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 fleet's lane signs in and seals through the core and the gateway, and the Share relay runs in the gateway (#911)

Deeef3f4d0b600c
diff --git a/cli/AGENTS.md b/cli/AGENTS.md
index 41e1e60c7..7ae3b2877 100644
--- a/cli/AGENTS.md
+++ b/cli/AGENTS.md
@@ -22,7 +22,11 @@ together. It is the core's own entry (`harness __run`); `src/cli.ts` is the CLI,
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.
+`GatewayPort` and hears it through `GatewayEvents` (`src/core/api.ts`), and never holds a key. The
+gateway also holds the other sockets that sign in to the backend for this machine's sake: the windows'
+sessions to the owner's other machines, the Share relay for a harness shared with this account
+(`WindowRelay`), and the fleet's lane's E2EE sessions, which the lane asks it to seal and open through
+`core.account.lane` (`src/gateway/lane.ts`).
## Where new code goes
diff --git a/cli/e2e/fleet.e2e.ts b/cli/e2e/fleet.e2e.ts
index dd0225752..3461af76f 100644
--- a/cli/e2e/fleet.e2e.ts
+++ b/cli/e2e/fleet.e2e.ts
@@ -94,6 +94,9 @@ describe('two machines in one fleet', () => {
expect(await routeSend(onA, agentId, 'sent from machine a')).toMatchObject({ ok: true })
expect((await started).payload?.userMessage).toBe('sent from machine a')
await ended
+ // Sealed by A's gateway, which holds A's identity: the relay never read the turn.
+ expect(backend.deviceSent.some((frame) => frame.machineId === b.machineId && (frame.payload as Record<string, unknown> | undefined)?.__e2e)).toBe(true)
+ expect(JSON.stringify(backend.deviceSent)).not.toContain('sent from machine a')
// Nothing tried to reach anywhere but the fake backend, and both daemons are the cores they started as.
for (const machine of [a, b]) {
expect(machine.daemon.log()).not.toMatch(/getaddrinfo|ENOTFOUND|autonomous\.ai/)
diff --git a/cli/e2e/gatewayProcess.e2e.ts b/cli/e2e/gatewayProcess.e2e.ts
index 671bff850..c87bea9ab 100644
--- a/cli/e2e/gatewayProcess.e2e.ts
+++ b/cli/e2e/gatewayProcess.e2e.ts
@@ -9,6 +9,7 @@
* Nothing here reaches beyond this machine: the daemon's every server setting is the fake backend's.
*/
import { execFileSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
import { mkdirSync } from 'node:fs'
import { join } from 'node:path'
import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
@@ -30,6 +31,15 @@ function gatewayPids(d: IsolatedDaemon): number[] {
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))
}
+/** ⌘K on a machine: its pick for a task (`route_task`), and its send to an agent anywhere (`route_send`). */
+async function routeTask(client: LocalClient, text: string): Promise<Record<string, any>> {
+ const requestId = randomUUID()
+ const answered = client.next((frame) => frame.type === 'route_result' && frame.payload?.requestId === requestId, 30_000, 'route_result')
+ client.send('route_task', { requestId, text })
+ return (await answered).payload as Record<string, any>
+}
+const routeSend = (client: LocalClient, agentId: string, text: string) => client.request('route_send', { agentId, text }, 30_000)
+
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
@@ -156,6 +166,65 @@ describe('the gateway in its own process', () => {
expect(machine.daemon.coresStarted()).toBe(1)
})
+ describe('the fleet\'s lane from A to B, sealed by A\'s 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('the relay never reads it; A\'s gateway killed costs the lane its sessions and nothing else, and they open again', async () => {
+ const f = await startFleet({ dialOnA: true, 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 })
+ const onA = await LocalClient.connect(f.a.daemon, { machineId: f.a.machineId })
+ clients.push(onB, onA)
+ const cwd = join(f.b.daemon.projectsDir, 'lane-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 dial on A opens A's lane; its session with B is the gateway's, under A's identity.
+ await f.dial!.greet()
+ await until('A to list the agent on B', async () => (await routeTask(onA, 'anything')).agentId === agentId || null, 60_000, 1_000)
+ expect(f.a.daemon.log()).toContain(`[device] device: e2e session ready ${f.b.machineId}`)
+ const started = onB.next(isTurn('turn_started', agentId), 30_000, 'turn_started on B')
+ expect(await routeSend(onA, agentId, 'sealed by the gateway')).toMatchObject({ ok: true })
+ expect((await started).payload?.userMessage).toBe('sealed by the gateway')
+ // What A's lane sent B went sealed: the relay saw sealed frames, and never the turn.
+ const toB = () => f.backend.deviceSent.filter((frame) => frame.machineId === f.b.machineId && !String(frame.type).startsWith('e2e_'))
+ expect(toB().some((frame) => (frame.payload as any)?.__e2e)).toBe(true)
+ expect(JSON.stringify(f.backend.deviceSent)).not.toContain('sealed by the gateway')
+
+ // A's gateway killed: the lane's sessions went with it. A's own window and agents never notice.
+ const before = gatewayPids(f.a.daemon)
+ expect(before).toHaveLength(1)
+ for (const pid of before) process.kill(pid, 'SIGKILL')
+ 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)
+ // The lane starts a session with B again, through the new gateway, and delivers.
+ const delivered = await until('A to deliver to B again', async () => {
+ if ((await routeTask(onA, 'anything')).agentId !== agentId) return null
+ const again = onB.next(isTurn('turn_started', agentId), 10_000, 'turn_started on B')
+ const sent = await routeSend(onA, agentId, 'after the gateway came back')
+ if (!sent.ok) { again.catch(() => {}); return null }
+ return (await again.catch(() => null))?.payload?.userMessage === 'after the gateway came back' ? sent : null
+ }, 120_000, 1_000)
+ expect(delivered).toMatchObject({ ok: true })
+ expect(f.a.daemon.log().split(`[device] device: e2e session ready ${f.b.machineId}`).length - 1).toBeGreaterThanOrEqual(2)
+ expect(JSON.stringify(f.backend.deviceSent)).not.toContain('after the gateway came back')
+ expect(f.a.daemon.coresStarted()).toBe(1)
+ })
+ })
+
describe('a window on this computer working on another machine, through the gateway', () => {
let fleet: Fleet | undefined
const clients: LocalClient[] = []
diff --git a/cli/e2e/harness/fakeBackend.ts b/cli/e2e/harness/fakeBackend.ts
index 842de953d..20d4d625f 100644
--- a/cli/e2e/harness/fakeBackend.ts
+++ b/cli/e2e/harness/fakeBackend.ts
@@ -79,6 +79,8 @@ export class FakeBackend {
readonly webSent = new Map<string, Frame[]>()
/** What reached each web client from its machine, as relayed (sealed), by connection id. */
readonly webReceived = new Map<string, Frame[]>()
+ /** What each device socket (a daemon's lane to its other machines) sent towards a machine, as sent. */
+ readonly deviceSent: Frame[] = []
private constructor(private readonly server: Server, readonly port: number) {}
@@ -399,6 +401,7 @@ export class FakeBackend {
// here: a node that is not connected leaves it unanswered, as the real hub does.
const machineId = frame.machineId && device.conns.has(frame.machineId) ? frame.machineId : device.selected
const connId = device.conns.get(machineId)
+ this.deviceSent.push(frame)
if (connId) this.sendNode(machineId, connId, frame)
}
diff --git a/cli/src/architecture.spec.ts b/cli/src/architecture.spec.ts
index 1a83e1dcb..6b6499746 100644
--- a/cli/src/architecture.spec.ts
+++ b/cli/src/architecture.spec.ts
@@ -206,7 +206,12 @@ const SERVICE_MAY_IMPORT: Record<string, string> = {
//
// 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 = 95_800
+//
+// Then at 95,340 in 416 (step 10, R3), from 95,757 in 420: the fleet's lane seals through the gateway, so
+// the session crypto it ran in the core's process (lib/e2ee/relayClient.ts and what it loads) is the
+// gateway's alone, and the Share relay (sharing/relay.ts) runs in the gateway with the relay's other sockets.
+// What a service in its own process may ask of the account (core/accountQueries.ts) is the 41 lines added.
+const CORE_CLOSURE_BUDGET = 95_440
/** 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[] = [
@@ -277,14 +282,10 @@ 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, 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/core.ts': 'step 8: Share seals its own frames with it',
+ 'lib/e2ee/machinePeers.ts': 'step 9: the fleet reads which machines are linked (their public keys, no credential), beside the dial',
'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/e2ee/store.ts': 'step 8: this machine\'s identity, for Share\'s owner',
'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',
@@ -320,7 +321,6 @@ const CORE_MAY_REACH: Record<string, string> = {
'sharing/grants.ts': 'step 8: the experimental host',
'sharing/owner.ts': 'step 8: the experimental host',
'sharing/protocol.ts': 'step 8: the experimental host',
- 'sharing/relay.ts': 'step 8: the experimental host',
'sharing/viewer.ts': 'step 8: the experimental host',
'teams/channels.ts': 'step 8: the experimental host',
'teams/client.ts': 'step 8: the experimental host',
diff --git a/cli/src/core/AGENTS.md b/cli/src/core/AGENTS.md
index b328df1c9..fb0192061 100644
--- a/cli/src/core/AGENTS.md
+++ b/cli/src/core/AGENTS.md
@@ -39,6 +39,9 @@ questions. Everything else is a service ([../services/AGENTS.md](../services/AGE
keeps of the viewers when they run in theirs. `workspacesLink.ts`: what the core tells workspaces in
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.
+ process tells the core. `agentQueries.ts`: what a service in its own process may ask of the agents;
+ `accountQueries.ts`: of the account (a token, and the fleet's lane's sealing), so it holds no credential.
`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.
+ the link's state and the remote clients it reads in line, the frames it hands over in the clear, a
+ window's sessions to another machine or a shared harness, and the fleet's lane's sealing
+ (`core.account.lane`).
diff --git a/cli/src/core/accountQueries.spec.ts b/cli/src/core/accountQueries.spec.ts
new file mode 100644
index 000000000..c02784709
--- /dev/null
+++ b/cli/src/core/accountQueries.spec.ts
@@ -0,0 +1,56 @@
+// The core's account, asked by a service in its own process: a token, and each step of the fleet's lane's
+// sealing, which the gateway does with this machine's identity. Nothing else is the account's to answer.
+import { describe, expect, it, vi } from 'vitest'
+import { AuthSessionError } from '../lib/authSession.js'
+import { answerAccountQuery } from './accountQueries.js'
+import type { LaneSeal } from './api.js'
+
+function account() {
+ const lane = {
+ hello: vi.fn(async (machineId: string) => ({ type: 'e2e_hello', machineId })),
+ welcome: vi.fn(async () => true),
+ rekey: vi.fn(async () => {}),
+ seal: vi.fn(async (_m: string, frame: Record<string, unknown>) => ({ frame: { ...frame, sealed: true } })),
+ open: vi.fn(async () => ({ unreadable: true as const })),
+ drop: vi.fn(),
+ } satisfies LaneSeal
+ return { accessToken: vi.fn(async () => 'token-1'), lane }
+}
+
+describe('the core\'s account, asked by a service in its own process', () => {
+ it('hands out a token, refreshed once when the asker says the last was refused, or the session\'s own refusal', async () => {
+ const a = account()
+ expect(await answerAccountQuery(a, 'access_token', {})).toEqual({ token: 'token-1' })
+ expect(a.accessToken).toHaveBeenLastCalledWith({ force: false })
+ await answerAccountQuery(a, 'access_token', { force: true, failedToken: 'old' })
+ expect(a.accessToken).toHaveBeenLastCalledWith({ force: true, failedToken: 'old' })
+ a.accessToken.mockRejectedValueOnce(new AuthSessionError('refresh refused', 'INVALID_REFRESH'))
+ expect(await answerAccountQuery(a, 'access_token', {})).toEqual({ code: 'INVALID_REFRESH', message: 'refresh refused' })
+ a.accessToken.mockRejectedValueOnce('down')
+ expect(await answerAccountQuery(a, 'access_token', {})).toEqual({ code: 'UNAVAILABLE', message: 'down' })
+ })
+
+ it('runs each step of the lane\'s sealing on the gateway\'s seal, as it was asked', async () => {
+ const a = account()
+ expect(await answerAccountQuery(a, 'lane', { op: 'hello', machineId: 'm2', peerPub: 'P' })).toEqual({ frame: { type: 'e2e_hello', machineId: 'm2' } })
+ expect(a.lane.hello).toHaveBeenCalledWith('m2', 'P')
+ expect(await answerAccountQuery(a, 'lane', { op: 'welcome', machineId: 'm2', payload: { e: 1 } })).toEqual({ ok: true })
+ expect(await answerAccountQuery(a, 'lane', { op: 'rekey', machineId: 'm2', payload: { r: 1 } })).toEqual({})
+ expect(a.lane.rekey).toHaveBeenCalledWith('m2', { r: 1 })
+ expect(await answerAccountQuery(a, 'lane', { op: 'seal', machineId: 'm2', frame: { type: 'message' } })).toEqual({ frame: { type: 'message', sealed: true } })
+ expect(await answerAccountQuery(a, 'lane', { op: 'open', machineId: 'm2', frame: [] })).toEqual({ unreadable: true })
+ expect(a.lane.open).toHaveBeenCalledWith('m2', {})
+ expect(await answerAccountQuery(a, 'lane', { op: 'drop', machineId: 'm2' })).toEqual({})
+ expect(a.lane.drop).toHaveBeenCalledWith('m2')
+ expect(await answerAccountQuery(a, 'lane', { op: 'reveal', machineId: 'm2' })).toEqual({ error: 'UNKNOWN_OP' })
+ a.lane.hello.mockRejectedValueOnce(new Error('the gateway could not start an E2EE session: it is not running'))
+ expect(await answerAccountQuery(a, 'lane', { op: 'hello', machineId: 7 })).toEqual({ error: 'the gateway could not start an E2EE session: it is not running' })
+ expect(a.lane.hello).toHaveBeenLastCalledWith('', '')
+ a.lane.hello.mockRejectedValueOnce('down')
+ expect(await answerAccountQuery(a, 'lane', { op: 'hello', machineId: 'm2' })).toEqual({ error: 'down' })
+ })
+
+ it('answers nothing that is not the account\'s', async () => {
+ expect(await answerAccountQuery(account(), 'agents', {})).toBeNull()
+ })
+})
diff --git a/cli/src/core/accountQueries.ts b/cli/src/core/accountQueries.ts
new file mode 100644
index 000000000..553d0d721
--- /dev/null
+++ b/cli/src/core/accountQueries.ts
@@ -0,0 +1,43 @@
+/**
+ * What a service in its own process may ask of the core's account (`service_query`, core/serviceLinks.ts),
+ * so that it holds no credential of its own (step 10, R3):
+ * - `access_token`: a token, refreshed once when the asker says the last one was refused with a 401;
+ * - `lane`: one step of the fleet's lane's sealing (`LaneSeal`), which the gateway does with this
+ * machine's E2EE identity (gateway/lane.ts).
+ * The core answers them only for the services it names (core/main.ts): the gateway asks for tokens, and the
+ * process that runs the fleet asks for both. The process's side is services/accountLink.ts.
+ */
+import type { CoreApi } from './api.js'
+
+type Payload = Record<string, unknown>
+type Account = Pick<CoreApi['account'], 'accessToken' | 'lane'>
+
+const text = (value: unknown): string => (typeof value === 'string' ? value : '')
+const record = (value: unknown): Payload => (value && typeof value === 'object' && !Array.isArray(value) ? value as Payload : {})
+
+/** The answer to an account query, or null for a query that is not the account's. A refused token comes back
+ * as the session's own error, so the asker can tell a session that is over from one that could not be
+ * refreshed just now. */
+export async function answerAccountQuery(account: Account, query: string, payload: Payload): Promise<Payload | null> {
+ if (query === 'access_token') {
+ try {
+ return { token: await account.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 !== 'lane') return null
+ const machineId = text(payload.machineId)
+ switch (payload.op) {
+ case 'hello':
+ try { return { frame: await account.lane.hello(machineId, text(payload.peerPub)) } } catch (error) {
+ return { error: error instanceof Error ? error.message : String(error) }
+ }
+ case 'welcome': return { ok: await account.lane.welcome(machineId, record(payload.payload)) }
+ case 'rekey': await account.lane.rekey(machineId, record(payload.payload)); return {}
+ case 'seal': return { ...await account.lane.seal(machineId, record(payload.frame)) }
+ case 'open': return { ...await account.lane.open(machineId, record(payload.frame)) }
+ case 'drop': account.lane.drop(machineId); return {}
+ default: return { error: 'UNKNOWN_OP' }
+ }
+}
diff --git a/cli/src/core/api.spec.ts b/cli/src/core/api.spec.ts
index ae09505c7..45b682b8e 100644
--- a/cli/src/core/api.spec.ts
+++ b/cli/src/core/api.spec.ts
@@ -1,11 +1,20 @@
import { describe, expect, it, vi } from 'vitest'
import { projectDisplayName, type RegisteredSession } from '../lib/registry.js'
-import { createCoreApi, emptyPorts, FLEET_FALLBACKS, MONITOR_OFF, resolveAgent, TEAMS_FALLBACKS, type CoreApiDeps } from './api.js'
+import { createCoreApi, emptyPorts, FLEET_FALLBACKS, LANE_OFF, MONITOR_OFF, resolveAgent, TEAMS_FALLBACKS, type CoreApiDeps } from './api.js'
import { FAIL } from './serviceHost.js'
const row = (agentId: string) => ({ agentId, sessionId: `s-${agentId}`, engine: 'claude', cwd: '/work/app' }) as RegisteredSession
describe('the core API services stand on', () => {
+ it('gives a service with no lane of the core\'s nothing to seal with, and never its frame back in the clear', async () => {
+ await expect(LANE_OFF.hello('m', 'pub')).rejects.toThrow(/no E2EE identity/)
+ expect(await LANE_OFF.welcome('m', {})).toBe(false)
+ await expect(LANE_OFF.rekey('m', {})).resolves.toBeUndefined()
+ expect(await LANE_OFF.seal('m', { type: 'message', payload: { text: 'hello' } })).toEqual({ lost: true })
+ expect(await LANE_OFF.open('m', { type: 'message' })).toEqual({ lost: true })
+ expect(LANE_OFF.drop('m')).toBeUndefined()
+ })
+
it('resolves an agent in a service\'s own copy as the registry does: by agent id, then session id', () => {
const agents = [{ ...row('a'), sessionId: '' }, row('b')]
expect(resolveAgent(agents, 'b')?.agentId).toBe('b')
@@ -36,6 +45,7 @@ describe('the core API services stand on', () => {
dshInstallStatus: vi.fn(),
mintGridName: vi.fn(async () => 'grid-1'),
accessToken: vi.fn(async () => 'token'),
+ lane: LANE_OFF,
privateGridName: vi.fn(async () => 'grid-1'),
machineName: vi.fn(() => 'Studio'),
runtimeProfile: vi.fn(() => null),
@@ -69,6 +79,7 @@ describe('the core API services stand on', () => {
expect(core.clients.gridModelsChanged).toBe(deps.gridModelsChanged)
expect(core.account.mintGridName).toBe(deps.mintGridName)
expect(core.account.accessToken).toBe(deps.accessToken)
+ expect(core.account.lane).toBe(deps.lane)
expect(core.account.privateGridName).toBe(deps.privateGridName)
expect(core.account.machineName).toBe(deps.machineName)
// What a device or another machine asks of an agent here: the core's own handlers, as they are.
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index c4d3e616f..1546ca4e2 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -108,8 +108,13 @@ export interface CoreApi {
/** The account's private grid name, minted and remembered by the backend; null when an older
* backend issues none. Bounded in time. */
mintGridName(): Promise<string | null>
- /** This machine's harness access token, for handing a sign-in to grid. Rejects when signed out. */
- accessToken(): Promise<string>
+ /** This machine's harness access token, for handing a sign-in to grid or dialling the fleet's lane.
+ * Rejects when signed out. `force` refreshes it (once, after a 401 for `failedToken`): the core's one
+ * session manager shares a refresh in flight with the backend link. */
+ accessToken(options?: { force?: boolean; failedToken?: string }): Promise<string>
+ /** The fleet's lane to the owner's other machines, sealed by the gateway with this machine's E2EE
+ * identity, which no service holds (`LaneSeal`). */
+ lane: LaneSeal
/** The account's private grid: the backend's word when it gave one, else what this machine works
* out (`lib/gridDerive.ts`); null when it has none. */
privateGridName(): Promise<string | null>
@@ -494,6 +499,41 @@ export interface GatewayEvents {
toWindows(frame: Record<string, unknown>): void
}
+/**
+ * The fleet's lane to the owner's other machines (device/deviceLink.ts), sealed by the gateway, which holds
+ * this machine's E2EE identity (the one `harness link connect` proves knowledge against). The lane keeps
+ * which machines have a session; the session itself, its keys and its counters, is the gateway's, one per
+ * machine. A gateway that restarted holds none and says so (`lost`): the lane then starts one again, and
+ * sends nothing for that machine in the clear meanwhile.
+ */
+export interface LaneSeal {
+ /** Start a session with a linked machine, pinned to the key `harness link connect` left for it (`peerPub`,
+ * base64): the hello to send it, in the clear. Replaces any session that machine had. Rejects when the
+ * gateway cannot start one (it is not running). */
+ hello(machineId: string, peerPub: string): Promise<Record<string, unknown>>
+ /** The machine's welcome to that hello: true once the session is up. */
+ welcome(machineId: string, payload: Record<string, unknown>): Promise<boolean>
+ /** The machine's new keys, for a session that is up. */
+ rekey(machineId: string, payload: Record<string, unknown>): Promise<void>
+ /** A frame for the machine, sealed as its session seals that type (a type it does not seal goes as it is). */
+ seal(machineId: string, frame: Record<string, unknown>): Promise<LaneSealed>
+ /** A sealed frame from the machine, opened; `unreadable` when it does not open (stale, forged, garbled). */
+ open(machineId: string, frame: Record<string, unknown>): Promise<LaneOpened>
+ /** The lane is done with the machine's session. */
+ drop(machineId: string): void
+}
+export type LaneSealed = { frame: Record<string, unknown> } | { lost: true }
+export type LaneOpened = { frame: Record<string, unknown> } | { unreadable: true } | { lost: true }
+/** A service with no lane of the core's: it starts no session and seals nothing, never sends in the clear. */
+export const LANE_OFF: LaneSeal = {
+ hello: () => Promise.reject(new Error('no lane: this process holds no E2EE identity')),
+ welcome: async () => false,
+ rekey: async () => {},
+ seal: async () => ({ lost: true }),
+ open: async () => ({ lost: true }),
+ drop: () => {},
+}
+
/** An HTTP answer for the daemon's own routes (`harness pair`, `harness devices`, …), as the hook server sends it. */
export interface HttpAnswer {
status: number
@@ -561,6 +601,8 @@ export interface GatewayOps {
/** 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
+ /** The fleet's lane's sessions (`core.account.lane`). */
+ lane: LaneSeal
}
/** A window on this computer working on another of the owner's machines, through the relay: what the
@@ -581,6 +623,12 @@ export interface WindowRelay {
onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
invalidate(machineId: string): void
invalidateIsolated(machineId: string): void
+ /** A window here watching, read-only, a harness someone shared with this account (sharing/relay.ts, the
+ * Share relay's own socket, `/api/observer-ws`). Fails with the close the window gets: 4403 when the
+ * share ended or was never there, 1013 when it could not be reached just now. The gateway's has it; a
+ * bare pool of sessions to other machines (lib/remoteRelay.ts) does not, and shares nothing. */
+ acquireShare?(machineId: string, shareId: string, sink: WindowRelaySink,
+ onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession>
}
/** Each port is filled by the service that owns it when that service starts, and is null while the
@@ -615,6 +663,7 @@ export interface CoreApiDeps {
dshInstallStatus: CoreApi['clients']['dshInstallStatus']
mintGridName: CoreApi['account']['mintGridName']
accessToken: CoreApi['account']['accessToken']
+ lane: CoreApi['account']['lane']
privateGridName: CoreApi['account']['privateGridName']
machineName: CoreApi['account']['machineName']
runtimeProfile: CoreApi['agents']['runtimeProfile']
@@ -626,7 +675,7 @@ export interface CoreApiDeps {
export function createCoreApi({
dataDir, registry, stoppedAgents, databaseHistory, externalSessions, openSessions, syncSession, runtimeModels, viewerChanged,
- gridNamed, gridModelsChanged, dshInstallStatus, mintGridName, accessToken, privateGridName, machineName,
+ gridNamed, gridModelsChanged, dshInstallStatus, mintGridName, accessToken, lane, privateGridName, machineName,
runtimeProfile, setRuntime, fork, turns, questions, terminals = TERMINALS_OFF,
}: CoreApiDeps): CoreApi {
return {
@@ -650,7 +699,7 @@ export function createCoreApi({
questions,
transcripts: { databaseHistory },
external: { sessions: externalSessions, open: openSessions },
- account: { mintGridName, accessToken, privateGridName, machineName },
+ account: { mintGridName, accessToken, lane, privateGridName, machineName },
clients: { viewerChanged, gridNamed, gridModelsChanged, dshInstallStatus },
}
}
diff --git a/cli/src/core/gatewayLink.spec.ts b/cli/src/core/gatewayLink.spec.ts
index 4b982a52b..b74cd8f47 100644
--- a/cli/src/core/gatewayLink.spec.ts
+++ b/cli/src/core/gatewayLink.spec.ts
@@ -2,8 +2,8 @@ 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'
+import type { GatewayEvents, LaneSeal } from './api.js'
+import { createGatewayLink, GATEWAY_BUFFER_LIMIT, LANE_WAIT_MS, laneOf, 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) })
@@ -251,6 +251,55 @@ describe('the gateway in its own process, as the core sees it', () => {
expect(await link.ops.wifi({ op: 'revoke', id: 'x' })).toMatchObject({ refused: { code: 'UNAVAILABLE' } })
})
+ it('carries the fleet\'s lane to the gateway\'s sessions, every step a call in order, and never a frame back unsealed', async () => {
+ let answer: Record<string, unknown> = {}
+ const { link, call } = setup({ call: async () => answer })
+ const lane = link.ops.lane
+ answer = { frame: { type: 'e2e_hello', payload: { identityPub: 'P' } } }
+ expect(await lane.hello('m2', 'PEER')).toEqual({ type: 'e2e_hello', payload: { identityPub: 'P' } })
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.lane, { op: 'hello', machineId: 'm2', peerPub: 'PEER' }, LANE_WAIT_MS)
+ answer = { ok: true }
+ expect(await lane.welcome('m2', { ephPub: 'E' })).toBe(true)
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.lane, { op: 'welcome', machineId: 'm2', payload: { ephPub: 'E' } }, LANE_WAIT_MS)
+ await lane.rekey('m2', { epoch: 'x' })
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.lane, { op: 'rekey', machineId: 'm2', payload: { epoch: 'x' } }, LANE_WAIT_MS)
+ answer = { frame: { type: 'message', payload: { __e2e: {} } } }
+ expect(await lane.seal('m2', { type: 'message', payload: { content: 'hi' } })).toEqual({ frame: { type: 'message', payload: { __e2e: {} } } })
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.lane, { op: 'seal', machineId: 'm2', frame: { type: 'message', payload: { content: 'hi' } } }, LANE_WAIT_MS)
+ answer = { frame: { type: 'agents_list_result', payload: {} } }
+ expect(await lane.open('m2', { type: 'agents_list_result' })).toEqual({ frame: { type: 'agents_list_result', payload: {} } })
+ answer = { unreadable: true }
+ expect(await lane.open('m2', { type: 'agents_list_result' })).toEqual({ unreadable: true })
+ lane.drop('m2')
+ expect(call).toHaveBeenLastCalledWith(GATEWAY_CALLS.lane, { op: 'drop', machineId: 'm2' }, LANE_WAIT_MS)
+ // The gateway not there (or failed): no session is started, nothing is sealed or opened.
+ answer = { error: 'SERVICE_UNAVAILABLE' }
+ await expect(lane.hello('m2', 'PEER')).rejects.toThrow(/not running/)
+ expect(await lane.welcome('m2', {})).toBe(false)
+ expect(await lane.seal('m2', { type: 'message', payload: { content: 'hi' } })).toEqual({ lost: true })
+ expect(await lane.open('m2', { type: 'agents_list_result' })).toEqual({ lost: true })
+ })
+
+ it('hands the core\'s services the gateway\'s lane as it is when each is called', async () => {
+ const one = { hello: vi.fn(async () => ({ type: 'e2e_hello' })), welcome: vi.fn(async () => true), rekey: vi.fn(async () => {}),
+ seal: vi.fn(async () => ({ lost: true as const })), open: vi.fn(async () => ({ unreadable: true as const })), drop: vi.fn() } satisfies LaneSeal
+ let current: LaneSeal = one
+ const lane = laneOf(() => current)
+ expect(await lane.hello('m', 'P')).toEqual({ type: 'e2e_hello' })
+ expect(await lane.welcome('m', { a: 1 })).toBe(true)
+ await lane.rekey('m', { b: 2 })
+ expect(await lane.seal('m', { type: 't' })).toEqual({ lost: true })
+ expect(await lane.open('m', { type: 't' })).toEqual({ unreadable: true })
+ lane.drop('m')
+ expect(one.hello).toHaveBeenCalledWith('m', 'P')
+ expect(one.welcome).toHaveBeenCalledWith('m', { a: 1 })
+ expect(one.rekey).toHaveBeenCalledWith('m', { b: 2 })
+ expect(one.drop).toHaveBeenCalledWith('m')
+ const two = { ...one, seal: vi.fn(async (_m: string, frame: Record<string, unknown>) => ({ frame })) }
+ current = two
+ expect(await lane.seal('m', { type: 'later' })).toEqual({ frame: { type: 'later' } })
+ })
+
it('tells the gateway what the core learns for it', () => {
const { link, sent } = setup()
link.connected()
@@ -272,10 +321,14 @@ describe('the gateway in its own process, as the core sees it', () => {
// 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')
+ // The harnesses shared with this account, which the Share relay looks a share up in before it dials.
+ expect(await link.answer('backend', { method: 'GET', path: '/api/harness-shares' })).toEqual({ status: 200, body: { data: { seen: {} } } })
+ expect(backend).toHaveBeenLastCalledWith('GET', '/api/harness-shares')
+ expect(await link.answer('backend', { method: 'GET', path: '/api/harness-shares/x' })).toEqual({ error: 'UNKNOWN_QUERY' })
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)
+ expect(backend).toHaveBeenCalledTimes(2)
})
})
@@ -344,6 +397,23 @@ describe('a window here working on another machine, through the gateway', () =>
await expect(refused).rejects.toMatchObject({ closeCode: 4403, message: 'relay failed' })
})
+ it('watches a harness shared with this account through the gateway, and is told 4403 when the share ended', async () => {
+ const { link, sent } = setup()
+ // The gateway not there: out of reach just now, as the Share relay said when it could not dial.
+ await expect(link.windowRelay.acquireShare!('owner', 'share-1', sink(), vi.fn())).rejects.toMatchObject({ closeCode: WINDOW_GATEWAY_GONE })
+ link.connected()
+ const window = sink()
+ const watching = link.windowRelay.acquireShare!('owner', 'share-1', window, vi.fn())
+ expect(sent.at(-1)).toEqual({ kind: 'windowOpen', id: 'window-1', machineId: 'owner', share: 'share-1' })
+ link.notice({ kind: 'windowOpened', id: 'window-1' })
+ await watching
+ link.notice({ kind: 'windowFrame', id: 'window-1', frame: { type: 'connected', payload: { readOnly: true } } })
+ expect(window.sendFrame).toHaveBeenCalledWith({ type: 'connected', payload: { readOnly: true } })
+ const ended = link.windowRelay.acquireShare!('owner', 'share-2', sink(), vi.fn())
+ link.notice({ kind: 'windowFailed', id: 'window-2', code: 4403, reason: 'Sharing ended or invitation expired' })
+ await expect(ended).rejects.toEqual(new RelayConnectError('Sharing ended or invitation expired', 4403))
+ })
+
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 })
diff --git a/cli/src/core/gatewayLink.ts b/cli/src/core/gatewayLink.ts
index 2b71d62d8..6a7bb934b 100644
--- a/cli/src/core/gatewayLink.ts
+++ b/cli/src/core/gatewayLink.ts
@@ -19,8 +19,10 @@
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'
import { decodeTerminalLocal, encodeTerminalLocal } from '../lib/terminalBinary.js'
+import { answerAccountQuery } from './accountQueries.js'
+import { LANE_OFF } from './api.js'
import type {
- BackendNotice, GatewayEvents, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer,
+ BackendNotice, GatewayEvents, GatewayOps, GatewayPort, GatewayRefusal, GatewayStatus, HttpAnswer, LaneSeal,
RemoteClient, RemoteRole, RemoteTransport, WindowRelay, WindowRelaySession, WindowRelaySink,
} from './api.js'
import type { ServiceFrame } from './serviceLinks.js'
@@ -55,6 +57,10 @@ 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
+/** How long the fleet's lane waits on the gateway to seal or open a frame. The frames behind it wait too,
+ * in order; a gateway that has not answered in this long is hung, and the master ends it soon after. */
+export const LANE_WAIT_MS = 5_000
+
const UNAVAILABLE: HttpAnswer = { status: 503, body: { error: 'GATEWAY_UNAVAILABLE' } }
interface Window {
@@ -139,6 +145,32 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
return typeof answer.status === 'number' ? { status: answer.status, body: record(answer.body) } : UNAVAILABLE
}
+ /**
+ * The fleet's lane's sessions, in the gateway (gateway/lane.ts). Every one of them is a call, the lane's
+ * drop too, so the gateway takes them in the order the lane made them. A gateway that is not there
+ * starts no session and seals nothing: the lane hears `lost`, never its frame back as it was.
+ */
+ const lane = (op: string, payload: Record<string, unknown> = {}) => deps.call(GATEWAY_CALLS.lane, { ...payload, op }, LANE_WAIT_MS)
+ const laneOps: LaneSeal = {
+ hello: async (machineId, peerPub) => {
+ const answer = await lane('hello', { machineId, peerPub })
+ if (answer.frame && typeof answer.frame === 'object') return record(answer.frame)
+ throw new Error('the gateway could not start an E2EE session: it is not running')
+ },
+ welcome: async (machineId, payload) => (await lane('welcome', { machineId, payload })).ok === true,
+ rekey: async (machineId, payload) => { await lane('rekey', { machineId, payload }) },
+ seal: async (machineId, frame) => {
+ const answer = await lane('seal', { machineId, frame })
+ return answer.frame && typeof answer.frame === 'object' ? { frame: record(answer.frame) } : { lost: true }
+ },
+ open: async (machineId, frame) => {
+ const answer = await lane('open', { machineId, frame })
+ if (answer.frame && typeof answer.frame === 'object') return { frame: record(answer.frame) }
+ return answer.unreadable === true ? { unreadable: true } : { lost: true }
+ },
+ drop: (machineId) => { void lane('drop', { machineId }) },
+ }
+
const ops: GatewayOps = {
status: async (): Promise<GatewayStatus> => {
const answer = await deps.call(GATEWAY_CALLS.status, {}, 2_000)
@@ -178,16 +210,21 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
revokeIdentity: (identity) => { send('revokeIdentity', { identity }) },
account: (next) => { send('account', { account: next }) },
reachable: (machineIds) => { reachable = machineIds; send('reachable', { machineIds }) },
+ lane: laneOps,
}
- const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
- sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
+ /** A window's session through the gateway: to another of the owner's machines, or to a harness shared
+ * with this account (`share`). */
+ const openWindow = (open: 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 })
+ send('windowOpen', { ...open, id })
})
+ const open = (isolated: boolean) => (machineId: string, autonomousEnv: string, selectFrame: Record<string, unknown>,
+ sink: WindowRelaySink, onClosed: (code: number, reason: string) => void): Promise<WindowRelaySession> =>
+ openWindow({ machineId, autonomousEnv, frame: selectFrame, isolated }, sink, onClosed)
const sessionOf = (id: string): WindowRelaySession => ({
send: async (frame) => { send('windowSend', { id, frame }) },
sendBinary: async (clear) => {
@@ -202,6 +239,7 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
acquireIsolated: open(true),
invalidate: (machineId) => { send('windowInvalidate', { machineId, isolated: false }) },
invalidateIsolated: (machineId) => { send('windowInvalidate', { machineId, isolated: true }) },
+ acquireShare: (machineId, shareId, sink, onClosed) => openWindow({ machineId, share: shareId }, sink, onClosed),
}
/** A window's connection ended, from the gateway's side or because the gateway went. */
@@ -302,20 +340,16 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
}
/**
- * 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
+ * What the gateway asks the core (`service_query`): a token to dial with, the device key log's reads of
+ * the backend, and the harnesses shared with this account (the Share relay finds a share among them
+ * before it dials). 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')) {
+ // The gateway is the lane's seal, never a lane of its own: it is answered tokens, and no lane step.
+ if (query === 'access_token') return (await answerAccountQuery({ accessToken: (options) => deps.tokens.accessToken(options), lane: LANE_OFF }, query, payload))!
+ if (query === 'backend' && payload.method === 'GET' && (text(payload.path).startsWith('/api/device-keys') || payload.path === '/api/harness-shares')) {
return { ...await deps.backend('GET', text(payload.path)) }
}
return { error: 'UNKNOWN_QUERY' }
@@ -354,3 +388,16 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
}
export type GatewayLink = ReturnType<typeof createGatewayLink>
+
+/** The lane's sessions as the core hands them to its services (`core.account.lane`): read from the gateway
+ * each time, because the core's API is built before the gateway is started. */
+export function laneOf(gateway: () => LaneSeal): LaneSeal {
+ return {
+ hello: (machineId, peerPub) => gateway().hello(machineId, peerPub),
+ welcome: (machineId, payload) => gateway().welcome(machineId, payload),
+ rekey: (machineId, payload) => gateway().rekey(machineId, payload),
+ seal: (machineId, frame) => gateway().seal(machineId, frame),
+ open: (machineId, frame) => gateway().open(machineId, frame),
+ drop: (machineId) => gateway().drop(machineId),
+ }
+}
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 090d703ff..e7d36bd6c 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -13,7 +13,6 @@ import { createDeviceStore, deviceStoreAgents } from '../lib/autonomous-device/s
import { HarnessShareOwner } from '../sharing/owner.js'
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 { runningDevicePart, startDevicePart } from '../lib/autonomous-device/parts.js'
import { readFileSync, writeFileSync, openSync, existsSync, rmSync, statSync } from 'fs'
@@ -148,7 +147,7 @@ import { saveDaemonPort } from '../lib/daemonEndpoint.js'
import { publishHookRoute } from '../lib/hookRoutes.js'
import { commandBarService } from '../lib/commandBar.js'
import { BackendSocket, isLocalClientId } from '../backendSocket.js'
-import { createGatewayLink } from './gatewayLink.js'
+import { createGatewayLink, laneOf } 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'
@@ -673,6 +672,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const externalEngines = externalProviders()
const externalSessions = new ExternalSessions({ providers: externalEngines, excluded: [env.ADAPTER_DATA_DIR], log: (line) => console.warn(line) })
const openSessions = new OpenSessions({ providers: externalEngines, log: (line) => console.warn(line) })
+ // The core's one session manager: the backend link, the gateway's dials and the fleet's lane all take
+ // their tokens from it, so a refresh in flight is shared rather than raced.
+ const auth = new AuthSessionManager(backendHttpBase())
// The core's side of the boundary its services stand on, and the ports it reaches them through (core/api.ts).
const coreApi = createCoreApi({
terminals: createTerminalOpener({ tmuxBackend, registry, announceSession, blocksFolder: (cwd) => !!backendRef?.purgeAgentService?.blocksFolder(cwd) }),
@@ -700,7 +702,10 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const { headers } = await controlPlaneAuth()
return (await postJson<{ gridName?: string }>('/api/grid/name', {}, headers, AbortSignal.timeout(GRID_MINT_TIMEOUT_MS))).gridName ?? null
},
- accessToken: () => new AuthSessionManager(backendHttpBase()).accessToken(),
+ accessToken: (options) => auth.accessToken(options),
+ // The fleet's lane's sessions are the gateway's, which holds this machine's E2EE identity; it starts
+ // below, before the fleet that seals through it.
+ lane: laneOf(() => gatewayOps.lane),
// What a device or another machine asks of an agent here: the SAME handlers the backend socket
// drives, called directly — the slash-command adaptation and the turn and question plumbing live there.
runtimeProfile: (session) => runtimeProfiles.selectedModel(session),
@@ -772,7 +777,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
* control plane is reachable again, which is precisely what an earlier attempt may have lacked. */
let fullReconcile: (announceDevice?: boolean) => Promise<void> = async () => {}
- const auth = new AuthSessionManager(backendHttpBase())
// The account's machine id when this computer is signed in; its own durable computer id when it is
// 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
@@ -1446,11 +1450,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
publish: (method, path, body) => proxyBackend(method, path, body),
watchViewer: (id, send) => sharedViewers.watch(id, send),
})
- const shareRelay = new HarnessShareRelay(auth, env.BACKEND_WS_URL, autonomousEnv, async () => {
- const result = await proxyBackend('GET', '/api/harness-shares')
- if (result.status !== 200) throw new Error('Shared harnesses are temporarily unavailable.')
- return ((result.body as { data?: { machines?: SharedMachineReference[] } }).data?.machines ?? [])
- })
/**
* The machine list a signed-out daemon answers with: this computer, alone.
@@ -1729,10 +1728,6 @@ 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}`)
- // 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()
// 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()))
@@ -1773,7 +1768,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
const localWsServer = attachLocalWsServer(hookServer, {
localSocketServer: localSocket?.server ?? null,
- shareRelay,
services: serviceLinks,
onSelectionReply: (connId, machineId, payload) => devices('window', () => windowSelection.reply(connId, machineId, payload)),
onVisitReply: (connId, machineId, payload) => devices('window', () => windowVisit.reply(connId, machineId, payload)),
@@ -2455,7 +2449,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// The FIXED hook port, released before the successor binds it (no fallback → EADDRINUSE otherwise).
// Process-owned agents stay in the persisted registry and are revalidated by its first discovery passes.
['the hook connections', () => (hookServer as unknown as { closeAllConnections?: () => void }).closeAllConnections?.()],
- ['the share relay', () => shareRelay.close()], ['the shared viewers', () => sharedViewers.stop()],
+ ['the shared viewers', () => sharedViewers.stop()],
['the local websocket', () => localWsServer.close()], ['the hook server', () => hookServer.close()],
['the local socket', () => localSocket?.close()], ['Codex activity', () => codexActivity.close()],
['the voice router', () => shutdownVoiceRouter()],
@@ -2504,7 +2498,6 @@ async function runForeground(session: AuthSession | null): Promise<void> {
normalizers.stopPollers()
await cursorDiscovery.stop()
await watcher.stop()
- shareRelay.close()
sharedViewers.stop()
// The data folder's socket first: a successor waiting for this core to leave (lib/localSocket.ts) can
// start as soon as it is gone, whatever the clients below take to close.
@@ -2561,8 +2554,8 @@ async function runForeground(session: AuthSession | null): Promise<void> {
serviceHost.start('fleet', (core, started) => {
startFleet(core, started, {
machines: machineListCache, guestMachines: guestMachinesBody, computerId, machineId: () => backend.machineId,
- machineName: dialMachineName, desk: () => appPaneAgents, auth,
- autonomousEnv: readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV, identity: relayIdentityStore.getIdentity(),
+ machineName: dialMachineName, desk: () => appPaneAgents,
+ autonomousEnv: readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV,
})
}, coreApi, FLEET_FALLBACKS)
diff --git a/cli/src/device/deviceLink.spec.ts b/cli/src/device/deviceLink.spec.ts
new file mode 100644
index 000000000..e66036592
--- /dev/null
+++ b/cli/src/device/deviceLink.spec.ts
@@ -0,0 +1,250 @@
+/**
+ * The fleet's lane (deviceLink.ts) against a fake `/api/device-ws` on 127.0.0.1, with its tokens from the
+ * core and its E2EE sessions in the gateway (step 10, R3; gateway/lane.ts holds the real ones, with real
+ * keys, in lane.spec.ts). It held this machine's identity and sealed in line before; each test here fails
+ * if a rule of the lane's was lost in the move to sealing through the gateway, a round trip away:
+ *
+ * - a frame for a linked machine is never sent in the clear: one the gateway cannot seal (it restarted
+ * under the lane) goes nowhere, and the next call starts a session again;
+ * - what goes out goes in the order it was handed, and what comes in is read in the order it came,
+ * however long the gateway takes over each;
+ * - the handshake goes in the clear, tagged with its machine; what does not open is never passed on;
+ * - the lane signs in with the core's token, with one forced refresh after a 401;
+ * - the lane's sessions end at the gateway when the lane does.
+ */
+import type { IncomingMessage } from 'node:http'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { WebSocketServer, type WebSocket } from 'ws'
+import type { LaneOpened, LaneSeal, LaneSealed } from '../core/api.js'
+import { DeviceLink, type DeviceFrame } from './deviceLink.js'
+
+const LINKED = 'linked-machine'
+const CLOUD = 'cloud-machine'
+type Frame = Record<string, unknown>
+
+/** The fake backend's device socket: what the lane sent, and a way to send it frames. */
+async function fakeDeviceWs(opts: { refuseToken?: string } = {}) {
+ const received: Frame[] = []
+ const tokens: string[] = []
+ let socket: WebSocket | null = null
+ const wss = new WebSocketServer({
+ port: 0, host: '127.0.0.1',
+ handleProtocols: (protocols) => [...protocols][0] ?? false,
+ verifyClient: (info: { req: IncomingMessage }, done: (ok: boolean, code?: number) => void) => {
+ const token = String(info.req.headers['sec-websocket-protocol'] ?? '')
+ tokens.push(token)
+ done(token !== opts.refuseToken, 401)
+ },
+ })
+ await new Promise<void>((resolve) => wss.once('listening', () => resolve()))
+ const listeners = new Set<(frame: Frame) => void>()
+ wss.on('connection', (ws) => {
+ socket = ws
+ ws.on('message', (raw) => {
+ const frame = JSON.parse(raw.toString()) as Frame
+ received.push(frame)
+ for (const listener of listeners) listener(frame)
+ })
+ })
+ const port = (wss.address() as { port: number }).port
+ return {
+ url: `ws://127.0.0.1:${port}`,
+ received,
+ tokens,
+ /** Frames for machines, as the lane sent them: its own control frames left out. */
+ forMachines: () => received.filter((frame) => frame.type !== 'device_hello' && frame.type !== 'machines_watch' && frame.type !== 'ping'),
+ send: (frame: Frame) => socket?.send(JSON.stringify(frame)),
+ on: (listener: (frame: Frame) => void) => { listeners.add(listener) },
+ close: () => new Promise<void>((resolve) => { for (const client of wss.clients) client.terminate(); wss.close(() => resolve()) }),
+ }
+}
+
+/** The gateway's side of the lane, faked: each seal marks the frame, and a test can make it slow or lost. */
+function fakeSeal() {
+ const sealed = vi.fn(async (_machineId: string, frame: Frame): Promise<LaneSealed> => ({ frame: { ...frame, payload: { __e2e: { of: frame.type } } } }))
+ const opened = vi.fn(async (_machineId: string, frame: Frame): Promise<LaneOpened> =>
+ ({ frame: { ...frame, payload: { opened: (frame.payload as { __e2e: unknown }).__e2e } } }))
+ const seal = {
+ hello: vi.fn(async (machineId: string, peerPub: string) => ({ type: 'e2e_hello', payload: { for: machineId, peerPub } })),
+ welcome: vi.fn(async () => true),
+ rekey: vi.fn(async () => {}),
+ seal: sealed,
+ open: opened,
+ drop: vi.fn(),
+ } satisfies LaneSeal
+ return seal
+}
+
+const links: DeviceLink[] = []
+const servers: Array<{ close(): Promise<void> }> = []
+afterEach(async () => {
+ for (const link of links.splice(0)) link.stop()
+ for (const server of servers.splice(0)) await server.close()
+})
+
+async function lane(over: { refuseToken?: string; auth?: { accessToken(options?: { force?: boolean; failedToken?: string }): Promise<string> } } = {}) {
+ const server = await fakeDeviceWs({ refuseToken: over.refuseToken })
+ servers.push(server)
+ const seal = fakeSeal()
+ const lines: string[] = []
+ const auth = over.auth ?? { accessToken: vi.fn(async () => 'token-1') }
+ const link = new DeviceLink({
+ auth, backendWsBase: server.url, computerId: 'computer-1', autonomousEnv: 'test', seal,
+ peer: (machineId) => (machineId === LINKED ? { machineId, pub: 'LINKED-PUB', label: 'linked', linkedAt: 1 } as never : null),
+ localMachineId: () => 'this-machine',
+ log: (line) => { lines.push(line) },
+ })
+ links.push(link)
+ // The far machine answers every hello with a welcome, as a linked daemon does.
+ server.on((frame) => {
+ if (frame.type === 'e2e_hello') server.send({ type: 'e2e_welcome', machineId: frame.machineId, payload: { ephPub: 'E' } })
+ })
+ const heard: DeviceFrame[] = []
+ link.onFrame((frame) => { heard.push(frame) })
+ return { server, seal, link, lines, auth, heard }
+}
+
+const until = async (what: string, check: () => boolean, ms = 5_000): Promise<void> => {
+ const deadline = Date.now() + ms
+ while (!check()) {
+ if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`)
+ await new Promise((resolve) => setTimeout(resolve, 10))
+ }
+}
+
+describe('the fleet\'s lane, sealed by the gateway', () => {
+ it('sends a linked machine nothing in the clear: what the gateway cannot seal goes nowhere, and a session starts again', async () => {
+ const { server, seal, link, lines } = await lane()
+ await link.online()
+ await link.sendSealed({ type: 'message', machineId: LINKED, payload: { content: 'the owner typed this' } })
+ await until('the sealed message', () => server.forMachines().some((frame) => frame.type === 'message'))
+ // The handshake went first, in the clear and tagged with its machine; the message sealed after it.
+ expect(server.forMachines().map((frame) => frame.type)).toEqual(['e2e_hello', 'message'])
+ expect(server.forMachines()[0]).toEqual({ type: 'e2e_hello', machineId: LINKED, payload: { for: LINKED, peerPub: 'LINKED-PUB' } })
+ expect(seal.welcome).toHaveBeenCalledWith(LINKED, { ephPub: 'E' })
+ // The gateway restarted under the lane: it holds no session, and the frame is dropped, never sent as is.
+ seal.seal.mockResolvedValueOnce({ lost: true })
+ await link.sendSealed({ type: 'message', machineId: LINKED, payload: { content: 'never in the clear' } })
+ await until('the drop to be said', () => lines.some((line) => line.includes('its E2EE session is gone')))
+ // And the next call starts a session again before it sends.
+ await link.sendSealed({ type: 'message', machineId: LINKED, payload: { content: 'after the restart' } })
+ await until('the second sealed message', () => server.forMachines().filter((frame) => frame.type === 'message').length === 2)
+ expect(seal.hello).toHaveBeenCalledTimes(2)
+ expect(server.forMachines().map((frame) => frame.type)).toEqual(['e2e_hello', 'message', 'e2e_hello', 'message'])
+ expect(JSON.stringify(server.received)).not.toContain('the owner typed this')
+ expect(JSON.stringify(server.received)).not.toContain('never in the clear')
+ expect(JSON.stringify(server.received)).not.toContain('after the restart')
+ })
+
+ it('sends a frame that would be sealed nowhere while the gateway cannot start a session', async () => {
+ const { server, seal, link, lines } = await lane()
+ await link.online()
+ seal.hello.mockRejectedValueOnce(new Error('the gateway could not start an E2EE session: it is not running'))
+ await link.sendSealed({ type: 'message', machineId: LINKED, payload: { content: 'never in the clear' } })
+ expect(lines.some((line) => line.includes('dropped message for linked-machine') && line.includes('not running'))).toBe(true)
+ await new Promise((resolve) => setTimeout(resolve, 50))
+ expect(server.forMachines()).toEqual([])
+ })
+
+ it('sends in the order it was handed, however long the gateway takes to seal', async () => {
+ const { server, seal, link } = await lane()
+ await link.online()
+ await link.establish(LINKED)
+ let release!: () => void
+ seal.seal.mockImplementationOnce(async (_m, frame) => {
+ await new Promise<void>((resolve) => { release = resolve })
+ return { frame: { ...frame, payload: { __e2e: { of: frame.type } } } }
+ })
+ link.send({ type: 'first', machineId: LINKED, payload: {} })
+ // A frame for a machine the backend runs itself is never sealed: it waits its turn all the same.
+ link.send({ type: 'second', machineId: CLOUD, payload: {} })
+ await new Promise((resolve) => setTimeout(resolve, 50))
+ expect(server.forMachines().map((frame) => frame.type)).toEqual(['e2e_hello'])
+ release()
+ await until('both frames', () => server.forMachines().length === 3)
+ expect(server.forMachines().map((frame) => frame.type)).toEqual(['e2e_hello', 'first', 'second'])
+ expect(server.forMachines()[1].payload).toEqual({ __e2e: { of: 'first' } })
+ expect(server.forMachines()[2].payload).toEqual({})
+ })
+
+ it('reads what comes in in order, opens only what was sealed, and never passes on what does not open', async () => {
+ const { server, seal, link, heard, lines } = await lane()
+ await link.online()
+ await link.establish(LINKED)
+ let release!: () => void
+ seal.open.mockImplementationOnce(async (_m, frame) => {
+ await new Promise<void>((resolve) => { release = resolve })
+ return { frame: { ...frame, payload: { opened: 'first' } } }
+ })
+ server.send({ type: 'card', machineId: LINKED, payload: { __e2e: { n: 1 } } })
+ server.send({ type: 'status', machineId: LINKED, payload: { plain: true } })
+ await new Promise((resolve) => setTimeout(resolve, 50))
+ expect(heard).toEqual([])
+ release()
+ await until('both frames', () => heard.length === 2)
+ expect(heard).toEqual([
+ { type: 'card', machineId: LINKED, payload: { opened: 'first' } },
+ { type: 'status', machineId: LINKED, payload: { plain: true } },
+ ])
+ // Only the sealed one went to the gateway.
+ expect(seal.open).toHaveBeenCalledTimes(1)
+ seal.open.mockResolvedValueOnce({ unreadable: true })
+ server.send({ type: 'card', machineId: LINKED, payload: { __e2e: { n: 2 } } })
+ await until('the drop to be said', () => lines.some((line) => line === 'device: could not decrypt card — dropped'))
+ // The gateway lost the session: nothing passed on, and the next call starts one again.
+ seal.open.mockResolvedValueOnce({ lost: true })
+ server.send({ type: 'card', machineId: LINKED, payload: { __e2e: { n: 3 } } })
+ await until('the loss to be said', () => lines.some((line) => line.includes('the E2EE session with linked-machine is gone')))
+ expect(heard).toHaveLength(2)
+ await link.establish(LINKED)
+ expect(seal.hello).toHaveBeenCalledTimes(2)
+ })
+
+ it('asks a linked machine through the gateway both ways: the request sealed, the reply opened before it is read', async () => {
+ const { server, seal, link } = await lane()
+ await link.online()
+ const answer = link.rpc('agents_list', { scope: 'all' }, LINKED)
+ await until('the request', () => server.forMachines().some((frame) => frame.type === 'agents_list'))
+ expect(server.forMachines().find((frame) => frame.type === 'agents_list')!.payload).toEqual({ __e2e: { of: 'agents_list' } })
+ // What the gateway sealed carried the request id; the reply that comes back sealed is opened to it.
+ const asked = seal.seal.mock.calls.find(([, frame]) => frame.type === 'agents_list')![1] as { payload: { requestId: string } }
+ seal.open.mockResolvedValueOnce({ frame: { type: 'agents_list_result', machineId: LINKED, payload: { requestId: asked.payload.requestId, agents: ['on B'] } } })
+ server.send({ type: 'agents_list_result', machineId: LINKED, payload: { __e2e: { n: 1 } } })
+ expect(await answer).toEqual({ requestId: asked.payload.requestId, agents: ['on B'] })
+ })
+
+ it('a machine that refuses this one\'s key fails its session, and it ends at the gateway', async () => {
+ const { server, seal, link } = await lane()
+ await link.online()
+ await link.establish(LINKED)
+ server.send({ type: 'e2e_rekey', machineId: LINKED, payload: { epoch: 'next' } })
+ await until('the rekey', () => seal.rekey.mock.calls.length === 1)
+ expect(seal.rekey).toHaveBeenCalledWith(LINKED, { epoch: 'next' })
+ // A rekey for a machine with no session is not the gateway's business.
+ server.send({ type: 'e2e_rekey', machineId: 'nobody', payload: {} })
+ server.send({ type: 'e2e_denied', machineId: LINKED, payload: {} })
+ await until('the session to end at the gateway', () => seal.drop.mock.calls.length === 1)
+ expect(seal.drop).toHaveBeenCalledWith(LINKED)
+ expect(seal.rekey).toHaveBeenCalledTimes(1)
+ // A welcome the gateway turns down fails the handshake.
+ seal.welcome.mockResolvedValueOnce(false)
+ await expect(link.establish(LINKED)).rejects.toThrow('E2EE_HANDSHAKE_FAILED')
+ // A reset says so to the gateway too, and the lane stopping ends every session it has there.
+ await link.establish(LINKED)
+ expect(link.resetSession(LINKED)).toBe(true)
+ expect(seal.drop).toHaveBeenLastCalledWith(LINKED)
+ await link.establish(LINKED)
+ const drops = seal.drop.mock.calls.length
+ link.stop()
+ expect(seal.drop.mock.calls.length).toBe(drops + 1)
+ })
+
+ it('signs in with the core\'s token, refreshed once after a 401, and holds none of its own', async () => {
+ const auth = { accessToken: vi.fn(async (options?: { force?: boolean; failedToken?: string }) => (options?.force ? 'token-2' : 'token-1')) }
+ const { server, link } = await lane({ refuseToken: 'token-1', auth })
+ await link.online()
+ expect(auth.accessToken).toHaveBeenNthCalledWith(1)
+ expect(auth.accessToken).toHaveBeenNthCalledWith(2, { force: true, failedToken: 'token-1' })
+ expect(server.tokens).toEqual(['token-1', 'token-2'])
+ })
+})
diff --git a/cli/src/device/deviceLink.ts b/cli/src/device/deviceLink.ts
index f21243cdb..4d8d387eb 100644
--- a/cli/src/device/deviceLink.ts
+++ b/cli/src/device/deviceLink.ts
@@ -18,7 +18,9 @@
//
// 2. NEVER CLEAR THE AUTH SESSION. `BackendSocket.onRevoked` owns that decision. Two sockets racing to
// wipe a session on the same 401 is a bug waiting for a bad afternoon; a dead DeviceLink must
-// degrade to "other machines unavailable" and leave the cabled machine working.
+// degrade to "other machines unavailable" and leave the cabled machine working. It holds no session
+// either: its tokens come from the core's (`core.account.accessToken`), and its E2EE sessions are the
+// gateway's, which holds this machine's identity (`core.account.lane`, gateway/lane.ts).
//
// 3. LOG EVERY ERROR AND EVERY DROPPED FRAME. This feature's characteristic bug is SILENT EMPTINESS —
// an RPC answered with an error nobody printed, a card arriving in a shape nobody recognised. All of
@@ -28,10 +30,9 @@ import { randomUUID } from 'node:crypto'
import WebSocket from 'ws'
-import type { AuthSessionManager } from '../lib/authSession.js'
-import { b64d, type Identity } from '../lib/e2ee/core.js'
-import { RelaySessionCrypto } from '../lib/e2ee/relayClient.js'
+import type { LaneSeal } from '../core/api.js'
import type { MachinePeer } from '../lib/e2ee/machinePeers.js'
+import { isWrapped } from '../lib/relayFrames.js'
import { VERSION } from '../version.js'
/** One frame on the wire. The backend's own vocabulary, unchanged. */
@@ -51,12 +52,17 @@ const MAX_DELAY_MS = 30_000
export type DeviceLinkStatus = 'idle' | 'connecting' | 'ready' | 'error'
export interface DeviceLinkOpts {
- auth: AuthSessionManager
+ /** The account's tokens, from the core (`core.account.accessToken`): one forced refresh after a 401. */
+ auth: { accessToken(options?: { force?: boolean; failedToken?: string }): Promise<string> }
backendWsBase: string
computerId: string
autonomousEnv: string
- /** This daemon's own E2EE identity — the same one `harness remote-password set`/`link connect` signs with. */
- identity: Identity
+ /**
+ * The E2EE session with each linked machine, held by the gateway under this daemon's own identity — the
+ * same one `harness remote-password set`/`link connect` signs with (`core.account.lane`). The lane keeps
+ * only whether each session is up.
+ */
+ seal: LaneSeal
/** The pinned key for a machine, read FRESH: `harness link connect` runs as a separate process. */
peer: (machineId: string) => MachinePeer | null
/**
@@ -71,6 +77,9 @@ export interface DeviceLinkOpts {
log: (line: string) => void
}
+/** The lane's side of a machine's E2EE session: whether it is up. Its keys are the gateway's. */
+interface LaneSession { ready: boolean }
+
export class DeviceLink {
private ws: WebSocket | null = null
private attached = ''
@@ -98,10 +107,17 @@ export class DeviceLink {
* can be encrypted or read — which is exactly what the backend's outer `machineId` tag is for
* (hub.ts deliverUpLocal tags every commander frame with it).
*/
- private readonly sessions = new Map<string, RelaySessionCrypto>()
+ private readonly sessions = new Map<string, LaneSession>()
private readonly cryptoWaiters = new Map<string, { resolve: () => void; reject: (e: Error) => void; timer: NodeJS.Timeout }>()
/** In-flight handshakes, so N concurrent callers for one machine send exactly ONE hello. */
private readonly handshakes = new Map<string, Promise<void>>()
+ /**
+ * What goes out and what comes in, each in the order it came. Sealing and opening are a round trip to the
+ * gateway, and a frame that needs none must not overtake one that does: a turn's cards, or a reply and
+ * the frame after it, would arrive out of order.
+ */
+ private outbound: Promise<void> = Promise.resolve()
+ private inbound: Promise<void> = Promise.resolve()
@@ -162,17 +178,24 @@ export class DeviceLink {
if (inflight) return inflight
const peer = this.opts.peer(machineId)
if (!peer) return // a cloud machine, or one whose RPCs the backend answers itself
- const crypto = new RelaySessionCrypto({ machineId, selfIdentity: this.opts.identity, peerPub: b64d(peer.pub) })
- this.sessions.set(machineId, crypto)
+ const session: LaneSession = { ready: false }
+ this.sessions.set(machineId, session)
const handshake = new Promise<void>((resolve, reject) => {
const timer = setTimeout(() => {
this.cryptoWaiters.delete(machineId)
reject(new Error('the machine did not answer the E2EE hello'))
}, RPC_TIMEOUT_MS)
this.cryptoWaiters.set(machineId, { resolve, reject, timer })
- // The hello goes in clear AND tagged: the backend routes a device frame by its outer machineId, so
- // without the tag the handshake for a background machine would be delivered to the active one.
- this.send({ ...(crypto.helloFrame() as DeviceFrame), machineId })
+ // The gateway starts the session and words the hello. It goes in clear AND tagged: the backend routes
+ // a device frame by its outer machineId, so without the tag the handshake for a background machine
+ // would be delivered to the active one. A session given up meanwhile (the socket closed, a reset)
+ // sends nothing, and a gateway that cannot start one fails only this one.
+ this.opts.seal.hello(machineId, peer.pub).then(
+ (hello) => { if (this.sessions.get(machineId) === session) this.send({ ...(hello as DeviceFrame), machineId }) },
+ (err: unknown) => {
+ if (this.sessions.get(machineId) === session) this.failCrypto(machineId, err instanceof Error ? err : new Error(String(err)))
+ },
+ )
}).finally(() => { this.handshakes.delete(machineId) })
this.handshakes.set(machineId, handshake)
await handshake
@@ -205,6 +228,7 @@ export class DeviceLink {
if (!machineId || this.handshakes.has(machineId)) return false
if (!this.sessions.has(machineId)) return false
this.sessions.delete(machineId)
+ this.opts.seal.drop(machineId)
return true
}
@@ -226,7 +250,8 @@ export class DeviceLink {
/** Fire-and-forget. Dropped with a line rather than thrown: a turn is not worth an unhandled rejection. */
send(frame: DeviceFrame): void {
- if (this.ws?.readyState !== WebSocket.OPEN) {
+ const ws = this.ws
+ if (ws?.readyState !== WebSocket.OPEN) {
this.opts.log(`device: dropped ${frame.type ?? '?'} — no link`)
return
}
@@ -236,14 +261,38 @@ export class DeviceLink {
// The key is picked by the frame's own `machineId`, falling back to the attached machine for the
// frames that predate multi-machine (machine_select, ping). Encrypting with the wrong machine's key
// is the one failure here that looks like nothing at all: the far end drops it silently.
- const session = this.sessions.get(frame.machineId || this.attached)
- const out = session?.ready && !String(frame.type ?? '').startsWith('e2e_')
- ? (session.wrapOutgoing(frame as Record<string, unknown>) as DeviceFrame)
- : frame
+ //
+ // Decided now, as the frame is handed over; sealed by the gateway in turn, and sent in the order handed.
+ const machineId = frame.machineId || this.attached
+ const session = this.sessions.get(machineId)
+ const sealing = !!session?.ready && !String(frame.type ?? '').startsWith('e2e_')
+ this.outbound = this.outbound.then(async () => {
+ let out = frame
+ if (sealing) {
+ const sealed = await this.opts.seal.seal(machineId, frame as Record<string, unknown>).catch((): { lost: true } => ({ lost: true }))
+ // Never the frame as it came: the gateway restarted under this session (or is not there), so the
+ // frame goes nowhere and the next call to that machine starts a session again.
+ if ('lost' in sealed) {
+ this.forget(machineId, session)
+ this.opts.log(`device: dropped ${frame.type ?? '?'} for ${machineId} — its E2EE session is gone`)
+ return
+ }
+ out = sealed.frame as DeviceFrame
+ }
+ // The socket it was handed for: one closed meanwhile takes it with it, never the next connection.
+ if (ws.readyState !== WebSocket.OPEN) {
+ this.opts.log(`device: dropped ${frame.type ?? '?'} — no link`)
+ return
+ }
+ try { ws.send(JSON.stringify(out)) } catch (err) {
+ this.opts.log(`device: send ${frame.type ?? '?'} failed (${(err as Error).message})`)
+ }
+ })
+ }
- try { this.ws.send(JSON.stringify(out)) } catch (err) {
- this.opts.log(`device: send ${frame.type ?? '?'} failed (${(err as Error).message})`)
- }
+ /** A session the gateway no longer holds (it restarted): forgotten here too, so the next call starts one. */
+ private forget(machineId: string, session: LaneSession | undefined): void {
+ if (session && this.sessions.get(machineId) === session && !this.handshakes.has(machineId)) this.sessions.delete(machineId)
}
/**
@@ -323,8 +372,8 @@ export class DeviceLink {
cleanup()
this.attempts = 0
this.state = 'ready'
- // `e2ee_data` says this side can decrypt an encrypted `*_result` — which it can, via
- // RelaySessionCrypto below. Advertising it before that was true would turn a clean
+ // `e2ee_data` says this side can decrypt an encrypted `*_result` — which it can, through the
+ // gateway's session (gateway/lane.ts). Advertising it before that was true would turn a clean
// E2EE_REQUIRED error into a hang, which is why it went in only once the session did.
//
// `multi_machine` is what makes the dial's carousel span machines: the backend then holds a
@@ -350,7 +399,11 @@ export class DeviceLink {
}
ws.once('error', onError)
ws.once('open', onOpen)
- ws.on('message', (raw) => this.onMessage(raw))
+ ws.on('message', (raw) => {
+ this.inbound = this.inbound.then(() => this.onMessage(raw)).catch((err: unknown) => {
+ this.opts.log(`device: a frame could not be read (${err instanceof Error ? err.message : String(err)})`)
+ })
+ })
ws.on('close', (code) => this.onClose(code))
})
}
@@ -375,16 +428,20 @@ export class DeviceLink {
})
}
- private onWelcome(machineId: string, payload: Record<string, unknown>): void {
- const crypto = this.sessions.get(machineId)
- if (!crypto) return
- if (!crypto.handleWelcome(payload)) { this.failCrypto(machineId, new Error('E2EE_HANDSHAKE_FAILED')); return }
+ private async onWelcome(machineId: string, payload: Record<string, unknown>): Promise<void> {
+ const session = this.sessions.get(machineId)
+ if (!session) return
+ const welcomed = await this.opts.seal.welcome(machineId, payload).catch(() => false)
+ // Given up while the gateway read it (the socket closed, a reset): a newer session is not this one's.
+ if (this.sessions.get(machineId) !== session) return
+ if (!welcomed) { this.failCrypto(machineId, new Error('E2EE_HANDSHAKE_FAILED')); return }
+ session.ready = true
const waiter = this.cryptoWaiters.get(machineId)
if (waiter) { clearTimeout(waiter.timer); this.cryptoWaiters.delete(machineId); waiter.resolve() }
}
private failCrypto(machineId: string, err: Error): void {
- this.sessions.delete(machineId)
+ if (this.sessions.delete(machineId)) this.opts.seal.drop(machineId)
const waiter = this.cryptoWaiters.get(machineId)
if (waiter) { clearTimeout(waiter.timer); this.cryptoWaiters.delete(machineId); waiter.reject(err) }
}
@@ -439,7 +496,7 @@ export class DeviceLink {
}, delay)
}
- private onMessage(raw: WebSocket.RawData): void {
+ private async onMessage(raw: WebSocket.RawData): Promise<void> {
let frame: DeviceFrame
try { frame = JSON.parse(raw.toString()) as DeviceFrame } catch { return }
@@ -455,8 +512,11 @@ export class DeviceLink {
if (from && from === this.opts.localMachineId() && !String(frame.type ?? '').endsWith('_result')) return
- if (frame.type === 'e2e_welcome') { this.onWelcome(from, (frame.payload ?? {}) as Record<string, unknown>); return }
- if (frame.type === 'e2e_rekey') { this.sessions.get(from)?.handleRekey((frame.payload ?? {}) as Record<string, unknown>); return }
+ if (frame.type === 'e2e_welcome') { await this.onWelcome(from, (frame.payload ?? {}) as Record<string, unknown>); return }
+ if (frame.type === 'e2e_rekey') {
+ if (this.sessions.has(from)) await this.opts.seal.rekey(from, (frame.payload ?? {}) as Record<string, unknown>).catch(() => undefined)
+ return
+ }
if (frame.type === 'e2e_denied') {
// The far end knows this daemon's key and rejected it — the pin is stale, not merely missing.
this.opts.log(`device: e2e denied ${from} — the remote password may have changed or this machine's link was revoked, re-run \`harness link connect ${from}\``)
@@ -465,16 +525,22 @@ export class DeviceLink {
}
const session = this.sessions.get(from)
- if (session?.ready) {
- const plain = session.unwrapIncoming(frame as Record<string, unknown>)
-
- if (!plain) {
+ // A frame that was never sealed (a control frame) is read as it is, as the session itself would read it
+ // (lib/e2ee/relayClient.ts `unwrapIncoming`): only a sealed one goes to the gateway to be opened.
+ if (session?.ready && isWrapped(frame.payload)) {
+ const opened = await this.opts.seal.open(from, frame as Record<string, unknown>).catch((): { lost: true } => ({ lost: true }))
+ if ('lost' in opened) {
+ this.forget(from, session)
+ this.opts.log(`device: could not decrypt ${frame.type ?? '?'} — the E2EE session with ${from} is gone, dropped`)
+ return
+ }
+ if ('unreadable' in opened) {
// The single most misleading failure this lane has: an undecryptable card is indistinguishable
// from no card at all, and the dial just sits through a whole turn showing nothing.
this.opts.log(`device: could not decrypt ${frame.type ?? '?'} — dropped`)
return
}
- frame = plain as DeviceFrame
+ frame = opened.frame as DeviceFrame
}
const type = frame.type ?? ''
const payload = (frame.payload ?? {}) as Record<string, unknown>
diff --git a/cli/src/gateway/gatewayProcess.spec.ts b/cli/src/gateway/gatewayProcess.spec.ts
index ce7aa5021..ee9110fb9 100644
--- a/cli/src/gateway/gatewayProcess.spec.ts
+++ b/cli/src/gateway/gatewayProcess.spec.ts
@@ -6,6 +6,7 @@
import { describe, expect, it, vi } from 'vitest'
import type { GatewayEvents, GatewayOps, GatewayPort, WindowRelay } from '../core/api.js'
import { createGatewayLink } from '../core/gatewayLink.js'
+import { GATEWAY_CALLS } from '../lib/gatewayWire.js'
import { RelayConnectError } from '../lib/relayFrames.js'
import { TerminalBinaryKind, type TerminalBinaryClear } from '../lib/terminalBinary.js'
import type { CoreConnection, ServiceProcessOptions } from '../services/process.js'
@@ -32,12 +33,23 @@ function stubGateway() {
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(),
+ lane: {
+ hello: vi.fn(async (machineId: string) => ({ type: 'e2e_hello', machineId })), welcome: vi.fn(async () => true),
+ rekey: vi.fn(async () => {}), seal: vi.fn(async (_m: string, frame: Record<string, unknown>) => ({ frame: { ...frame, sealed: true } })),
+ open: vi.fn(async () => ({ unreadable: true as const })), drop: 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(),
+ acquireShare: vi.fn(async (_machineId: string, shareId: string) => {
+ if (shareId === 'ended') throw new RelayConnectError('Sharing ended or invitation expired', 4403)
+ const session = { send: vi.fn(async () => {}), sendBinary: vi.fn(async () => {}), detach: vi.fn() }
+ sessions.push(session)
+ return session
+ }),
} satisfies WindowRelay
return { port, ops, windowRelay, sessions, stop: vi.fn(async () => {}) }
}
@@ -248,6 +260,29 @@ describe('the gateway\'s process, spoken to by the core', () => {
expect(ops.wifi).toHaveBeenCalledWith({ op: 'pair', device: 'dev', code: 'C', id: '' })
})
+ it('runs the fleet\'s lane\'s sessions in the gateway it runs, and seals nothing with none running', async () => {
+ const w = wire()
+ const lane = w.link.ops.lane
+ // Not started: the lane gets no session and no frame back as it was.
+ await expect(lane.hello('m2', 'PEER')).rejects.toThrow(/not running/)
+ w.connect()
+ expect(await lane.hello('m2', 'PEER')).toEqual({ type: 'e2e_hello', machineId: 'm2' })
+ expect(await lane.welcome('m2', { ephPub: 'E' })).toBe(true)
+ await lane.rekey('m2', { epoch: 'x' })
+ expect(await lane.seal('m2', { type: 'message' })).toEqual({ frame: { type: 'message', sealed: true } })
+ expect(await lane.open('m2', { type: 'message' })).toEqual({ unreadable: true })
+ lane.drop('m2')
+ await Promise.resolve()
+ const { ops } = w.gateways[0]
+ expect(ops.lane.hello).toHaveBeenCalledWith('m2', 'PEER')
+ expect(ops.lane.welcome).toHaveBeenCalledWith('m2', { ephPub: 'E' })
+ expect(ops.lane.rekey).toHaveBeenCalledWith('m2', { epoch: 'x' })
+ expect(ops.lane.drop).toHaveBeenCalledWith('m2')
+ expect(await w.options().requests[GATEWAY_CALLS.lane]({ op: 'nothing' }, { local: true, owner: true })).toEqual({ error: 'UNKNOWN_OP' })
+ w.disconnect()
+ expect(await lane.seal('m2', { type: 'message' })).toEqual({ lost: true })
+ })
+
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()
@@ -283,6 +318,18 @@ describe('the gateway\'s process, spoken to by the core', () => {
expect(sessions[2].detach).toHaveBeenCalled()
})
+ it('watches a shared harness through the Share relay it runs, and fails as the Share relay did', async () => {
+ const w = wire()
+ w.connect()
+ const { windowRelay, sessions } = w.gateways[0]
+ const sink = { sendFrame: vi.fn(() => true), sendBinary: vi.fn(() => true) }
+ const session = await w.link.windowRelay.acquireShare!('owner', 'share-1', sink, vi.fn())
+ expect(windowRelay.acquireShare).toHaveBeenCalledWith('owner', 'share-1', expect.anything(), expect.any(Function))
+ await session.send({ type: 'terminal_open', payload: {} })
+ expect(sessions[0].send).toHaveBeenCalledWith({ type: 'terminal_open', payload: {} })
+ await expect(w.link.windowRelay.acquireShare!('owner', 'ended', sink, vi.fn())).rejects.toMatchObject({ message: 'Sharing ended or invitation expired', closeCode: 4403 })
+ })
+
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 })
diff --git a/cli/src/gateway/gatewayProcess.ts b/cli/src/gateway/gatewayProcess.ts
index 2f5b3cefc..4cc3019f2 100644
--- a/cli/src/gateway/gatewayProcess.ts
+++ b/cli/src/gateway/gatewayProcess.ts
@@ -11,10 +11,10 @@
* 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 { accountLink } from '../services/accountLink.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess } from '../services/process.js'
import { startGateway, type StartedGateway } from './start.js'
@@ -33,7 +33,6 @@ export interface GatewayServiceOptions {
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
@@ -66,14 +65,9 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces
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 account's tokens, from the core (`core.account`, services/accountLink.ts): a refusal comes back as
+ * the session's own error. */
+ const { accessToken } = accountLink((query, payload) => (core ? core.query(query, payload) : Promise.reject(new Error('not connected to the core'))))
/** 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. */
@@ -119,17 +113,22 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces
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 sink = {
+ sendFrame: (frame: Payload) => { notice('windowFrame', { id, frame }); return true },
+ sendBinary: (bytes: Uint8Array) => {
const framed = encodeGatewayBinary(GatewayBinary.window, id, bytes)
return !!framed && !!core?.sendBinary?.(framed)
},
- }, (code, reason) => {
+ }
+ const onClosed = (code: number, reason: string): void => {
windows.delete(id)
notice('windowClosed', { id, code, reason })
- })
+ }
+ const machineId = text(payload.machineId)
+ const acquire = typeof payload.share === 'string' ? () => pool.acquireShare(machineId, text(payload.share), sink, onClosed)
+ : payload.isolated === true ? () => pool.acquireIsolated(machineId, text(payload.autonomousEnv), record(payload.frame), sink, onClosed)
+ : () => pool.acquire(machineId, text(payload.autonomousEnv), record(payload.frame), sink, onClosed)
+ const session = await acquire()
windows.set(id, session)
notice('windowOpened', { id })
} catch (error) {
@@ -228,6 +227,21 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces
[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) }),
}),
+ // The fleet's lane's sessions (gateway/lane.ts). Each is answered from what it holds at once, so they
+ // are taken in the order the core sent them.
+ [GATEWAY_CALLS.lane]: async (p: Payload): Promise<Payload> => {
+ const lane = ops().lane
+ const machineId = text(p.machineId)
+ switch (p.op) {
+ case 'hello': return { frame: await lane.hello(machineId, text(p.peerPub)) }
+ case 'welcome': return { ok: await lane.welcome(machineId, record(p.payload)) }
+ case 'rekey': await lane.rekey(machineId, record(p.payload)); return {}
+ case 'seal': return { ...await lane.seal(machineId, record(p.frame)) }
+ case 'open': return { ...await lane.open(machineId, record(p.frame)) }
+ case 'drop': lane.drop(machineId); return {}
+ default: return { error: 'UNKNOWN_OP' }
+ }
+ },
}
return (options.run ?? runServiceProcess)({
diff --git a/cli/src/gateway/lane.spec.ts b/cli/src/gateway/lane.spec.ts
new file mode 100644
index 000000000..b8bbd2aaf
--- /dev/null
+++ b/cli/src/gateway/lane.spec.ts
@@ -0,0 +1,124 @@
+/**
+ * The fleet's lane's sessions in the gateway, with real keys against a real machine on the far end (its
+ * E2eeManager, as another daemon runs it). The lane used to hold this machine's identity and run these
+ * sessions itself (device/deviceLink.ts); each rule here fails if it was lost in the move: what the lane
+ * hands over is sealed so the far machine opens it, what the far machine seals is opened, and a session
+ * the gateway does not hold (never welcomed, dropped, gone with a restart) seals nothing, so a frame for a
+ * linked machine never leaves in the clear.
+ */
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import type * as CoreCrypto from '../lib/e2ee/core.js'
+import type { E2eeManager as Manager } from '../lib/e2ee/manager.js'
+import { LaneSessions } from './lane.js'
+
+type Frame = Record<string, unknown>
+const MACHINE = 'b1b2c3d4e5f60718293a4b5c6d7e8f90'
+const CONN = 'device:lane-1'
+
+// The far machine's store reads its data folder when its module loads: a throwaway one, set first.
+const dataDir = mkdtempSync(join(tmpdir(), 'gateway-lane-'))
+let C: typeof CoreCrypto
+let E2eeManager: typeof Manager
+beforeAll(async () => {
+ process.env.ADAPTER_DATA_DIR = dataDir
+ C = await import('../lib/e2ee/core.js')
+ E2eeManager = (await import('../lib/e2ee/manager.js')).E2eeManager
+})
+afterAll(() => { rmSync(dataDir, { recursive: true, force: true }) })
+
+/** The far machine, which trusts this one's key (as `harness link connect` leaves two machines). */
+function farMachine(trusted: Uint8Array) {
+ const sent: Frame[] = []
+ const manager = new E2eeManager({ machineId: MACHINE, sendTo: (_connId, frame) => { sent.push(frame) }, isConnected: () => true })
+ manager.trustPeer({ pub: C.b64e(trusted), machineId: 'this-machine', label: 'this machine' })
+ const pub = C.b64e((manager as unknown as { store: { getIdentity(): CoreCrypto.Identity } }).store.getIdentity().pub)
+ return { manager, sent, pub }
+}
+
+/** A lane with a session up to the far machine: hello, then its welcome. */
+async function welcomed() {
+ const identity = C.newIdentity()
+ const lane = new LaneSessions(() => identity)
+ const far = farMachine(identity.pub)
+ const hello = await lane.hello(MACHINE, far.pub)
+ expect(hello.type).toBe('e2e_hello')
+ far.manager.handleFrame(CONN, hello)
+ const welcome = far.sent.find((frame) => frame.type === 'e2e_welcome')!
+ expect(welcome).toBeDefined()
+ return { lane, far, identity, welcome }
+}
+
+describe('the fleet\'s lane, sealed by the gateway', () => {
+ it('seals what the lane hands it so the far machine opens it, and opens what the far machine seals back', async () => {
+ const { lane, far, welcome } = await welcomed()
+ expect(await lane.welcome(MACHINE, welcome.payload as Frame)).toBe(true)
+ const sealed = await lane.seal(MACHINE, { type: 'agents_list', machineId: MACHINE, payload: { requestId: 'r1', secret: 'the owner typed this' } })
+ expect('frame' in sealed).toBe(true)
+ const out = (sealed as { frame: Frame }).frame
+ expect(JSON.stringify(out)).not.toContain('the owner typed this')
+ expect(far.manager.unwrapDown(CONN, out)).toMatchObject({ type: 'agents_list', payload: { requestId: 'r1', secret: 'the owner typed this' } })
+ const reply = far.manager.wrapRpcReply(CONN, 'agents_list_result', 'r1', { agents: [{ id: 'a1', name: 'on the far machine' }] })!
+ expect(JSON.stringify(reply)).not.toContain('on the far machine')
+ expect(await lane.open(MACHINE, reply)).toEqual({ frame: expect.objectContaining({ type: 'agents_list_result', payload: { requestId: 'r1', agents: [{ id: 'a1', name: 'on the far machine' }] } }) })
+ })
+
+ it('signs the hello as this machine, so a machine that trusts another key turns it away', async () => {
+ const lane = new LaneSessions(() => C.newIdentity())
+ const far = farMachine(C.newIdentity().pub)
+ far.manager.handleFrame(CONN, await lane.hello(MACHINE, far.pub))
+ expect(far.sent.some((frame) => frame.type === 'e2e_welcome')).toBe(false)
+ expect(far.sent.some((frame) => frame.type === 'e2e_denied')).toBe(true)
+ })
+
+ it('seals nothing without a session up: not before the welcome, not after a drop, not after a restart', async () => {
+ const frame = { type: 'message', machineId: MACHINE, payload: { content: 'never in the clear' } }
+ const { lane, welcome } = await welcomed()
+ // Hello sent, no welcome yet.
+ expect(await lane.seal(MACHINE, frame)).toEqual({ lost: true })
+ expect(await lane.open(MACHINE, frame)).toEqual({ lost: true })
+ // A machine nobody started a session with.
+ expect(await lane.seal('another-machine', frame)).toEqual({ lost: true })
+ expect(await lane.welcome('another-machine', welcome.payload as Frame)).toBe(false)
+ await lane.rekey('another-machine', {})
+ expect(await lane.welcome(MACHINE, welcome.payload as Frame)).toBe(true)
+ expect('frame' in await lane.seal(MACHINE, frame)).toBe(true)
+ lane.drop(MACHINE)
+ expect(await lane.seal(MACHINE, frame)).toEqual({ lost: true })
+ // Up again, then the gateway stopping (a restart under the lane): every session goes.
+ const again = await welcomed()
+ expect(await again.lane.welcome(MACHINE, again.welcome.payload as Frame)).toBe(true)
+ again.lane.clear()
+ expect(await again.lane.seal(MACHINE, frame)).toEqual({ lost: true })
+ })
+
+ it('never forwards what does not open: a garbled, a replayed or a forged frame is unreadable', async () => {
+ const { lane, far, welcome } = await welcomed()
+ expect(await lane.welcome(MACHINE, welcome.payload as Frame)).toBe(true)
+ const reply = far.manager.wrapRpcReply(CONN, 'agents_list_result', 'r1', { agents: [] })!
+ expect('frame' in await lane.open(MACHINE, reply)).toBe(true)
+ // The same frame again: the session's replay window refuses it.
+ expect(await lane.open(MACHINE, reply)).toEqual({ unreadable: true })
+ const payload = reply.payload as { __e2e: Record<string, unknown> }
+ expect(await lane.open(MACHINE, { ...reply, payload: { __e2e: { ...payload.__e2e, n: 99, ct: 'AAAA' } } })).toEqual({ unreadable: true })
+ // A frame never sealed is passed as it is, as the session reads one.
+ expect(await lane.open(MACHINE, { type: 'machine_selected', payload: { machineId: MACHINE } })).toEqual({ frame: { type: 'machine_selected', payload: { machineId: MACHINE } } })
+ })
+
+ it('takes the far machine\'s new keys, and a new hello replaces the session it had', async () => {
+ const { lane, far, welcome, identity } = await welcomed()
+ expect(await lane.welcome(MACHINE, welcome.payload as Frame)).toBe(true)
+ await lane.rekey(MACHINE, { epoch: 'nope' })
+ // A second hello for the same machine: a fresh session, not yet up, so nothing is sealed under the old one.
+ const second = await lane.hello(MACHINE, far.pub)
+ expect(await lane.seal(MACHINE, { type: 'message', payload: {} })).toEqual({ lost: true })
+ far.manager.handleFrame('device:lane-2', second)
+ const welcome2 = far.sent.filter((frame) => frame.type === 'e2e_welcome').at(-1)!
+ expect(await lane.welcome(MACHINE, welcome2.payload as Frame)).toBe(true)
+ const sealed = await lane.seal(MACHINE, { type: 'message', payload: { content: 'second session' } }) as { frame: Frame }
+ expect(far.manager.unwrapDown('device:lane-2', sealed.frame)).toMatchObject({ payload: { content: 'second session' } })
+ expect(identity.pub).toBeInstanceOf(Uint8Array)
+ })
+})
diff --git a/cli/src/gateway/lane.ts b/cli/src/gateway/lane.ts
new file mode 100644
index 000000000..04856b9f9
--- /dev/null
+++ b/cli/src/gateway/lane.ts
@@ -0,0 +1,60 @@
+/**
+ * The fleet's lane's sessions, held by the gateway (docs/design/2026-10-06-core-boundary-next.md, step 10,
+ * R3). The lane (device/deviceLink.ts) is the daemon's socket to its owner's other machines on the dial's
+ * behalf; it used to hold this machine's E2EE identity to seal what it sent them, and a service holds no
+ * credential. The identity stays here with every other key: the lane asks for a session per machine,
+ * and for each frame to be sealed or opened under it (`core.account.lane`, `LaneSeal`).
+ *
+ * The same sessions the lane ran itself (lib/e2ee/relayClient.ts), one per machine, keyed by its id: a
+ * new hello replaces the machine's session, as the lane's own map did. No session, or one not yet up,
+ * seals nothing: `lost`, never the frame as it came, so a frame for a linked machine is never sent in
+ * the clear because the gateway restarted under the lane.
+ */
+import type { LaneOpened, LaneSeal, LaneSealed } from '../core/api.js'
+import { b64d, type Identity } from '../lib/e2ee/core.js'
+import { RelaySessionCrypto } from '../lib/e2ee/relayClient.js'
+
+type Frame = Record<string, unknown>
+
+export class LaneSessions implements LaneSeal {
+ private readonly sessions = new Map<string, RelaySessionCrypto>()
+
+ /** `identity` is read when a session starts: the one on disk, as the gateway's own store holds it. */
+ constructor(private readonly identity: () => Identity) {}
+
+ async hello(machineId: string, peerPub: string): Promise<Frame> {
+ const session = new RelaySessionCrypto({ machineId, selfIdentity: this.identity(), peerPub: b64d(peerPub) })
+ this.sessions.set(machineId, session)
+ return session.helloFrame()
+ }
+
+ async welcome(machineId: string, payload: Frame): Promise<boolean> {
+ return this.sessions.get(machineId)?.handleWelcome(payload) ?? false
+ }
+
+ async rekey(machineId: string, payload: Frame): Promise<void> {
+ this.sessions.get(machineId)?.handleRekey(payload)
+ }
+
+ async seal(machineId: string, frame: Frame): Promise<LaneSealed> {
+ const session = this.sessions.get(machineId)
+ if (!session?.ready) return { lost: true }
+ return { frame: session.wrapOutgoing(frame) }
+ }
+
+ async open(machineId: string, frame: Frame): Promise<LaneOpened> {
+ const session = this.sessions.get(machineId)
+ if (!session?.ready) return { lost: true }
+ const plain = session.unwrapIncoming(frame)
+ return plain ? { frame: plain } : { unreadable: true }
+ }
+
+ drop(machineId: string): void {
+ this.sessions.delete(machineId)
+ }
+
+ /** The gateway is stopping: every session goes with it. */
+ clear(): void {
+ this.sessions.clear()
+ }
+}
diff --git a/cli/src/gateway/share.spec.ts b/cli/src/gateway/share.spec.ts
new file mode 100644
index 000000000..5051a405b
--- /dev/null
+++ b/cli/src/gateway/share.spec.ts
@@ -0,0 +1,33 @@
+/**
+ * The Share relay through the gateway: a window that cannot watch a shared harness is told why in the
+ * words and the close the local socket gave it when the Share relay ran in the core (sharing/relay.ts's
+ * errors, mapped where the relay now runs). Each case fails if the mapping was lost in the move.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { SharingEndedError } from '../sharing/relay.js'
+import { SHARE_ENDED, SHARE_UNREACHABLE, shareWindows } from './share.js'
+
+const sink = { sendFrame: () => true, sendBinary: () => true }
+
+describe('a window watching a shared harness, through the gateway', () => {
+ it('watches through the Share relay, with the window\'s own sink and close', async () => {
+ const session = { send: vi.fn(async () => {}), sendBinary: vi.fn(async () => {}), detach: vi.fn() }
+ const acquire = vi.fn(async () => session)
+ const onClosed = vi.fn()
+ expect(await shareWindows({ acquire })('owner-machine', 'share-1', sink, onClosed)).toBe(session)
+ expect(acquire).toHaveBeenCalledWith('owner-machine', 'share-1', sink, onClosed)
+ })
+
+ it('is told 4403 for a share that ended, so it stops trying, and 1013 for one out of reach just now', async () => {
+ const failing = (error: unknown) => shareWindows({ acquire: async () => { throw error } })('m', 's', sink, () => {})
+ const ended = await failing(new SharingEndedError('Sharing ended or invitation expired')).catch((error: unknown) => error)
+ expect(ended).toBeInstanceOf(RelayConnectError)
+ expect(ended).toMatchObject({ message: 'Sharing ended or invitation expired', closeCode: SHARE_ENDED })
+ expect(SHARE_ENDED).toBe(4403)
+ expect(await failing(new Error('The owner’s machine is offline.')).catch((error: unknown) => error))
+ .toMatchObject({ message: 'The owner’s machine is offline.', closeCode: SHARE_UNREACHABLE })
+ expect(SHARE_UNREACHABLE).toBe(1013)
+ expect(await failing('down').catch((error: unknown) => error)).toMatchObject({ message: 'Sharing unavailable', closeCode: 1013 })
+ })
+})
diff --git a/cli/src/gateway/share.ts b/cli/src/gateway/share.ts
new file mode 100644
index 000000000..17625248d
--- /dev/null
+++ b/cli/src/gateway/share.ts
@@ -0,0 +1,25 @@
+/**
+ * A window here watching a harness someone shared with this account, through the gateway (step 10, R3).
+ * The Share relay (sharing/relay.ts) holds its own socket to the backend, signed in with the account's
+ * token, so it runs where the relay's sockets run: here, not in the core. What a window is told when it
+ * cannot watch is what the local socket told it when the Share relay ran in the core: 4403 for a share
+ * that ended or was never there, so the app stops trying; 1013 for one out of reach just now.
+ */
+import type { WindowRelay } from '../core/api.js'
+import { RelayConnectError } from '../lib/relayFrames.js'
+import { SharingEndedError, type HarnessShareRelay } from '../sharing/relay.js'
+
+/** The close for a share that ended, and for one that could not be reached. */
+export const SHARE_ENDED = 4403
+export const SHARE_UNREACHABLE = 1013
+
+export function shareWindows(relay: Pick<HarnessShareRelay, 'acquire'>): NonNullable<WindowRelay['acquireShare']> {
+ return async (machineId, shareId, sink, onClosed) => {
+ try {
+ return await relay.acquire(machineId, shareId, sink, onClosed)
+ } catch (error) {
+ throw new RelayConnectError(error instanceof Error ? error.message : 'Sharing unavailable',
+ error instanceof SharingEndedError ? SHARE_ENDED : SHARE_UNREACHABLE)
+ }
+ }
+}
diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.ts
index 71697cbdd..be2264b2d 100644
--- a/cli/src/gateway/start.ts
+++ b/cli/src/gateway/start.ts
@@ -31,7 +31,10 @@ 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 { HarnessShareRelay, type SharedMachineReference } from '../sharing/relay.js'
import { RelayGateway } from './gateway.js'
+import { LaneSessions } from './lane.js'
+import { shareWindows } from './share.js'
/** What the gateway needs of the core, in whichever process it runs. */
export interface GatewayHost {
@@ -53,7 +56,7 @@ export interface GatewayHost {
export interface StartedGateway {
port: RelayGateway
ops: GatewayOps
- windowRelay: WindowRelay
+ windowRelay: Required<WindowRelay>
stop(): Promise<void>
}
@@ -123,6 +126,8 @@ export function startGateway(host: GatewayHost): StartedGateway {
const relayIdentityStore = new E2eeStore()
relayIdentityStore.init()
const relayPeers = new MachinePeerStore()
+ // The fleet's lane's sessions, sealed with the same identity (gateway/lane.ts).
+ const lane = new LaneSessions(() => relayIdentityStore.getIdentity())
// 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
@@ -143,6 +148,21 @@ export function startGateway(host: GatewayHost): StartedGateway {
},
},
)
+ // The Share relay: a window here watching a harness someone shared with this account, over its own
+ // socket to the backend (`/api/observer-ws`), signed in with the account's token. It finds the share
+ // among those the backend lists for this account first.
+ const shareRelay = new HarnessShareRelay(host.tokens, env.BACKEND_WS_URL, host.autonomousEnv, async () => {
+ const result = await host.backend('GET', '/api/harness-shares')
+ if (result.status !== 200) throw new Error('Shared harnesses are temporarily unavailable.')
+ return ((result.body as { data?: { machines?: SharedMachineReference[] } }).data?.machines ?? [])
+ })
+ const windowRelay: Required<WindowRelay> = {
+ acquire: (...args) => relayPool.acquire(...args),
+ acquireIsolated: (...args) => relayPool.acquireIsolated(...args),
+ invalidate: (machineId) => relayPool.invalidate(machineId),
+ invalidateIsolated: (machineId) => relayPool.invalidateIsolated(machineId),
+ acquireShare: shareWindows(shareRelay),
+ }
/** This machine as its trust group knows it — see groupSyncer.ts's SELF_STAMP for the stamp. */
const groupSelf = (): GroupMember => {
const machineId = account.machineId
@@ -400,17 +420,20 @@ export function startGateway(host: GatewayHost): StartedGateway {
void devlog.register()
},
reachable: (machineIds) => { reachable = machineIds ? new Set(machineIds) : null },
+ lane,
}
return {
port: gateway,
ops,
- windowRelay: relayPool,
+ windowRelay,
stop: async () => {
clearInterval(devlogTimer)
syncer.stop()
direct?.stop()
relayPool.close()
+ shareRelay.close()
+ lane.clear()
await gateway.stop()
},
}
diff --git a/cli/src/lib/gatewayWire.ts b/cli/src/lib/gatewayWire.ts
index 41bce3846..62fd7b004 100644
--- a/cli/src/lib/gatewayWire.ts
+++ b/cli/src/lib/gatewayWire.ts
@@ -60,4 +60,5 @@ export const GATEWAY_CALLS = {
devicesDismiss: 'gateway_devices_dismiss',
devicesRebaseline: 'gateway_devices_rebaseline',
wifi: 'gateway_wifi',
+ lane: 'gateway_lane',
} as const
diff --git a/cli/src/localWsServer.spec.ts b/cli/src/localWsServer.spec.ts
index 1e5fd653e..1aab0fd61 100644
--- a/cli/src/localWsServer.spec.ts
+++ b/cli/src/localWsServer.spec.ts
@@ -6,6 +6,7 @@ import type { Frame, LocalClientSink } from './backendSocket.js'
import { attachLocalWsServer, LOCAL_WS_CLOSE_GRACE_MS, type LocalWsBackend, type LocalWsServer, type LocalWsServerOptions } from './localWsServer.js'
import { encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from './lib/terminalBinary.js'
import { listenLocalSocket } from './lib/localSocket.js'
+import { RelayConnectError } from './lib/relayFrames.js'
import { mkdtempSync, rmSync } from 'node:fs'
import { join } from 'node:path'
import { WindowForm } from './cable/windowForm.js'
@@ -397,8 +398,7 @@ describe('local CLI WebSocket', () => {
})
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
- relayPool: { acquire, acquireIsolated: acquire } as unknown as LocalWsServerOptions['relayPool'],
- shareRelay: { acquire } as unknown as LocalWsServerOptions['shareRelay'],
+ relayPool: { acquire, acquireIsolated: acquire, acquireShare: acquire } as unknown as LocalWsServerOptions['relayPool'],
}))
await onceOpen(ws)
ws.send(JSON.stringify({ type: 'machine_select', payload: {
@@ -417,6 +417,34 @@ describe('local CLI WebSocket', () => {
},
)
+ // Watching a shared harness goes through the gateway's Share relay (gateway/share.ts): the window is told
+ // what the Share relay said, with the close it set (4403 the share ended, 1013 out of reach).
+ it.each([
+ ['a share that ended', new RelayConnectError('Sharing ended or invitation expired', 4403), [4403, 'Sharing ended or invitation expired']],
+ ['one out of reach', new RelayConnectError('The owner’s machine is offline.', 1013), [1013, 'The owner’s machine is offline.']],
+ ['one failing without a close', new Error('boom'), [1013, 'boom']],
+ ['one failing with no words', 'down', [1013, 'Sharing unavailable']],
+ ] as const)('closes a window watching %s with the close the Share relay gave', async (_name, error, expected) => {
+ const backend = new FakeBackend()
+ const ws = new WebSocket(await start(backend, {
+ autonomousEnv: 'test',
+ relayPool: { acquire: vi.fn(), acquireShare: vi.fn(async () => { throw error }) } as unknown as LocalWsServerOptions['relayPool'],
+ }))
+ await onceOpen(ws)
+ const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'owner', localProtocolVersion: 1, shareId: 'share' } }))
+ expect(await closed).toEqual(expected)
+ })
+
+ it('refuses to watch a shared harness with no gateway to watch it through', async () => {
+ const backend = new FakeBackend()
+ const ws = new WebSocket(await start(backend, { autonomousEnv: 'test', relayPool: { acquire: vi.fn() } as unknown as LocalWsServerOptions['relayPool'] }))
+ await onceOpen(ws)
+ const closed = new Promise<[number, string]>((resolve) => ws.once('close', (code, reason) => resolve([code, reason.toString()])))
+ ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: 'owner', localProtocolVersion: 1, shareId: 'share' } }))
+ expect(await closed).toEqual([4403, 'Sharing is unavailable'])
+ })
+
it.each(['owned', 'shared'] as const)('detaches a late %s relay after its window disconnects', async (kind) => {
const backend = new FakeBackend(), pending = gate(), entered = gate(), disconnected = gate(), detach = vi.fn()
const acquire = async () => {
@@ -426,8 +454,7 @@ describe('local CLI WebSocket', () => {
}
const ws = new WebSocket(await start(backend, {
autonomousEnv: 'test',
- relayPool: { acquire } as unknown as LocalWsServerOptions['relayPool'],
- shareRelay: { acquire } as unknown as LocalWsServerOptions['shareRelay'],
+ relayPool: { acquire, acquireShare: acquire } as unknown as LocalWsServerOptions['relayPool'],
}))
server!.once('connection', (socket) => socket.once('close', disconnected.resolve))
await onceOpen(ws)
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index e5e468021..6fa665c12 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -1,4 +1,3 @@
-import { SharingEndedError, type HarnessShareRelay } from './sharing/relay.js'
import { randomUUID } from 'node:crypto'
import type { AppSwarms } from './cable/cableSession.js'
import { notificationReadToken, type UnreadNotification } from './cable/notificationRead.js'
@@ -51,9 +50,9 @@ export interface LocalWsServerOptions {
/** The daemon's Unix-socket server (lib/localSocket.ts), served the same endpoint beside TCP. */
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. */
+ * backend's `/api/web-ws` — see lib/remoteRelay.ts — and one for a harness shared with this account
+ * (`shareId`, sharing/relay.ts). Both are the gateway's. Omit to keep today's own-machine-only behavior. */
relayPool?: WindowRelay
- shareRelay?: HarnessShareRelay
autonomousEnv?: string
/**
* Who a window on this computer is, for a `terminal_open` it relays to another machine without
@@ -375,14 +374,16 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
close(4403, 'machine mismatch')
return
}
+ // A harness someone shared with this account, watched read-only through the gateway, which holds the
+ // Share relay's socket (sharing/relay.ts): 4403 when the share ended, 1013 when it is out of reach.
if (typeof payload.shareId === 'string') {
- if (!options.shareRelay) { close(4403, 'Sharing is unavailable'); return }
+ if (!options.relayPool?.acquireShare) { close(4403, 'Sharing is unavailable'); return }
try {
- relay = await options.shareRelay.acquire(requestedMachineId, payload.shareId, terminalSink, close)
+ relay = await options.relayPool.acquireShare(requestedMachineId, payload.shareId, terminalSink, close)
if (ws.readyState !== WebSocket.OPEN) { relay.detach(); return }
selected = true
} catch (error) {
- close(error instanceof SharingEndedError ? 4403 : 1013,
+ close(error instanceof RelayConnectError && error.closeCode ? error.closeCode : 1013,
error instanceof Error ? error.message.slice(0, 120) : 'Sharing unavailable')
}
return
diff --git a/cli/src/services/AGENTS.md b/cli/src/services/AGENTS.md
index bdd244129..8aa3c365e 100644
--- a/cli/src/services/AGENTS.md
+++ b/cli/src/services/AGENTS.md
@@ -108,5 +108,7 @@ all inside the core's process (for debugging or a quick way back).
## Do not
- Do not keep state the core needs. If the core would break without your data, it is not a service.
-- Do not hold credentials. Ask `core.account`.
+- Do not hold credentials. Ask `core.account`: a token (`accessToken`, with one forced refresh after a
+ 401) or, to seal for one of the owner's other machines, the gateway's session with it (`lane`, as the
+ fleet's lane does: `src/device/deviceLink.ts`). This machine's E2EE identity is the gateway's alone.
- Do not write to tmux, the registry or another service's files.
diff --git a/cli/src/services/accountLink.spec.ts b/cli/src/services/accountLink.spec.ts
new file mode 100644
index 000000000..72bc86df5
--- /dev/null
+++ b/cli/src/services/accountLink.spec.ts
@@ -0,0 +1,66 @@
+// The core's account from a service's own process: each token and each step of the lane's sealing asked of
+// the core (core/accountQueries.ts, wired in here as the core answers), and nothing in the clear without it.
+import { describe, expect, it, vi } from 'vitest'
+import { answerAccountQuery } from '../core/accountQueries.js'
+import type { LaneSeal } from '../core/api.js'
+import { AuthSessionError } from '../lib/authSession.js'
+import { accountLink } from './accountLink.js'
+
+function core() {
+ const lane = {
+ hello: vi.fn(async (machineId: string) => ({ type: 'e2e_hello', machineId })),
+ welcome: vi.fn(async () => true),
+ rekey: vi.fn(async () => {}),
+ seal: vi.fn(async (_m: string, frame: Record<string, unknown>) => ({ frame: { ...frame, sealed: true } })),
+ open: vi.fn(async (_m: string, frame: Record<string, unknown>) => ({ frame: { ...frame, opened: true } })),
+ drop: vi.fn(),
+ } satisfies LaneSeal
+ const account = { accessToken: vi.fn(async (_options?: unknown) => 'token-1'), lane }
+ const query = vi.fn(async (q: string, payload: Record<string, unknown>) => (await answerAccountQuery(account, q, payload)) ?? { error: 'UNKNOWN_QUERY' })
+ return { account, query }
+}
+
+describe('the core\'s account, from a service\'s own process', () => {
+ it('asks the core for each token, and fails as the session failed', async () => {
+ const c = core()
+ const link = accountLink(c.query)
+ expect(await link.accessToken()).toBe('token-1')
+ expect(await link.accessToken({ force: true, failedToken: 'old' })).toBe('token-1')
+ expect(c.account.accessToken).toHaveBeenLastCalledWith({ force: true, failedToken: 'old' })
+ c.account.accessToken.mockRejectedValueOnce(new AuthSessionError('signed out', 'MISSING'))
+ await expect(link.accessToken()).rejects.toMatchObject({ code: 'MISSING', message: 'signed out' })
+ c.account.accessToken.mockRejectedValueOnce(Object.assign(new Error('odd'), { code: 'WEIRD' }))
+ await expect(link.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE', message: 'odd' })
+ await expect(accountLink(async () => ({}))?.accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE', message: 'the core could not hand out a token' })
+ // The link to the core gone: no token, said as a session that could not be refreshed just now.
+ await expect(accountLink(async () => { throw new Error('the core went away') }).accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE', message: 'the core went away' })
+ await expect(accountLink(async () => { throw 'gone' }).accessToken()).rejects.toMatchObject({ code: 'UNAVAILABLE', message: 'not connected to the core' })
+ })
+
+ it('seals and opens through the core, step by step, as the gateway did each', async () => {
+ const c = core()
+ const { lane } = accountLink(c.query)
+ expect(await lane.hello('m2', 'P')).toEqual({ type: 'e2e_hello', machineId: 'm2' })
+ expect(await lane.welcome('m2', { e: 1 })).toBe(true)
+ await lane.rekey('m2', { r: 1 })
+ expect(await lane.seal('m2', { type: 'message' })).toEqual({ frame: { type: 'message', sealed: true } })
+ expect(await lane.open('m2', { type: 'card' })).toEqual({ frame: { type: 'card', opened: true } })
+ c.account.lane.open.mockResolvedValueOnce({ unreadable: true } as never)
+ expect(await lane.open('m2', { type: 'card' })).toEqual({ unreadable: true })
+ lane.drop('m2')
+ await vi.waitFor(() => expect(c.account.lane.drop).toHaveBeenCalledWith('m2'))
+ expect(c.account.lane.rekey).toHaveBeenCalledWith('m2', { r: 1 })
+ })
+
+ it('starts no session and seals nothing without the core, never handing a frame back as it came', async () => {
+ const { lane } = accountLink(async () => { throw new Error('the core went away') })
+ await expect(lane.hello('m2', 'P')).rejects.toThrow('not connected to the core')
+ await expect(accountLink(async () => ({})).lane.hello('m2', 'P')).rejects.toThrow('the gateway could not start an E2EE session')
+ expect(await lane.welcome('m2', {})).toBe(false)
+ expect(await lane.seal('m2', { type: 'message', payload: { content: 'never in the clear' } })).toEqual({ lost: true })
+ expect(await lane.open('m2', { type: 'card' })).toEqual({ lost: true })
+ const c = core()
+ c.account.lane.hello.mockRejectedValueOnce(new Error('it is not running'))
+ await expect(accountLink(c.query).lane.hello('m2', 'P')).rejects.toThrow('it is not running')
+ })
+})
diff --git a/cli/src/services/accountLink.ts b/cli/src/services/accountLink.ts
new file mode 100644
index 000000000..649521949
--- /dev/null
+++ b/cli/src/services/accountLink.ts
@@ -0,0 +1,53 @@
+/**
+ * The core's account, as a service in its own process reaches it (step 10, R3; the core's side is
+ * core/accountQueries.ts): a token for each dial, and the gateway's seal for the fleet's lane, each asked of
+ * the core as it is needed. The process holds neither the session nor this machine's E2EE identity.
+ *
+ * A core that cannot be asked (the link is down) hands out no token and starts no session: the lane seals
+ * nothing (`lost`), so nothing for a linked machine goes out in the clear while the core is away.
+ */
+import type { CoreApi } from '../core/api.js'
+import { AuthSessionError } from '../lib/authSession.js'
+
+type Payload = Record<string, unknown>
+const text = (value: unknown): string => (typeof value === 'string' ? value : '')
+/** A frame in the core's answer: an object, or none. */
+const frameOf = (answer: Payload): Payload | null => (answer.frame && typeof answer.frame === 'object' ? answer.frame as Payload : null)
+const SESSION_CODES = new Set(['MISSING', 'INVALID_REFRESH', 'UNAVAILABLE'])
+
+/** `query` asks the core (`CoreConnection.query`, services/process.ts); it rejects when the link goes. */
+export function accountLink(query: (query: string, payload: Payload) => Promise<Payload>): Pick<CoreApi['account'], 'accessToken' | 'lane'> {
+ const ask = (q: string, payload: Payload): Promise<Payload> => query(q, payload).catch((): Payload => ({ error: 'not connected to the core' }))
+ const lane = (op: string, payload: Payload = {}) => ask('lane', { ...payload, op })
+ return {
+ accessToken: async (options = {}) => {
+ const answer = await query('access_token', options).catch((error: unknown) => {
+ throw new AuthSessionError(error instanceof Error ? error.message : 'not connected to the core', 'UNAVAILABLE')
+ })
+ 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)
+ },
+ lane: {
+ hello: async (machineId, peerPub) => {
+ const answer = await lane('hello', { machineId, peerPub })
+ const frame = frameOf(answer)
+ if (frame) return frame
+ throw new Error(text(answer.error) || 'the gateway could not start an E2EE session')
+ },
+ welcome: async (machineId, payload) => (await lane('welcome', { machineId, payload })).ok === true,
+ rekey: async (machineId, payload) => { await lane('rekey', { machineId, payload }) },
+ seal: async (machineId, frame) => {
+ const sealed = frameOf(await lane('seal', { machineId, frame }))
+ return sealed ? { frame: sealed } : { lost: true }
+ },
+ open: async (machineId, frame) => {
+ const answer = await lane('open', { machineId, frame })
+ const opened = frameOf(answer)
+ if (opened) return { frame: opened }
+ return answer.unreadable === true ? { unreadable: true } : { lost: true }
+ },
+ drop: (machineId) => { void lane('drop', { machineId }) },
+ },
+ }
+}
diff --git a/cli/src/services/fleet.spec.ts b/cli/src/services/fleet.spec.ts
index 3b87e7f59..70230751a 100644
--- a/cli/src/services/fleet.spec.ts
+++ b/cli/src/services/fleet.spec.ts
@@ -5,8 +5,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { env } from '../config/env.js'
import type { DeviceLinkOpts } from '../device/deviceLink.js'
import type { MachineListCache } from '../device/machineList.js'
-import type { AuthSessionManager } from '../lib/authSession.js'
-import type { Identity } from '../lib/e2ee/core.js'
import type { RegisteredSession } from '../lib/registry.js'
import { routeVoiceTask, type RouteDecision, type RouterAgent } from '../lib/voiceRouter.js'
import { fakeCore } from '../testing/fakeCore.js'
@@ -72,9 +70,7 @@ function setup(over: Partial<FleetDeps> = {}, core = fakeCore()) {
machineId: () => 'mine',
machineName: () => 'MacbookPro.local',
desk: () => [],
- auth: { accessToken: vi.fn() } as unknown as AuthSessionManager,
autonomousEnv: 'test-env',
- identity: { pub: new Uint8Array(32), priv: new Uint8Array(32) } as unknown as Identity,
...over,
}
const ports: CorePorts = emptyPorts()
@@ -118,11 +114,16 @@ describe('the machine list', () => {
})
describe('the lane to the other machines', () => {
- it('signs in and seals as this daemon, reading the pinned keys and this machine’s id fresh', async () => {
+ it('signs in and seals through the core, holding no credential, reading the pinned keys and this machine’s id fresh', async () => {
let machineId = ''
- const { deps, router } = setup({ machineId: () => machineId })
+ const { router, core } = setup({ machineId: () => machineId })
const opts = lane.opts!
- expect(opts).toMatchObject({ auth: deps.auth, backendWsBase: env.BACKEND_WS_URL, computerId: 'computer-1', autonomousEnv: 'test-env', identity: deps.identity })
+ expect(opts).toMatchObject({ backendWsBase: env.BACKEND_WS_URL, computerId: 'computer-1', autonomousEnv: 'test-env' })
+ // Its tokens are the core's session's, a forced refresh included; its sessions the gateway's.
+ expect(await opts.auth.accessToken({ force: true, failedToken: 'old' })).toBe('token')
+ expect(core.account.accessToken).toHaveBeenCalledWith({ force: true, failedToken: 'old' })
+ expect(opts.seal).toBe(core.account.lane)
+ expect(Object.keys(opts)).not.toContain('identity')
expect(opts.peer('other')).toEqual({ pub: 'pinned' })
expect(opts.peer('third')).toBeNull()
lane.peers.set('third', { pub: 'later' })
diff --git a/cli/src/services/fleet.ts b/cli/src/services/fleet.ts
index e4bcf4e1e..959ce6c3e 100644
--- a/cli/src/services/fleet.ts
+++ b/cli/src/services/fleet.ts
@@ -17,8 +17,6 @@ import type { CoreApi, CorePorts, RouteAnswer } from '../core/api.js'
import { DeviceFleet } from '../device/deviceFleet.js'
import { DeviceLink } from '../device/deviceLink.js'
import type { MachineListCache } from '../device/machineList.js'
-import type { AuthSessionManager } from '../lib/authSession.js'
-import type { Identity } from '../lib/e2ee/core.js'
import { MachinePeerStore } from '../lib/e2ee/machinePeers.js'
import { routeVoiceTask, type RouterAgent } from '../lib/voiceRouter.js'
import { FleetRouter } from './fleetRouter.js'
@@ -54,15 +52,9 @@ export interface FleetDeps {
machineName(): string
/** The window's tiles on its active tab, in tile order, as it last reported them. */
desk(): string[]
- /**
- * What the lane signs in and seals with, until it moves with the relay (step D3): the daemon's own
- * session manager, which shares a refresh in flight with the backend socket; the account's
- * environment; and this machine's E2EE identity, the one `harness link connect` proves knowledge
- * against.
- */
- auth: AuthSessionManager
+ /** The account's environment, which the lane names when it dials. Its tokens and its seal are the
+ * core's to give (`core.account`): this service holds no credential. */
autonomousEnv: string
- identity: Identity
}
/** Start the fleet: its port, through which ⌘K and the dial reach the router. The router itself is
@@ -85,13 +77,15 @@ export function startFleet(core: CoreApi, ports: CorePorts, deps: FleetDeps): Fl
const peers = new MachinePeerStore()
const link = new DeviceLink({
- auth: deps.auth,
+ // Signed in and sealed through the core (step 10, R3): its tokens are the core's session's, which
+ // shares a refresh in flight with the backend link, and its E2EE sessions are the gateway's, under the
+ // SAME identity `harness remote-password set` publishes and `harness link connect` proves knowledge
+ // against, so one link ceremony covers the desktop app's relay and the dial's lane alike.
+ auth: { accessToken: (options) => core.account.accessToken(options) },
backendWsBase: env.BACKEND_WS_URL,
computerId: deps.computerId(),
autonomousEnv: deps.autonomousEnv,
- // The SAME identity `harness remote-password set` publishes and `harness link connect` proves
- // knowledge against, so one link ceremony covers the desktop app's relay and the dial's lane alike.
- identity: deps.identity,
+ seal: core.account.lane,
// Read FRESH on every attach: `harness link connect` runs as a separate process, so a value captured
// at daemon start would keep answering "not linked" until the next restart.
peer: (machineId) => peers.get(machineId),
diff --git a/cli/src/services/processCoreApi.ts b/cli/src/services/processCoreApi.ts
index b24a67999..81a18445c 100644
--- a/cli/src/services/processCoreApi.ts
+++ b/cli/src/services/processCoreApi.ts
@@ -7,7 +7,7 @@
* What these services never ask (turns, questions, sign-in, the windows) answers as nothing, and a
* credential is refused: a service holds none (services/AGENTS.md).
*/
-import { resolveAgent, TERMINALS_OFF, type CoreApi } from '../core/api.js'
+import { LANE_OFF, resolveAgent, TERMINALS_OFF, type CoreApi } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
/** The agents a process was last told of. Those it is never told of read as none. */
@@ -57,6 +57,7 @@ export function processCoreApi(dataDir: string, service: string, view: AgentsVie
account: {
mintGridName: async () => null,
accessToken: () => Promise.reject(new Error(`${service} holds no credential`)),
+ lane: LANE_OFF,
privateGridName: async () => null,
machineName: () => null,
},
diff --git a/cli/src/services/searchProcess.ts b/cli/src/services/searchProcess.ts
index f10d3c0f8..d1460ef42 100644
--- a/cli/src/services/searchProcess.ts
+++ b/cli/src/services/searchProcess.ts
@@ -8,7 +8,7 @@
* process's alone: a crash or a leak in search costs search, and the master starts it again.
*/
import type { CoreApi } from '../core/api.js'
-import { emptyPorts, resolveAgent, TERMINALS_OFF } from '../core/api.js'
+import { emptyPorts, LANE_OFF, resolveAgent, TERMINALS_OFF } from '../core/api.js'
import { databaseHistory } from '../core/transcripts/databaseHistory.js'
import { ExternalSessions, OpenSessions } from '../lib/sessionSearch/external.js'
import { externalProviders } from '../lib/sessionSearch/externals/index.js'
@@ -67,6 +67,7 @@ export function searchCoreApi(
account: {
mintGridName: async () => null,
accessToken: () => Promise.reject(new Error('search holds no credential')),
+ lane: LANE_OFF,
privateGridName: async () => null,
machineName: () => null,
},
diff --git a/cli/src/services/viewersProcess.ts b/cli/src/services/viewersProcess.ts
index 4cc059f27..30d2bb7be 100644
--- a/cli/src/services/viewersProcess.ts
+++ b/cli/src/services/viewersProcess.ts
@@ -18,7 +18,7 @@
* no longer restarts every viewer: they stay up here, and the new core hears their URLs at once.
*/
import type { CoreApi } from '../core/api.js'
-import { emptyPorts, resolveAgent, TERMINALS_OFF } from '../core/api.js'
+import { emptyPorts, LANE_OFF, resolveAgent, TERMINALS_OFF } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'
import { startViewers } from './viewers.js'
@@ -73,6 +73,7 @@ export function viewersCoreApi(dataDir: string, sessions: ReadonlyMap<string, Re
account: {
mintGridName: async () => null,
accessToken: () => Promise.reject(new Error('the viewers hold no credential')),
+ lane: LANE_OFF,
privateGridName: async () => null,
machineName: () => null,
},
diff --git a/cli/src/services/workspacesProcess.ts b/cli/src/services/workspacesProcess.ts
index e989e4e74..c34001ee4 100644
--- a/cli/src/services/workspacesProcess.ts
+++ b/cli/src/services/workspacesProcess.ts
@@ -13,7 +13,7 @@
* alone: a hang or a crash in it costs workspaces, and the master starts them again.
*/
import type { CoreApi } from '../core/api.js'
-import { emptyPorts, resolveAgent, TERMINALS_OFF } from '../core/api.js'
+import { emptyPorts, LANE_OFF, resolveAgent, TERMINALS_OFF } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import { runServiceProcess, type CoreConnection, type ServiceProcess } from './process.js'
import { startWorkspaces } from './workspaces.js'
@@ -75,6 +75,7 @@ export function workspacesCoreApi(
account: {
mintGridName: async () => null,
accessToken: () => Promise.reject(new Error('workspaces hold no credential')),
+ lane: LANE_OFF,
privateGridName: async () => null,
machineName: () => null,
},
diff --git a/cli/src/sharing/relay.ts b/cli/src/sharing/relay.ts
index f2f5d7ac7..6507e95db 100644
--- a/cli/src/sharing/relay.ts
+++ b/cli/src/sharing/relay.ts
@@ -19,7 +19,7 @@ export class SharingEndedError extends Error {}
/** One invitation per connection. Never promoted into a full machine link or a shared connection pool. */
export class HarnessShareRelay {
private sessions = new Set<() => void>()
- constructor(private readonly auth: AuthSessionManager, private readonly backendWsBase: string,
+ constructor(private readonly auth: Pick<AuthSessionManager, 'accessToken'>, private readonly backendWsBase: string,
private readonly environment: string, private readonly discover: () => Promise<SharedMachineReference[]>) {}
async acquire(machineId: string, shareId: string, sink: LocalClientSink,
onClosed: (code: number, reason: string) => void): Promise<RelaySession> {
diff --git a/cli/src/testing/fakeCore.ts b/cli/src/testing/fakeCore.ts
index a89ad34f1..447cd4965 100644
--- a/cli/src/testing/fakeCore.ts
+++ b/cli/src/testing/fakeCore.ts
@@ -38,6 +38,14 @@ export function fakeCore(over: Overrides = {}): CoreApi {
account: {
mintGridName: vi.fn(async () => null),
accessToken: vi.fn(async () => 'token'),
+ lane: {
+ hello: vi.fn(async () => ({ type: 'e2e_hello', payload: {} })),
+ welcome: vi.fn(async () => true),
+ rekey: vi.fn(async () => {}),
+ seal: vi.fn(async (_machineId: string, frame: Record<string, unknown>) => ({ frame })),
+ open: vi.fn(async (_machineId: string, frame: Record<string, unknown>) => ({ frame })),
+ drop: vi.fn(),
+ },
privateGridName: vi.fn(async () => null),
machineName: vi.fn(() => null),
...over.account,