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.

feat(e2ee): one link works both ways; linked machines and phones form a trust group (#406)

0xken15a191e67b5702
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 3769d9d2c..586f04aaa 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -1057,6 +1057,19 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('refuses a trust-group roster swap that is not over an E2EE session (a local client has no identity)', async () => {
+ const socket = new BackendSocket('token')
+ const handle = vi.fn(() => ({}))
+ socket.groupSync = { handle }
+ const frames: Array<Record<string, unknown>> = []
+ socket.registerLocalClient('local:group', { sendFrame: frame => { frames.push(frame); return true }, sendBinary: () => true })
+ socket.handleLocalFrame('local:group', { type: 'group_sync', payload: { requestId: 'g1', members: [] } })
+ await vi.waitFor(() => expect(frames).toContainEqual({ type: 'group_sync_result', payload: { requestId: 'g1', error: 'UNSUPPORTED' } }))
+ expect(handle).not.toHaveBeenCalled()
+ await socket.unregisterLocalClient('local:group')
+ await socket.stop()
+ })
+
it('serves machine stats locally without blocking the next RPC while sampling', async () => {
let finish!: (value: machineResources.MachineResources) => void
const read = vi.spyOn(machineResources, 'readMachineResources').mockImplementation(
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 86e11ff07..3be513ae2 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -99,7 +99,8 @@ import { hermesDbForSession } from './lib/hermesHome.js'
import { readDevinMessages } from './engines/devin/reader.js'
import { readOpencodeMessages } from './engines/opencode/reader.js'
import { readKiloMessages } from './engines/kilo/reader.js'
-import { E2eeManager, type PairResult } from './lib/e2ee/manager.js'
+import { E2eeManager, type LinkedPeer, type PairResult } from './lib/e2ee/manager.js'
+import { MachinePeerStore } from './lib/e2ee/machinePeers.js'
import type { TerminalStreamManager } from './lib/terminalStreamManager.js'
import {
decodeTerminalHop,
@@ -521,6 +522,8 @@ export class BackendSocket {
onTerminalHandoff: ((tmuxPane: string) => string | null) | null = null
/** What the daemon knows about an agent's DSH companions (viewer URL, verdict); null when nothing. */
harnessSharing: HarnessShareOwner | null = null
+ /** Answers the trust group's roster exchange (`group_sync`); null until the daemon wires it. */
+ groupSync: { handle: (peerPub: string, payload: Record<string, unknown>) => Record<string, unknown> } | null = null
dshFrameProvider: ((session: RegisteredSession) => AgentDshContext | null) | null = null
viewerTargetProvider: ((agentId: string) => string | null) | null = null
readonly viewerForwarder = new ViewerForwarder({
@@ -706,6 +709,10 @@ export class BackendSocket {
private readonly directDeviceSinks = new Map<string, (frame: Record<string, unknown>) => void>()
private readonly directDevicePins = new Map<string, string>()
onDirectDeviceRevoked?: (fingerprint: string) => void
+ /** A peer linked here over the remote password (after it is trusted and, for a machine, pinned back). */
+ onPeerLinked?: (peer: LinkedPeer) => void
+ /** A person unpaired this identity here (not the trust group removing it). */
+ onUnpaired?: (identityPub: string) => void
/** A connection that is, or is pairing as, an Autonomous device — what the device dump records. */
private isDeviceConn(connId: string): boolean {
return this.directDeviceSinks.has(connId) || this.e2ee.sessionRole(connId) === 'device'
@@ -778,6 +785,15 @@ export class BackendSocket {
onIdentityPaired: (connId, pub) => { if (this.directDeviceSinks.has(connId)) this.directDevicePins.set(connId, pub) },
onIdentityRevoked: identity => { this.autonomousDeviceRelay?.revoke(identity); this.onDirectDeviceRevoked?.(fingerprint(b64d(identity))) },
onSessionDropped: (connId) => this.viewerForwarder.closeConnection(connId),
+ onPeerLinked: (peer) => {
+ // The mutual half of a password link: a machine that proved this one's password is pinned back,
+ // so this machine can dial it without that machine's own password.
+ if (peer.kind === 'machine' && peer.machineId && peer.machineId !== this.machineId) {
+ new MachinePeerStore().pin(peer.machineId, peer.pub, peer.label)
+ }
+ this.onPeerLinked?.(peer)
+ },
+ onUnpaired: (pub) => this.onUnpaired?.(pub),
})
this.terminalP2p = new TerminalP2pResponderPool({
sendSignal: (connId, type, payload) => this.sendP2pSignal(connId, type, payload),
@@ -817,6 +833,17 @@ export class BackendSocket {
clearRemotePassword(): void {
this.e2ee.clearRemotePassword()
}
+ /** `harness link connect` — trust the machine this one just linked as a client too (mutual link). */
+ trustPeer(peer: LinkedPeer): void {
+ this.e2ee.trustPeer(peer)
+ }
+ /** Stop trusting `pub` here (unlink / trust-group removal); true when it was trusted. */
+ untrustPeer(pub: string): boolean {
+ return this.e2ee.untrustPeer(pub)
+ }
+ pairedPeers(): ReturnType<E2eeManager['pairedPeers']> {
+ return this.e2ee.pairedPeers()
+ }
/** `harness remote-password status` — whether one is set, and its fingerprint. */
remotePasswordStatus(): ReturnType<E2eeManager['remotePasswordStatus']> {
return this.e2ee.remotePasswordStatus()
@@ -1659,6 +1686,15 @@ export class BackendSocket {
return
}
+ // Trust-group roster exchange: only over an E2EE session, from the identity that session proved —
+ // the roster carries the keys this machine trusts, and the peer's own entry must be that identity.
+ if (type === 'group_sync') {
+ const peerPub = local ? null : this.e2ee.sessionIdentity(connId)
+ if (!peerPub || this.e2ee.sessionRole(connId) !== 'web' || !this.groupSync) { reply(type, requestId, { error: 'UNSUPPORTED' }); return }
+ try { reply(type, requestId, this.groupSync.handle(peerPub, payload)) } catch { reply(type, requestId, { error: 'GROUP_SYNC_FAILED' }) }
+ return
+ }
+
if (type.startsWith('viewer_')) {
if (VIEWER_DOWN_TYPES.has(type) && (local || this.e2ee.sessionRole(connId) === 'web')) {
this.viewerForwarder.handle(connId, type, payload)
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index c4fed14b5..c70c33e41 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -181,7 +181,10 @@ import { E2eeStore } from './lib/e2ee/store.js'
import { isLoopbackRequest, loopbackHosts } from './lib/loopbackRequest.js'
import { b64e } from './lib/e2ee/core.js'
import { MachinePeerStore } from './lib/e2ee/machinePeers.js'
-import { connectWithPassword } from './lib/e2ee/relayClient.js'
+import { connectWithPassword, type PwConnectProgress } from './lib/e2ee/relayClient.js'
+import type { LinkedPeer } from './lib/e2ee/manager.js'
+import { GroupSyncer, relayRequester, SELF_STAMP } from './lib/e2ee/groupSyncer.js'
+import { TrustGroupStore, type GroupMember } from './lib/e2ee/trustGroup.js'
import {
startSelfUpdater, restore as restoreUpdate, confirm as confirmUpdate,
fetchManifest, downloadVerified, canary, stage, semverGt, isLocalDevBuild,
@@ -419,6 +422,10 @@ every future connect, until you change or clear it:
(--name=<label> names the machine in messages instead of its id)
harness link list list machines this one has linked
harness link unlink <id> remove a linked machine's trust
+ harness group list machines and phones that trust each other through links: link one
+ machine and every member reaches it both ways, no more passwords
+ harness group sync compare with every reachable member now (it also happens on its own)
+ harness group remove <id> drop a member (machine id, # or fingerprint) from every member
(both \`remote-password set\` and \`link connect\` prompt for the password interactively, or read one
line from stdin with --stdin; add --json for NDJSON output instead of the human-readable text)
@@ -1830,6 +1837,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// not. Both are just "the id this daemon serves under" to everything downstream — the local
// websocket binds clients to it, the app selects by it — and the backend binds a machine to the
// computer id at login, so a sign-in ADOPTS this machine rather than minting a second one.
+ // The trust group (lib/e2ee/groupSyncer.ts). Built once the relay pool exists, far below; the hook
+ // handlers and the backend callbacks declared before then reach it through this.
+ let groupSyncer: GroupSyncer | null = null
const backend = new BackendSocket(session?.machineId ?? computerId(), auth, (connected) => {
if (!connected) return
const sessions = registry.advertised()
@@ -3875,6 +3885,19 @@ async function runForeground(session: AuthSession | null): Promise<void> {
},
onClearRemotePassword: () => { backend.clearRemotePassword(); return { status: 200, body: { ok: true } } },
onRemotePasswordStatus: () => ({ status: 200, body: backend.remotePasswordStatus() }),
+ onTrustLinkedPeer: (peer) => {
+ backend.trustPeer({ ...peer, kind: 'machine' })
+ groupSyncer?.linked({ ...peer, kind: 'machine' })
+ return { status: 200, body: { ok: true } }
+ },
+ onGroupList: () => ({ status: 200, body: { self: groupSelf(), members: new TrustGroupStore().list() } }),
+ onGroupSync: () => { void groupSyncer?.syncAll(); return { status: 200, body: { ok: true } } },
+ onGroupRemove: (selector) => {
+ const found = findGroupMember(selector)
+ if (!found.ok) return { status: found.error === 'AMBIGUOUS' ? 409 : 404, body: { error: found.error } }
+ groupSyncer?.remove(found.pub)
+ return { status: 200, body: { label: found.label, fingerprint: found.fingerprint } }
+ },
// Local dashboard (GET /api/status): adapter health + computer fingerprint + local pairings. It
// deliberately does NOT expose chat/transcripts — those live in the cloud web (WEB_URL/commander).
onStatus: async () => ({
@@ -3983,7 +4006,30 @@ async function runForeground(session: AuthSession | null): Promise<void> {
env.BACKEND_WS_URL.replace(/\/$/, ''),
relayIdentityStore.getIdentity(),
new MachinePeerStore(),
+ { onSessionReady: (machineId) => groupSyncer?.sessionOpened(machineId) },
)
+ // Every machine and phone linked to this one, directly or through another member, trusts every other:
+ // rosters are swapped over any session that opens, and pushed on whenever they change.
+ groupSyncer = new GroupSyncer({
+ store: new TrustGroupStore(),
+ peers: new MachinePeerStore(),
+ self: groupSelf,
+ trust: (peer) => backend.trustPeer(peer),
+ untrust: (pub) => { backend.untrustPeer(pub) },
+ paired: () => backend.pairedPeers(),
+ request: relayRequester(relayPool, () => readAuthSession()?.autonomousEnv ?? env.AUTONOMOUS_ENV),
+ dropSessions: (machineId) => { relayPool.invalidate(machineId); relayPool.invalidateIsolated(machineId) },
+ reachable: () => {
+ // Only a list the backend answered says who is offline; otherwise try every member.
+ const { machines, source } = machineListCache.list()
+ return source !== 'backend' ? null : new Set(machines.filter((m) => m.state !== 'offline').map((m) => m.machineId))
+ },
+ log: (line) => console.log(line),
+ })
+ backend.groupSync = groupSyncer
+ backend.onPeerLinked = (peer) => groupSyncer?.linked(peer)
+ backend.onUnpaired = (pub) => groupSyncer?.unpaired(pub)
+ if (session?.machineId) groupSyncer.start()
// Spoken tasks go to the WINDOW to be routed, not to the copy of the router in this process.
//
// Built here because both ends need it: the local socket hands it the window's replies, and the cable
@@ -6771,51 +6817,36 @@ async function linkConnectCommand(machineId: string | undefined, stdin: boolean,
console.log(' this proves you know it; nothing needs approving there.\n')
password = await promptPassword(` Remote password for ${machineId}: `)
}
- const auth = new AuthSessionManager(backendHttpBase())
- let accessToken: string
- try {
- accessToken = await auth.accessToken()
- } catch (err) {
- const detail = err instanceof Error ? err.message : String(err)
- const message = `Could not refresh this computer's SSO session (${detail}). Run: harness login`
- if (json) console.log(JSON.stringify({ ok: false, error: 'AUTH_FAILED', message }))
- else console.error(`\n ✗ ${message}\n`)
- process.exit(1)
- return
- }
- const store = new E2eeStore()
- store.init()
- const result = await connectWithPassword({
- targetMachineId: machineId,
- password,
- selfIdentity: store.getIdentity(),
- accessToken,
- backendWsBase: env.BACKEND_WS_URL.replace(/\/$/, ''),
- autonomousEnv: session.autonomousEnv,
- onProgress: json ? (stage) => console.log(JSON.stringify({ stage })) : undefined,
- })
+ const result = await linkMachineWithPassword(machineId, password, displayName, json ? (stage) => console.log(JSON.stringify({ stage })) : undefined)
if (!result.ok) {
- const message = humanizeLinkError(result.error, displayName || machineId, result.retryAt)
if (json) {
- console.log(JSON.stringify({ ok: false, error: result.error, message, ...(result.retryAt !== undefined ? { retryAt: result.retryAt } : {}) }))
+ console.log(JSON.stringify({ ok: false, error: result.error, message: result.message, ...(result.retryAt !== undefined ? { retryAt: result.retryAt } : {}) }))
} else {
- console.error(`\n ✗ ${message}\n`)
+ console.error(`\n ✗ ${result.message}\n`)
}
process.exit(1)
return
}
- new MachinePeerStore().pin(machineId, b64e(result.peerPub), 'harness link', Date.now())
- if (json) { console.log(JSON.stringify({ ok: true, fingerprint: result.fingerprint, machineId })); process.exit(0) }
- console.log(`\n ✓ Linked machine ${machineId}`)
- console.log(` fingerprint ${result.fingerprint} — verify it matches \`harness remote-password status\`'s output on the other machine\n`)
+ if (json) { console.log(JSON.stringify({ ok: true, fingerprint: result.fingerprint, machineId, mutual: result.mutual })); process.exit(0) }
+ console.log(`\n ✓ Linked machine ${machineId}${result.mutual ? ' — both ways' : ''}`)
+ console.log(` fingerprint ${result.fingerprint} — verify it matches \`harness remote-password status\`'s output on the other machine`)
+ if (!result.mutual) console.log(` ${machineId} runs an older harness: it can't reach this machine back until it is updated and linked again.`)
+ console.log('')
process.exit(0)
}
/**
* The link itself, as `harness link connect` and `harness remote` both do it: this computer's SSO
* token and identity, the remote password proved against THAT machine, and its peer pinned here.
+ * This machine says who it is inside the handshake, so a target that understands it pins it back;
+ * when it did (`mutual`), that machine is trusted here as a client too — one link, both directions.
*/
-async function linkMachineWithPassword(machineId: string, password: string, displayName?: string): Promise<{ ok: true; fingerprint: string } | { ok: false; error: string; message: string }> {
+async function linkMachineWithPassword(
+ machineId: string,
+ password: string,
+ displayName?: string,
+ onProgress?: (stage: PwConnectProgress) => void,
+): Promise<{ ok: true; fingerprint: string; mutual: boolean } | { ok: false; error: string; message: string; retryAt?: number }> {
const session = readAuthSession()
if (!session) return { ok: false, error: 'NOT_SIGNED_IN', message: 'Not signed in. Run: harness login' }
const auth = new AuthSessionManager(backendHttpBase())
@@ -6835,10 +6866,55 @@ async function linkMachineWithPassword(machineId: string, password: string, disp
accessToken,
backendWsBase: env.BACKEND_WS_URL.replace(/\/$/, ''),
autonomousEnv: session.autonomousEnv,
+ onProgress,
+ self: { kind: 'machine', label: hostname(), ...(session.machineId ? { machineId: session.machineId } : {}) },
})
- if (!result.ok) return { ok: false, error: result.error, message: humanizeLinkError(result.error, displayName || machineId, result.retryAt) }
- new MachinePeerStore().pin(machineId, b64e(result.peerPub), 'harness link', Date.now())
- return { ok: true, fingerprint: result.fingerprint }
+ if (!result.ok) return { ok: false, error: result.error, message: humanizeLinkError(result.error, displayName || machineId, result.retryAt), retryAt: result.retryAt }
+ const label = displayName || machineId
+ new MachinePeerStore().pin(machineId, b64e(result.peerPub), label, Date.now())
+ const mutual = result.mutual && !!session.machineId
+ if (mutual) await trustLinkedMachine({ pub: b64e(result.peerPub), machineId, kind: 'machine', label })
+ return { ok: true, fingerprint: result.fingerprint, mutual }
+}
+
+/** Trust a just-linked machine as a client of THIS one. The running daemon holds paired.json in memory
+ * (and rewrites it whole), so the write has to go through it; with no daemon, the file is written directly. */
+async function trustLinkedMachine(peer: LinkedPeer): Promise<void> {
+ try {
+ const res = await fetch(`http://127.0.0.1:${daemonPort()}/api/link/trust-peer`, {
+ method: 'POST',
+ headers: { 'x-adapter-local': '1', 'content-type': 'application/json' },
+ body: JSON.stringify(peer),
+ })
+ if (res.ok) return
+ } catch { /* fall back to the disk-backed store below */ }
+ const store = new E2eeStore()
+ store.init()
+ if (!store.isPaired(peer.pub)) store.addPaired(peer.pub, peer.label, Date.now(), 'web', { machineId: peer.machineId, kind: peer.kind })
+ // The daemon seeds the group from this pin and pairing when it next starts, and syncs from there.
+}
+
+/** This machine as its trust group knows it — see groupSyncer.ts's SELF_STAMP for the stamp. */
+let groupSelfPub: string | null = null
+function groupSelf(): GroupMember {
+ groupSelfPub ??= b64e(new E2eeStore().init().pub)
+ const machineId = readAuthSession()?.machineId
+ return { pub: groupSelfPub, kind: 'machine', label: hostname(), at: SELF_STAMP, ...(machineId ? { machineId } : {}) }
+}
+
+/** A trust-group member by machine id, list number, or fingerprint (full or unique prefix). */
+function findGroupMember(selector: string): { ok: true; pub: string; label: string; fingerprint: string } | { ok: false; error: 'NOT_FOUND' | 'AMBIGUOUS' } {
+ const members = new TrustGroupStore().list()
+ const norm = (v: string): string => v.toUpperCase().replace(/[·\s-]/g, '')
+ const byIndex = /^\d+$/.test(selector) ? members[Number(selector) - 1] : undefined
+ const byMachine = members.find((m) => m.machineId === selector)
+ const hit = byMachine ?? byIndex ?? (() => {
+ const matches = members.filter((m) => norm(m.fingerprint).startsWith(norm(selector)))
+ return matches.length > 1 ? 'AMBIGUOUS' as const : matches[0]
+ })()
+ if (hit === 'AMBIGUOUS') return { ok: false, error: 'AMBIGUOUS' }
+ if (!hit || !selector.trim()) return { ok: false, error: 'NOT_FOUND' }
+ return { ok: true, pub: hit.pub, label: hit.label, fingerprint: hit.fingerprint }
}
/** `harness link list` — machines this one has linked (CLI-to-CLI/machine-node trust, not browsers). */
@@ -6860,17 +6936,74 @@ async function linkListCommand(): Promise<void> {
/** `harness link unlink <machineId>` — remove a linked machine's trust pin. */
async function linkUnlinkCommand(machineId: string | undefined): Promise<void> {
if (!machineId) { console.error('Usage: harness link unlink <machineId> (see: harness link list)'); process.exit(1) }
- const removed = new MachinePeerStore().unlink(machineId)
+ // Through the daemon: the machine leaves the trust group, so every other member drops it too.
+ const viaGroup = await daemonGroupRemove(machineId as string)
+ const removed = new MachinePeerStore().unlink(machineId as string) || viaGroup
if (!removed) {
console.error(`\n ✗ No linked machine matches "${machineId}".`)
console.error(' ▸ Run `harness link list` to see what\'s linked.\n')
process.exit(1)
return
}
- console.log(`\n ✓ Unlinked ${machineId}\n`)
+ console.log(`\n ✓ Unlinked ${machineId}${viaGroup ? ' — and removed from your trust group' : ''}\n`)
process.exit(0)
}
+/** Ask the running daemon to remove a trust-group member; false when there is no daemon or no match. */
+async function daemonGroupRemove(selector: string): Promise<boolean> {
+ try {
+ const res = await fetch(`http://127.0.0.1:${daemonPort()}/api/group/remove`, {
+ method: 'POST',
+ headers: { 'x-adapter-local': '1', 'content-type': 'application/json' },
+ body: JSON.stringify({ selector }),
+ })
+ return res.ok
+ } catch {
+ return false
+ }
+}
+
+/** `harness group list|sync|remove` — every machine and phone that trusts every other through links. */
+async function groupCommand(sub: string | undefined, arg: string | undefined, json: boolean): Promise<void> {
+ if (!sub || sub === 'list') {
+ const members = new TrustGroupStore().list()
+ if (json) { console.log(JSON.stringify({ members })); process.exit(0) }
+ if (!members.length) {
+ console.log('\n No trust group yet. Link another machine (`harness link connect <machineId>`) or a phone to start one.\n')
+ process.exit(0)
+ }
+ console.log('\n Trust group — each of these reaches every other without a password:\n')
+ members.forEach((m, i) => {
+ const id = m.kind === 'machine' ? m.machineId : 'viewer app'
+ console.log(` ${String(i + 1).padStart(2)}. ${m.label} ${id} ${m.fingerprint}`)
+ })
+ console.log('')
+ process.exit(0)
+ }
+ if (sub === 'sync') {
+ try {
+ const res = await fetch(`http://127.0.0.1:${daemonPort()}/api/group/sync`, { method: 'POST', headers: { 'x-adapter-local': '1' } })
+ if (!res.ok) throw new Error(String(res.status))
+ } catch {
+ console.error('\n ✗ Harness is not running here. Run: harness start\n')
+ process.exit(1)
+ }
+ console.log('\n ✓ Comparing with every reachable member now.\n')
+ process.exit(0)
+ }
+ if (sub === 'remove') {
+ if (!arg) { console.error('Usage: harness group remove <machineId|#|fingerprint> (see: harness group list)'); process.exit(1) }
+ if (!(await daemonGroupRemove(arg as string))) {
+ console.error(`\n ✗ Could not remove "${arg}" — no member matches, or harness is not running here (harness start).\n`)
+ process.exit(1)
+ }
+ console.log(`\n ✓ Removed ${arg} from the trust group. Every member drops it as they sync.\n`)
+ process.exit(0)
+ }
+ console.error(`Unknown command: group ${sub}`)
+ process.exit(1)
+}
+
/** One row of `GET /api/machines`. Only the fields this CLI shows are declared. */
interface OwnerMachineRow {
machineId: string
@@ -7301,6 +7434,9 @@ switch (cmd) {
else if (args[0] === 'unlink') linkUnlinkCommand(args[1]).catch(onError)
else { console.error(`Unknown command: link ${args[0] ?? ''}`); usage(1) }
break
+ case 'group':
+ groupCommand(args[0], args[1], flags.includes('--json')).catch(onError)
+ break
case 'remote-password':
if (args[0] === 'set') remotePasswordSetCommand(flags.includes('--json'), flags.includes('--stdin')).catch(onError)
else if (args[0] === 'clear') remotePasswordClearCommand(flags.includes('--json')).catch(onError)
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index 36941b284..11a700ca9 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -414,6 +414,40 @@ describe('requests must name this server', () => {
})
})
+describe('the trust group endpoints', () => {
+ const local = { 'x-adapter-local': '1', 'content-type': 'application/json' }
+ const key = Buffer.alloc(32, 7).toString('base64')
+ const machineId = 'a'.repeat(32)
+
+ it('trust-peer takes only a real key and machine id, and trims the label', async () => {
+ const onTrustLinkedPeer = vi.fn(() => ({ status: 200, body: { ok: true } }))
+ const { base } = await start({ onTrustLinkedPeer })
+ const post = (body: unknown, headers: Record<string, string> = local) =>
+ fetch(`${base}/api/link/trust-peer`, { method: 'POST', headers, body: JSON.stringify(body) })
+ for (const bad of [{ pub: 'x', machineId }, { pub: key, machineId: 'nope' }, { machineId }, { pub: `${key}AA`, machineId }]) {
+ expect((await post(bad)).status, JSON.stringify(bad)).toBe(400)
+ }
+ expect((await post({ pub: key, machineId }, { 'content-type': 'application/json' })).status).toBe(403)
+ expect((await post({ pub: key, machineId, label: ` ${'n'.repeat(80)} ` })).status).toBe(200)
+ expect(onTrustLinkedPeer).toHaveBeenCalledTimes(1)
+ expect(onTrustLinkedPeer).toHaveBeenCalledWith({ pub: key, machineId, label: 'n'.repeat(60) })
+ })
+
+ it('group remove and sync are local writes; list is readable', async () => {
+ const onGroupRemove = vi.fn(() => ({ status: 200, body: { label: 'b', fingerprint: 'fp' } }))
+ const onGroupSync = vi.fn(() => ({ status: 200, body: { ok: true } }))
+ const onGroupList = vi.fn(() => ({ status: 200, body: { members: [] } }))
+ const { base } = await start({ onGroupRemove, onGroupSync, onGroupList })
+ expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"selector":"1"}' })).status).toBe(403)
+ expect((await fetch(`${base}/api/group/sync`, { method: 'POST' })).status).toBe(403)
+ expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: local, body: '{"selector":" "}' })).status).toBe(400)
+ expect((await fetch(`${base}/api/group/remove`, { method: 'POST', headers: local, body: '{"selector":" 1 "}' })).status).toBe(200)
+ expect(onGroupRemove).toHaveBeenCalledWith('1')
+ expect((await fetch(`${base}/api/group/sync`, { method: 'POST', headers: local })).status).toBe(200)
+ expect(await (await fetch(`${base}/api/group`)).json()).toEqual({ members: [] })
+ })
+})
+
describe('the daemon socket', () => {
function viaSocket(socketPath: string, method: string, path: string, headers: Record<string, string> = {}): Promise<number> {
return new Promise((resolve, reject) => {
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index 0496964e2..5b5d974b2 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -109,6 +109,13 @@ export interface HookServerHandlers {
onClearRemotePassword?: () => PairOutcome
/** `harness remote-password status` — whether one is set, and its fingerprint. */
onRemotePasswordStatus?: () => PairOutcome
+ /** `harness link connect` — the machine this one just linked pinned it back, so trust that machine
+ * here too (the mutual half of the link). Goes through the daemon: it holds paired.json in memory. */
+ onTrustLinkedPeer?: (peer: { pub: string; machineId: string; label: string }) => PairOutcome
+ /** `harness group list|sync|remove` — the trust group this machine belongs to (groupSyncer.ts). */
+ onGroupList?: () => PairOutcome
+ onGroupSync?: () => PairOutcome
+ onGroupRemove?: (selector: string) => PairOutcome
/** Local dashboard status snapshot (GET /api/status). */
onStatus?: () => Record<string, unknown> | Promise<Record<string, unknown>>
/** Recent adapter log tail (GET /api/logs). */
@@ -645,6 +652,40 @@ export function startHookServer(
const out = handlers.onClearRemotePassword(); json(out.status, out.body); return
}
+ // `harness link connect` → trust the machine just linked back, on the daemon's live E2EE state.
+ if (req.method === 'POST' && url === '/api/link/trust-peer') {
+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
+ if (!handlers.onTrustLinkedPeer) { json(503, { error: 'UNAVAILABLE' }); return }
+ let body: { pub?: unknown; machineId?: unknown; label?: unknown }
+ try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
+ const isKey = typeof body.pub === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(body.pub) // 32-byte Ed25519, base64
+ if (!isKey || typeof body.machineId !== 'string' || !/^[a-f0-9]{32}$/.test(body.machineId)) { json(400, { error: 'BAD_PEER' }); return }
+ const label = typeof body.label === 'string' && body.label.trim() ? body.label.trim().slice(0, 60) : body.machineId
+ const out = handlers.onTrustLinkedPeer({ pub: body.pub as string, machineId: body.machineId, label })
+ json(out.status, out.body); return
+ }
+
+ // `harness group list` → the trust group's members. Read-only (keys and labels, no secrets).
+ if (req.method === 'GET' && url === '/api/group') {
+ if (!handlers.onGroupList) { json(503, { error: 'UNAVAILABLE' }); return }
+ const out = handlers.onGroupList(); json(out.status, out.body); return
+ }
+ // `harness group sync` → compare rosters with every reachable member now.
+ if (req.method === 'POST' && url === '/api/group/sync') {
+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
+ if (!handlers.onGroupSync) { json(503, { error: 'UNAVAILABLE' }); return }
+ const out = handlers.onGroupSync(); json(out.status, out.body); return
+ }
+ // `harness group remove <id|#|fp>` / `harness link unlink` → drop a member everywhere.
+ if (req.method === 'POST' && url === '/api/group/remove') {
+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
+ if (!handlers.onGroupRemove) { json(503, { error: 'UNAVAILABLE' }); return }
+ let body: { selector?: unknown }
+ try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
+ if (typeof body.selector !== 'string' || !body.selector.trim()) { json(400, { error: 'MISSING_SELECTOR' }); return }
+ const out = handlers.onGroupRemove(body.selector.trim()); json(out.status, out.body); return
+ }
+
// `harness remote-password status` → whether one is set, and its fingerprint. Read-only, same
// gating tier as /api/pairs.
if (req.method === 'GET' && url === '/api/remote-password/status') {
diff --git a/cli/src/lib/e2ee/applicationFrames.ts b/cli/src/lib/e2ee/applicationFrames.ts
index bc1c707b8..a829e5366 100644
--- a/cli/src/lib/e2ee/applicationFrames.ts
+++ b/cli/src/lib/e2ee/applicationFrames.ts
@@ -14,7 +14,8 @@ import { VIEWER_DOWN_TYPES } from '../viewerWire.js'
const FLEET_REQUESTS = new Set(['grid_fleet_capabilities', 'grid_fleet_run', 'grid_fleet_cancel',
'grid_fleet_models_list', 'grid_fleet_model_download', 'grid_fleet_model_start', 'grid_fleet_model_stop'])
const FLEET_RESULTS = new Set([...FLEET_REQUESTS].map(type => `${type}_result`))
-const MACHINE_REQUESTS = new Set(['git_project_info', 'git_pull_request', 'machine_resources', 'api_connections'])
+// `group_sync`: the trust-group roster exchange (groupSyncer.ts) — keys, so always sealed.
+const MACHINE_REQUESTS = new Set(['git_project_info', 'git_pull_request', 'machine_resources', 'api_connections', 'group_sync'])
const MACHINE_RESULTS = new Set([...MACHINE_REQUESTS].map(type => `${type}_result`))
export const encryptDownFrame = (type: string): boolean =>
isEncryptedDownType(type) || MACHINE_REQUESTS.has(type) || FLEET_REQUESTS.has(type) || SHARE_REQUEST_TYPES.has(type) || VIEWER_DOWN_TYPES.has(type)
diff --git a/cli/src/lib/e2ee/groupSyncer.spec.ts b/cli/src/lib/e2ee/groupSyncer.spec.ts
new file mode 100644
index 000000000..ba070ee58
--- /dev/null
+++ b/cli/src/lib/e2ee/groupSyncer.spec.ts
@@ -0,0 +1,353 @@
+import { describe, it, expect, beforeAll, afterEach, vi } from 'vitest'
+import { mkdtempSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// ADAPTER_DATA_DIR must be set before config/env.js loads (see manager.test.ts). Every store here is
+// in memory anyway — several "machines" share this one process.
+type Frame = Record<string, unknown>
+let C: typeof import('./core.js')
+let G: typeof import('./trustGroup.js')
+let S: typeof import('./groupSyncer.js')
+
+beforeAll(async () => {
+ process.env.ADAPTER_DATA_DIR = mkdtempSync(join(tmpdir(), 'e2ee-groupsync-'))
+ C = await import('./core.js')
+ G = await import('./trustGroup.js')
+ S = await import('./groupSyncer.js')
+})
+
+afterEach(() => { vi.useRealTimers() })
+
+interface Pin { machineId: string; pub: string; label: string; linkedAt: number }
+class MemPeers {
+ pins = new Map<string, Pin>()
+ get(id: string): Pin | null { return this.pins.get(id) ?? null }
+ pin(machineId: string, pub: string, label: string, at = 1): void { this.pins.set(machineId, { machineId, pub, label, linkedAt: at }) }
+ unlink(id: string): boolean { return this.pins.delete(id) }
+ list(): Array<Pin & { fingerprint: string }> { return [...this.pins.values()].map((p) => ({ ...p, fingerprint: 'fp' })) }
+}
+
+interface Node {
+ name: string
+ pub: string
+ machineId: string | null
+ peers: MemPeers
+ trusted: Map<string, { kind?: string; machineId?: string }>
+ syncer: InstanceType<typeof S.GroupSyncer>
+ online: boolean
+ droppedSessions: string[]
+}
+
+/** A small fleet whose "relay" is a direct call: a request reaches the target only if the caller pinned
+ * it and the target trusts the caller — exactly what the real hello/welcome would allow. */
+function fleet(): { add: (name: string, machine?: boolean) => Node; link: (joiner: Node, target: Node) => void; nodes: Node[] } {
+ const nodes: Node[] = []
+ let clock = 1_000
+ const add = (name: string, machine = true): Node => {
+ const memStore = new (class extends G.TrustGroupStore {
+ roster: import('./trustGroup.js').Roster = { members: [], removed: [] }
+ override read() { return JSON.parse(JSON.stringify(this.roster)) }
+ override write(r: import('./trustGroup.js').Roster) { this.roster = JSON.parse(JSON.stringify(r)) }
+ held = new Set<string>()
+ override blocked() { return new Set(this.held) }
+ override block(pub: string) { this.held.add(pub) }
+ override unblock(pub: string) { this.held.delete(pub) }
+ })()
+ const node = {
+ name,
+ pub: C.b64e(C.newIdentity().pub),
+ machineId: machine ? name.repeat(32).slice(0, 32) : null,
+ peers: new MemPeers(),
+ trusted: new Map(),
+ online: true,
+ droppedSessions: [],
+ } as unknown as Node
+ node.syncer = new S.GroupSyncer({
+ store: memStore,
+ peers: node.peers as unknown as import('./machinePeers.js').MachinePeerStore,
+ self: () => ({ pub: node.pub, kind: machine ? 'machine' : 'viewer', label: name, at: S.SELF_STAMP, ...(node.machineId ? { machineId: node.machineId } : {}) }),
+ trust: (p) => { node.trusted.set(p.pub, { kind: p.kind, machineId: p.machineId }) },
+ untrust: (p) => { node.trusted.delete(p) },
+ paired: () => [...node.trusted].map(([identityPub, t]) => ({ identityPub, label: 'x', pairedAt: 1, role: 'web' as const, ...(t.kind ? { kind: t.kind as 'machine' } : {}), ...(t.machineId ? { machineId: t.machineId } : {}) })),
+ request: async (machineId, frame: Frame) => {
+ const target = nodes.find((n) => n.machineId === machineId)
+ if (!target?.online) return null
+ const pin = node.peers.get(machineId)
+ if (!pin || pin.pub !== target.pub) return null
+ // What remoteRelay.ts does when the machine answers e2e_denied: the pin goes.
+ if (!target.trusted.has(node.pub)) { node.peers.unlink(machineId); return null }
+ return { type: 'group_sync_result', payload: target.syncer.handle(node.pub, frame.payload as Record<string, unknown>) }
+ },
+ dropSessions: (machineId) => { node.droppedSessions.push(machineId) },
+ now: () => ++clock,
+ })
+ nodes.push(node)
+ return node
+ }
+ /** What a password link does on both ends (manager.ts round 4/5 + cli.ts completeLink). */
+ const link = (joiner: Node, target: Node): void => {
+ target.trusted.set(joiner.pub, { kind: joiner.machineId ? 'machine' : 'viewer', machineId: joiner.machineId ?? undefined })
+ if (joiner.machineId) target.peers.pin(joiner.machineId, joiner.pub, joiner.name)
+ target.syncer.linked({ pub: joiner.pub, kind: joiner.machineId ? 'machine' : 'viewer', label: joiner.name, ...(joiner.machineId ? { machineId: joiner.machineId } : {}) })
+ joiner.peers.pin(target.machineId!, target.pub, target.name)
+ if (joiner.machineId) {
+ joiner.trusted.set(target.pub, { kind: 'machine', machineId: target.machineId! })
+ joiner.syncer.linked({ pub: target.pub, kind: 'machine', label: target.name, machineId: target.machineId! })
+ }
+ }
+ return { add, link, nodes }
+}
+
+describe('GroupSyncer', () => {
+ it('A links B, A links C ⇒ B and C reach each other both ways, no password', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ await a.syncer.syncAll()
+
+ expect(b.peers.get(c.machineId!)?.pub).toBe(c.pub)
+ expect(c.peers.get(b.machineId!)?.pub).toBe(b.pub)
+ expect(b.trusted.has(c.pub)).toBe(true)
+ expect(c.trusted.has(b.pub)).toBe(true)
+ // …and the link made one way already works the other way (B dials A).
+ expect(b.peers.get(a.machineId!)?.pub).toBe(a.pub)
+ expect(a.trusted.has(b.pub)).toBe(true)
+ // B↔C can now exchange directly.
+ await b.syncer.syncWith(c.machineId!)
+ expect(c.syncer.roster().members.map((m) => m.pub)).toEqual(expect.arrayContaining([a.pub, b.pub]))
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a phone linked to one machine is trusted by every member, and gets every machine key', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ const phone = f.add('p', false)
+ f.link(a, b)
+ f.link(a, c)
+ f.link(phone, a)
+ await a.syncer.syncAll()
+ expect(b.trusted.has(phone.pub)).toBe(true)
+ expect(c.trusted.has(phone.pub)).toBe(true)
+ // The phone pulls the roster from A (what the Dart viewer does after linking).
+ const reply = a.syncer.handle(phone.pub, { self: { pub: phone.pub, kind: 'viewer', label: 'p', at: S.SELF_STAMP }, members: [], removed: [] })
+ const machines = (reply.members as Array<{ kind: string; machineId?: string }>).filter((m) => m.kind === 'machine').map((m) => m.machineId)
+ expect(machines).toEqual(expect.arrayContaining([b.machineId, c.machineId]))
+ expect((reply.self as { machineId: string }).machineId).toBe(a.machineId)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a phone can bring a new machine in: D, linked only by the phone, learns and is learned by the group', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b] = [f.add('a'), f.add('b')]
+ const d = f.add('d')
+ const phone = f.add('p', false)
+ f.link(a, b)
+ f.link(phone, a)
+ await a.syncer.syncAll()
+ const roster = a.syncer.handle(phone.pub, { members: [], removed: [] })
+ // Phone links D over D's password, then hands D everything it knows (itself included).
+ f.link(phone, d)
+ const phoneSelf = { pub: phone.pub, kind: 'viewer', label: 'p', at: S.SELF_STAMP }
+ const members = [...(roster.members as unknown[]), roster.self, { pub: d.pub, kind: 'machine', machineId: d.machineId, label: 'd', at: 5_000 }]
+ d.syncer.handle(phone.pub, { self: phoneSelf, members, removed: [] })
+ expect(d.peers.get(a.machineId!)?.pub).toBe(a.pub)
+ expect(d.peers.get(b.machineId!)?.pub).toBe(b.pub)
+ // …and the phone tells A about D, which pushes it on.
+ a.syncer.handle(phone.pub, { self: phoneSelf, members: [{ pub: d.pub, kind: 'machine', machineId: d.machineId, label: 'd', at: 5_000 }], removed: [] })
+ await a.syncer.syncAll()
+ expect(b.trusted.has(d.pub)).toBe(true)
+ expect(b.peers.get(d.machineId!)?.pub).toBe(d.pub)
+ await d.syncer.syncWith(b.machineId!)
+ expect(b.syncer.roster().members.some((m) => m.pub === d.pub)).toBe(true)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('removing a member on one machine removes it on every member it reaches', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ await a.syncer.syncAll()
+ expect(b.syncer.remove(c.pub)).toBe(true)
+ expect(b.peers.get(c.machineId!)).toBeNull()
+ expect(b.droppedSessions).toEqual([c.machineId]) // a pooled session to C must not outlive the pin
+ expect(b.trusted.has(c.pub)).toBe(false)
+ await b.syncer.syncAll()
+ expect(a.peers.get(c.machineId!)).toBeNull()
+ expect(a.trusted.has(c.pub)).toBe(false)
+ expect(a.droppedSessions).toEqual([c.machineId])
+ // C describing itself cannot bring it back (its self entry is older than any removal).
+ await c.syncer.syncWith(a.machineId!) // refused: A no longer trusts C
+ a.syncer.handle(c.pub, { self: { pub: c.pub, kind: 'machine', machineId: c.machineId, label: 'c', at: S.SELF_STAMP }, members: [], removed: [] })
+ expect(a.trusted.has(c.pub)).toBe(false)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a peer may describe only itself: a self entry under another key is ignored', () => {
+ const f = fleet()
+ const [a, b] = [f.add('a'), f.add('b')]
+ const forged = { pub: C.b64e(C.newIdentity().pub), kind: 'machine', machineId: 'f'.repeat(32), label: 'x', at: S.SELF_STAMP }
+ a.syncer.handle(b.pub, { self: forged, members: [], removed: [] })
+ expect(a.syncer.roster().members).toEqual([])
+ })
+
+ it('start() seeds the group from links made before it existed (one-way links become mutual on contact)', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b] = [f.add('a'), f.add('b')]
+ // An old one-way link: A pinned B; B trusts A but knows nothing else about it.
+ a.peers.pin(b.machineId!, b.pub, 'b')
+ b.trusted.set(a.pub, {})
+ a.syncer.start()
+ expect(a.syncer.roster().members.map((m) => m.pub)).toEqual([b.pub])
+ await a.syncer.syncWith(b.machineId!)
+ expect(b.peers.get(a.machineId!)?.pub).toBe(a.pub) // B can now dial A
+ expect(a.trusted.has(b.pub)).toBe(true) // and A lets B in
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a machine that heard of another before being heard of recovers: the refused dial\'s unpin is undone', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ // A tells B about C, but C has not heard of B yet: B's dial to C is refused.
+ await a.syncer.syncWith(b.machineId!)
+ await b.syncer.syncWith(c.machineId!)
+ b.peers.unlink(c.machineId!) // what remoteRelay.ts does on e2e_denied
+ await a.syncer.syncWith(c.machineId!)
+ await b.syncer.syncAll()
+ expect(b.peers.get(c.machineId!)?.pub).toBe(c.pub)
+ expect(c.syncer.roster().members.some((m) => m.pub === b.pub)).toBe(true)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('an unpairing on one machine is not undone by the group, and linking again lifts it', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ await a.syncer.syncAll()
+ // `harness unpair <c>` on B: E2eeManager drops the pairing, then tells the group.
+ b.trusted.delete(c.pub)
+ b.syncer.unpaired(c.pub)
+ expect(b.peers.get(c.machineId!)).toBeNull()
+ await b.syncer.syncAll()
+ await a.syncer.syncAll()
+ await b.syncer.syncWith(a.machineId!)
+ expect(b.trusted.has(c.pub)).toBe(false)
+ expect(b.peers.get(c.machineId!)).toBeNull()
+ // Local only: A and C still trust each other.
+ expect(a.trusted.has(c.pub)).toBe(true)
+ // C links to B again with B's password: trusted again.
+ f.link(c, b)
+ expect(b.trusted.has(c.pub)).toBe(true)
+ await b.syncer.syncAll()
+ expect(b.trusted.has(c.pub)).toBe(true)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('two members that heard of each other at different moments converge on their own, soon', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ // A tells B first. B's own push reaches C before A has told C: refused, and B's pin to C goes.
+ await a.syncer.syncWith(b.machineId!)
+ await b.syncer.syncWith(c.machineId!)
+ expect(b.peers.get(c.machineId!)).toBeNull()
+ // Now A tells C. Nobody links anything or opens a session after this.
+ await a.syncer.syncWith(c.machineId!)
+ await vi.advanceTimersByTimeAsync(20_000)
+ expect(b.peers.get(c.machineId!)?.pub).toBe(c.pub)
+ expect(c.peers.get(b.machineId!)?.pub).toBe(b.pub)
+ expect(b.trusted.has(c.pub) && c.trusted.has(b.pub)).toBe(true)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a member reaching us puts back the pin a refused dial dropped, even when nothing else changed', async () => {
+ const f = fleet()
+ const [a, b, c] = [f.add('a'), f.add('b'), f.add('c')]
+ f.link(a, b)
+ f.link(a, c)
+ await a.syncer.syncWith(b.machineId!)
+ await a.syncer.syncWith(c.machineId!)
+ b.peers.unlink(c.machineId!) // B dialed C a moment too early; remoteRelay dropped the pin
+ expect(await c.syncer.syncWith(b.machineId!)).toBe(true) // C reaches B; B's roster is unchanged
+ expect(b.peers.get(c.machineId!)?.pub).toBe(c.pub)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('a round that missed a member tries again soon, then backs off', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b] = [f.add('a'), f.add('b')]
+ f.link(a, b)
+ await vi.advanceTimersByTimeAsync(0) // the fan-out the link scheduled
+ b.online = false
+ const handle = vi.spyOn(b.syncer, 'handle')
+ await a.syncer.syncAll()
+ b.online = true
+ await vi.advanceTimersByTimeAsync(14_000)
+ expect(handle).not.toHaveBeenCalled()
+ await vi.advanceTimersByTimeAsync(2_000)
+ expect(handle).toHaveBeenCalledTimes(1)
+ // It answered: no more retries.
+ await vi.advanceTimersByTimeAsync(5 * 60_000)
+ expect(handle).toHaveBeenCalledTimes(1)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+
+ it('sessionOpened() does not re-sync a machine it just synced with', async () => {
+ vi.useFakeTimers()
+ const f = fleet()
+ const [a, b] = [f.add('a'), f.add('b')]
+ f.link(a, b)
+ const spy = vi.spyOn(b.syncer, 'handle')
+ await a.syncer.syncWith(b.machineId!)
+ a.syncer.sessionOpened(b.machineId!)
+ await Promise.resolve()
+ expect(spy).toHaveBeenCalledTimes(1)
+ for (const n of f.nodes) n.syncer.stop()
+ })
+})
+
+describe('relayRequester', () => {
+ it('resolves with the matching _result and detaches; null on timeout', async () => {
+ let detached = 0
+ let sink: import('../../backendSocket.js').LocalClientSink | null = null
+ const pool = {
+ acquireIsolated: async (_m: string, _e: string, _sel: Frame, s: import('../../backendSocket.js').LocalClientSink) => {
+ sink = s
+ return {
+ send: async (frame: Frame) => {
+ const rid = (frame.payload as Record<string, unknown>).requestId
+ setTimeout(() => {
+ sink!.sendFrame({ type: 'group_sync_result', payload: { requestId: 'other' } })
+ sink!.sendFrame({ type: 'group_sync_result', payload: { requestId: rid, ok: 1 } })
+ }, 1)
+ },
+ sendBinary: async () => {},
+ detach: () => { detached++ },
+ }
+ },
+ }
+ const request = S.relayRequester(pool, () => 'prod')
+ const reply = await request('m', { type: 'group_sync', payload: { requestId: 'r1' } }, 1_000)
+ expect(reply?.payload).toEqual({ requestId: 'r1', ok: 1 })
+ expect(detached).toBe(1)
+
+ const silent = S.relayRequester({ acquireIsolated: async () => ({ send: async () => {}, sendBinary: async () => {}, detach: () => { detached++ } }) }, () => 'prod')
+ expect(await silent('m', { type: 'group_sync', payload: { requestId: 'r2' } }, 20)).toBeNull()
+ expect(detached).toBe(2)
+ })
+})
diff --git a/cli/src/lib/e2ee/groupSyncer.ts b/cli/src/lib/e2ee/groupSyncer.ts
new file mode 100644
index 000000000..8b0891d5d
--- /dev/null
+++ b/cli/src/lib/e2ee/groupSyncer.ts
@@ -0,0 +1,302 @@
+/**
+ * Keeps this machine's trust group (trustGroup.ts) in step with every other member, and turns what the
+ * roster says into the two trust stores that actually gate a connection:
+ * - machinePeers.json — the key this machine expects when it DIALS a machine member;
+ * - paired.json (through E2eeManager) — the keys allowed to open a session HERE.
+ *
+ * Both halves of the exchange are one sealed RPC, `group_sync`, over the ordinary relay session: the
+ * dialer sends its roster and itself, the dialed machine merges, answers with its own, and the dialer
+ * merges that. Whatever changed is then pushed on to the other members, so a link made anywhere
+ * reaches everyone who is online, and the rest catch up on their next contact.
+ */
+import type { Frame, LocalClientSink } from '../../backendSocket.js'
+import type { RelaySession } from '../remoteRelay.js'
+import type { MachinePeerStore } from './machinePeers.js'
+import type { LinkedPeer } from './manager.js'
+import type { PairedClient } from './store.js'
+import { parseMember, parseRoster, rosterDigest, type GroupMember, type MergeResult, type Roster, type TrustGroupStore } from './trustGroup.js'
+
+export const GROUP_SYNC = 'group_sync'
+/** The stamp a device's description of ITSELF carries: older than anything, so any removal beats it and
+ * a removed device cannot sync its way back in — only a new link (stamped now) can. */
+export const SELF_STAMP = 1
+const SYNC_TIMEOUT_MS = 20_000
+const PERIODIC_MS = 10 * 60_000
+/** A machine synced this recently is not synced again just because a session to it opened. */
+const RECONTACT_MS = 5 * 60_000
+/** After a round where a member could not be reached (or refused, having not heard of this machine yet),
+ * try again this soon — then less often. The periodic round takes over after the last. */
+const RETRY_MS = [15_000, 60_000, 4 * 60_000]
+
+export interface GroupSyncerDeps {
+ store: TrustGroupStore
+ peers: MachinePeerStore
+ /** This machine, as the group should know it (stamped SELF_STAMP). */
+ self: () => GroupMember
+ /** Allow `peer` to open a session here (idempotent). */
+ trust: (peer: LinkedPeer) => void
+ /** Stop allowing `pub` here; drops its live sessions. */
+ untrust: (pub: string) => void
+ /** paired.json, for seeding the roster from links made before the group existed. */
+ paired: () => PairedClient[]
+ /** One sealed request/response with a machine over the relay; null when it could not be reached or
+ * did not answer (an older machine answers nothing for an unknown type). */
+ request: (machineId: string, frame: Frame, timeoutMs: number) => Promise<Frame | null>
+ /** Close every open relay session to a machine the group removed — a lingering one would otherwise
+ * keep working after its pin is gone, since a pooled session is reused without looking again. */
+ dropSessions?: (machineId: string) => void
+ /** Machines worth dialing now; null = unknown, try every member. */
+ reachable?: () => Set<string> | null
+ now?: () => number
+ log?: (line: string) => void
+}
+
+export class GroupSyncer {
+ private readonly now: () => number
+ private readonly lastSynced = new Map<string, number>()
+ private readonly inFlight = new Map<string, Promise<boolean>>()
+ private fanOutTimer: ReturnType<typeof setTimeout> | null = null
+ private periodic: ReturnType<typeof setInterval> | null = null
+ private retryRound = 0
+
+ constructor(private readonly deps: GroupSyncerDeps) {
+ this.now = deps.now ?? (() => Date.now())
+ }
+
+ /** Seed the roster from links that predate it, re-apply it to the trust stores, and start the
+ * periodic catch-up. Safe to call once per daemon. */
+ start(): void {
+ this.seedFromExistingLinks()
+ this.applyAll()
+ this.scheduleFanOut(30_000)
+ this.periodic = setInterval(() => this.scheduleFanOut(0), PERIODIC_MS)
+ this.periodic.unref?.()
+ }
+
+ stop(): void {
+ if (this.periodic) clearInterval(this.periodic)
+ if (this.fanOutTimer) clearTimeout(this.fanOutTimer)
+ this.periodic = null
+ this.fanOutTimer = null
+ }
+
+ roster(): Roster { return this.deps.store.read() }
+
+ /** A device just linked to or from this machine over the remote password: it joins the group, and the
+ * rest of the group hears of it. */
+ linked(peer: LinkedPeer): void {
+ if (!peer.kind) return // an older joiner that did not say what it is — it stays a plain pairing
+ const member = parseMember({ ...peer, at: this.now() }, this.now())
+ if (!member) return
+ this.deps.store.unblock(member.pub) // linking again is the way back after an unpair
+ this.apply(this.deps.store.add(member, this.selfPub()))
+ this.scheduleFanOut(0)
+ }
+
+ /** Remove a member everywhere (`harness group remove`, `harness link unlink`). */
+ remove(pub: string): boolean {
+ const known = this.deps.store.read().members.some((m) => m.pub === pub)
+ const result = this.deps.store.remove(pub, this.selfPub(), this.now())
+ this.apply(result)
+ // Not in the roster (a link that predates it): still stop trusting it here.
+ if (!known) this.forget(pub)
+ this.scheduleFanOut(0)
+ return known || result.dropped.length > 0
+ }
+
+ /** This machine's user unpaired `pub` (`harness unpair`): stop trusting and dialing it HERE, and keep
+ * it that way — without this the next round would put back what the roster still names. */
+ unpaired(pub: string): void {
+ this.deps.store.block(pub)
+ this.forget(pub)
+ }
+
+ /** A session to `machineId` just opened: a good moment to compare rosters, unless we just did. */
+ sessionOpened(machineId: string): void {
+ const last = this.lastSynced.get(machineId) ?? 0
+ if (this.now() - last < RECONTACT_MS) return
+ void this.syncWith(machineId)
+ }
+
+ /** Responder side of `group_sync`, for a sealed request from the session identity `peerPub`. */
+ handle(peerPub: string, payload: Record<string, unknown>): Record<string, unknown> {
+ const now = this.now()
+ const incoming = parseRoster(payload, now)
+ const self = parseMember(payload.self, now)
+ // A peer may describe only itself — its `self` must be the key its session proved.
+ if (self && self.pub === peerPub) incoming.members.push(self)
+ const before = rosterDigest(this.deps.store.read())
+ const result = this.deps.store.merge(incoming, this.selfPub())
+ this.apply(result)
+ // A member that reached us is one we can reach: put back a pin the relay dropped when this machine
+ // dialed it before it had heard of us (remoteRelay.ts unlinks a peer that answers e2e_denied).
+ this.applyAll()
+ if (rosterDigest(result.roster) !== before) this.scheduleFanOut(1_000)
+ return { self: this.deps.self(), ...result.roster, digest: rosterDigest(result.roster) }
+ }
+
+ /** Initiator side: exchange rosters with one machine; true when it answered. Never throws. */
+ syncWith(machineId: string): Promise<boolean> {
+ const running = this.inFlight.get(machineId)
+ if (running) return running
+ const task = this.exchange(machineId).catch(() => false).finally(() => this.inFlight.delete(machineId))
+ this.inFlight.set(machineId, task)
+ return task
+ }
+
+ /** Every reachable machine member (and every machine pinned outside the roster), one at a time. */
+ async syncAll(): Promise<void> {
+ // Put back any pin the relay dropped. A member can hear of another before that one hears of it,
+ // and its first dial is then refused — remoteRelay.ts unlinks a peer that answers e2e_denied. The
+ // roster still says they belong together, so they are re-pinned and tried again on this round.
+ this.applyAll()
+ const reachable = this.deps.reachable?.() ?? null
+ const self = this.deps.self().machineId
+ const targets = new Set<string>()
+ for (const m of this.deps.store.read().members) if (m.kind === 'machine' && m.machineId) targets.add(m.machineId)
+ for (const p of this.deps.peers.list()) targets.add(p.machineId)
+ if (self) targets.delete(self)
+ // All at once: one machine that never answers (offline, or too old to know the frame) must not
+ // hold up the rest for its whole timeout.
+ const due = [...targets].filter((machineId) => !reachable || reachable.has(machineId))
+ const answered = await Promise.all(due.map((machineId) => this.syncWith(machineId)))
+ const members = new Set(this.deps.store.read().members.map((m) => m.machineId))
+ const missed = due.some((machineId, i) => !answered[i] && members.has(machineId))
+ if (!missed) { this.retryRound = 0; return }
+ const delay = RETRY_MS[this.retryRound]
+ if (delay === undefined) return // the periodic round takes over
+ this.retryRound++
+ this.scheduleFanOut(delay, true)
+ }
+
+ private async exchange(machineId: string): Promise<boolean> {
+ const pin = this.deps.peers.get(machineId)
+ if (!pin) return false
+ const local = this.deps.store.read()
+ const reply = await this.deps.request(machineId, {
+ type: GROUP_SYNC,
+ payload: { requestId: `gs-${this.now()}-${Math.random().toString(36).slice(2, 8)}`, self: this.deps.self(), ...local, digest: rosterDigest(local) },
+ }, SYNC_TIMEOUT_MS).catch(() => null)
+ if (!reply) return false
+ this.lastSynced.set(machineId, this.now())
+ const payload = (reply.payload ?? {}) as Record<string, unknown>
+ if (typeof payload.error === 'string') return false
+ const now = this.now()
+ const incoming = parseRoster(payload, now)
+ const theirSelf = parseMember(payload.self, now)
+ // The answering machine may describe only itself, as the key this machine dialed and verified.
+ if (theirSelf && theirSelf.pub === pin.pub && theirSelf.machineId === machineId) incoming.members.push(theirSelf)
+ // Compared with the roster as it is now, not the one sent: a link can land while this was in flight.
+ const before = rosterDigest(this.deps.store.read())
+ const result = this.deps.store.merge(incoming, this.selfPub())
+ this.apply(result)
+ if (rosterDigest(result.roster) !== before) {
+ this.deps.log?.(`[group] ${machineId.slice(0, 8)}: +${result.upserted.length} −${result.dropped.length}`)
+ this.scheduleFanOut(1_000)
+ }
+ return true
+ }
+
+ /** `retry`: a follow-up to a round that missed someone. Anything else is news, which starts the
+ * retry schedule over. */
+ private scheduleFanOut(delayMs: number, retry = false): void {
+ if (!retry) this.retryRound = 0
+ if (this.fanOutTimer) return
+ this.fanOutTimer = setTimeout(() => {
+ this.fanOutTimer = null
+ // What changed reaches every member, not just the recently-contacted ones.
+ this.lastSynced.clear()
+ void this.syncAll().catch(() => { /* next round */ })
+ }, delayMs)
+ this.fanOutTimer.unref?.()
+ }
+
+ private selfPub(): string { return this.deps.self().pub }
+
+ /** Links made before the group existed: every pinned machine and every paired peer that said what it is. */
+ private seedFromExistingLinks(): void {
+ const seed: GroupMember[] = []
+ for (const p of this.deps.peers.list()) {
+ const m = parseMember({ pub: p.pub, machineId: p.machineId, kind: 'machine', label: p.label, at: p.linkedAt || SELF_STAMP }, this.now())
+ if (m) seed.push(m)
+ }
+ for (const p of this.deps.paired()) {
+ if (!p.kind) continue
+ const m = parseMember({ pub: p.identityPub, machineId: p.machineId, kind: p.kind, label: p.label, at: p.pairedAt || SELF_STAMP }, this.now())
+ if (m) seed.push(m)
+ }
+ if (seed.length) this.deps.store.merge({ members: seed, removed: [] }, this.selfPub())
+ }
+
+ private applyAll(): void {
+ const roster = this.deps.store.read()
+ this.apply({ roster, upserted: roster.members, dropped: [] })
+ }
+
+ private apply(result: MergeResult): void {
+ const selfMachine = this.deps.self().machineId
+ const blocked = this.deps.store.blocked()
+ for (const m of result.upserted) {
+ if (blocked.has(m.pub)) continue
+ try {
+ if (m.kind === 'machine' && m.machineId && m.machineId !== selfMachine) {
+ const pin = this.deps.peers.get(m.machineId)
+ if (!pin || pin.pub !== m.pub) this.deps.peers.pin(m.machineId, m.pub, m.label, m.at)
+ }
+ this.deps.trust({ pub: m.pub, machineId: m.machineId, kind: m.kind, label: m.label })
+ } catch (err) {
+ this.deps.log?.(`[group] could not apply ${m.pub.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`)
+ }
+ }
+ for (const m of result.dropped) this.forget(m.pub)
+ }
+
+ private forget(pub: string): void {
+ try {
+ for (const p of this.deps.peers.list()) {
+ if (p.pub !== pub) continue
+ this.deps.peers.unlink(p.machineId)
+ this.deps.dropSessions?.(p.machineId)
+ }
+ this.deps.untrust(pub)
+ } catch (err) {
+ this.deps.log?.(`[group] could not remove ${pub.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`)
+ }
+ }
+}
+
+/** `GroupSyncerDeps.request` over a background relay session (its own pool — it never takes the
+ * window's sink): select the machine, send one sealed frame, wait for its `_result`, detach. */
+export function relayRequester(
+ pool: { acquireIsolated: (machineId: string, autonomousEnv: string, selectFrame: Frame, sink: LocalClientSink, onClosed: (code: number, reason: string) => void) => Promise<RelaySession> },
+ autonomousEnv: () => string,
+): GroupSyncerDeps['request'] {
+ return (machineId, frame, timeoutMs) => new Promise<Frame | null>((resolve) => {
+ const requestId = (frame.payload as Record<string, unknown> | undefined)?.requestId
+ let session: RelaySession | null = null
+ let done = false
+ const finish = (result: Frame | null): void => {
+ if (done) return
+ done = true
+ clearTimeout(timer)
+ session?.detach()
+ resolve(result)
+ }
+ const timer = setTimeout(() => finish(null), timeoutMs)
+ const sink: LocalClientSink = {
+ sendFrame: (f) => {
+ const p = (f.payload ?? {}) as Record<string, unknown>
+ if (f.type === `${frame.type}_result` && p.requestId === requestId) finish(f)
+ return true
+ },
+ sendBinary: () => true,
+ }
+ pool.acquireIsolated(machineId, autonomousEnv(), { type: 'machine_select', payload: { machineId } }, sink, () => finish(null))
+ .then((s) => {
+ session = s
+ if (done) { s.detach(); return }
+ return s.send(frame)
+ })
+ .catch(() => finish(null))
+ })
+}
diff --git a/cli/src/lib/e2ee/manager.ts b/cli/src/lib/e2ee/manager.ts
index 8f635c1d1..03fc21ace 100644
--- a/cli/src/lib/e2ee/manager.ts
+++ b/cli/src/lib/e2ee/manager.ts
@@ -23,7 +23,7 @@ import {
sealTerminalBinary,
type TerminalBinaryClear,
} from '../terminalBinary.js'
-import { E2eeStore } from './store.js'
+import { E2eeStore, type PeerKind } from './store.js'
import { pwCpaceGenerator, pwContext } from './passwordPake.js'
import { ReplayWindow } from './replayWindow.js'
@@ -114,6 +114,30 @@ export interface E2eeManagerDeps {
onIdentityRevoked?: (identityPub: string) => void
/** Release connection-scoped resources on revoke, eviction, replacement and disconnect. */
onSessionDropped?: (connId: string) => void
+ /** A peer just proved this machine's remote password (it is already trusted here as a client). A
+ * machine joiner carries its machineId so the caller can pin it back and sync the trust group. */
+ onPeerLinked?: (peer: LinkedPeer) => void
+ /** A person unpaired `identityPub` (`harness unpair`, or a trusted client's unpair RPC) — not called
+ * for the trust group's own removals, so the group can keep an unpairing from being undone. */
+ onUnpaired?: (identityPub: string) => void
+}
+
+export interface LinkedPeer {
+ pub: string // base64 Ed25519 identity
+ machineId?: string // set when kind is 'machine'
+ kind?: PeerKind // absent for an older joiner that did not say
+ label: string
+}
+
+const MACHINE_ID_RE = /^[a-f0-9]{32}$/
+
+/** The optional fields a newer joiner seals into round 4. Anything malformed is dropped rather than
+ * failing the link — an older joiner sends none of them and still links one-way, as it always did. */
+function parseJoiner(p: { machineId?: unknown; kind?: unknown; label?: unknown }): Omit<LinkedPeer, 'pub'> {
+ const kind = p.kind === 'machine' || p.kind === 'viewer' ? p.kind : undefined
+ const machineId = kind === 'machine' && typeof p.machineId === 'string' && MACHINE_ID_RE.test(p.machineId) ? p.machineId : undefined
+ const label = pairedLabel(p.label) ?? 'harness link'
+ return { kind: kind === 'machine' && !machineId ? undefined : kind, machineId, label }
}
export class E2eeManager {
@@ -153,6 +177,21 @@ export class E2eeManager {
setAt: this.store.remotePasswordSetAt(),
}
}
+ /** Trust `pub` as a client of this machine (idempotent; keeps the original pairedAt). Used for the
+ * mutual half of a password link — the machine whose password the joiner proved is trusted back — and
+ * for members learned from a trust-group sync. */
+ trustPeer(peer: LinkedPeer, at = this.now()): void {
+ const existing = this.store.pairedPeer(peer.pub)
+ if (existing && existing.label === peer.label && existing.machineId === peer.machineId && existing.kind === peer.kind) return
+ this.store.addPaired(peer.pub, peer.label, existing?.pairedAt ?? at, existing?.role ?? 'web', { machineId: peer.machineId, kind: peer.kind })
+ }
+ /** Stop trusting `pub` (a no-op when it is not paired): the same path as `harness unpair`. */
+ untrustPeer(pub: string): boolean {
+ if (!this.store.isPaired(pub)) return false
+ this.revokeIdentity(pub)
+ return true
+ }
+ pairedPeers(): ReturnType<E2eeStore['list']> { return this.store.list() }
hasSession(connId: string): boolean { return this.sessions.has(connId) }
sessionIdentity(connId: string): string | null { return this.sessions.get(connId)?.webIdentityPub ?? null }
sessionRole(connId: string): C.PairRole | null { return this.sessions.get(connId)?.role ?? null }
@@ -221,6 +260,7 @@ export class E2eeManager {
const found = this.findPaired(selector)
if (!found.ok) return found
this.revokeIdentity(found.identityPub)
+ this.noteUnpaired(found.identityPub)
return { ok: true, label: found.label, fingerprint: found.fingerprint }
}
@@ -232,6 +272,7 @@ export class E2eeManager {
const reply = this.wrapRpcReply(connId, 'e2ee_pairing_unpair_result', requestId, { ok: true, label: payload.label, fingerprint: payload.fingerprint })
if (reply) this.deps.sendTo(connId, reply)
this.revokeIdentity(payload.identityPub)
+ this.noteUnpaired(payload.identityPub)
return
}
const reply = this.wrapRpcReply(connId, 'e2ee_pairing_unpair_result', requestId, { error: payload.error })
@@ -241,14 +282,20 @@ export class E2eeManager {
/** Revoke every paired browser. Signals all online sessions to re-pair + rotates the group key. */
revokeAll(): { count: number } {
const count = this.store.count()
+ const unpaired = this.store.list().map((p) => p.identityPub)
// Device cleanup first: it needs the live session to seal a pair.revoke frame before deny drops it.
for (const paired of this.store.list()) { try { this.deps.onIdentityRevoked?.(paired.identityPub) } catch { /* Continue revoking every stored identity. */ } }
for (const s of [...this.sessions.entries()]) { this.deny(s[0]); this.dropSession(s[0]) }
this.store.clear()
this.rotateGroupKey()
+ for (const pub of unpaired) this.noteUnpaired(pub)
return { count }
}
+ private noteUnpaired(identityPub: string): void {
+ try { this.deps.onUnpaired?.(identityPub) } catch { /* the unpairing itself stands */ }
+ }
+
revokeAllFromTrustedWeb(connId: string, requestId: unknown): void {
const count = this.store.count()
const reply = this.wrapRpcReply(connId, 'e2ee_pairings_unpair_all_result', requestId, { count })
@@ -631,7 +678,7 @@ export class E2eeManager {
if (!slot.isk || !slot.th) { this.failPwPair(connId, 'TIMEOUT'); return true }
const opened = C.aeadOpen(C.pairKey(slot.isk, ci), 4, C.utf8('e2e-id'), C.b64d(String(p.enc)))
if (!opened) { this.failPwPair(connId, 'WRONG_PASSWORD', true); return true }
- const joinerId = JSON.parse(new TextDecoder().decode(opened)) as { id: string; sig: string; label?: unknown }
+ const joinerId = JSON.parse(new TextDecoder().decode(opened)) as { id: string; sig: string; machineId?: unknown; kind?: unknown; label?: unknown }
if (!C.pairBindVerify(C.b64d(joinerId.id), slot.th, C.b64d(joinerId.sig))) { this.failPwPair(connId, 'WRONG_PASSWORD', true); return true }
// Full success: trust the joiner exactly as if it were a paired browser session (same call/role
// onSetupClaim uses) — this is what lets it relay through this machine's data plane.
@@ -639,10 +686,14 @@ export class E2eeManager {
// Named by the joiner when it says who it is ("Dee's iPhone"), inside the sealed identity, so the
// name is as authenticated as the key — and so the Mac's list of paired devices reads as devices.
// A joiner that predates the field (`harness link connect`, an older phone) stays "harness link".
- this.store.addPaired(joinerId.id, pairedLabel(joinerId.label) ?? 'harness link', this.now(), 'web')
+ // A newer joiner also says what it is: a machine gets pinned back (mutual link — it can be dialed
+ // from here without its own password).
+ const joiner = parseJoiner(joinerId)
+ this.store.addPaired(joinerId.id, joiner.label, this.now(), 'web', { machineId: joiner.machineId, kind: joiner.kind })
this.store.notePwSuccess()
+ try { this.deps.onPeerLinked?.({ pub: joinerId.id, ...joiner }) } catch { /* the link itself stands */ }
const fp = this.fingerprint()
- this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: slot.sidB64, round: 5, ok: true, fingerprint: fp } })
+ this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: slot.sidB64, round: 5, ok: true, fingerprint: fp, mutual: 1 } })
this.clearPwSlot(connId)
return true
}
diff --git a/cli/src/lib/e2ee/relayClient.ts b/cli/src/lib/e2ee/relayClient.ts
index 8701e9b69..cebbf1ba4 100644
--- a/cli/src/lib/e2ee/relayClient.ts
+++ b/cli/src/lib/e2ee/relayClient.ts
@@ -164,7 +164,8 @@ export class RelaySessionCrypto {
}
export type PwConnectResult =
- | { ok: true; peerPub: Uint8Array; fingerprint: string }
+ /** `mutual`: the target said it pinned this joiner back (a machine joiner can then be dialed from it). */
+ | { ok: true; peerPub: Uint8Array; fingerprint: string; mutual: boolean }
| { ok: false; error: string; retryAt?: number }
export type PwConnectProgress = 'connecting' | 'deriving_key' | 'exchanging' | 'verifying'
@@ -186,6 +187,9 @@ export async function connectWithPassword(opts: {
autonomousEnv: string
onProgress?: (stage: PwConnectProgress) => void
timeoutMs?: number
+ /** Who this joiner is, sealed into round 4 next to its identity. A machine that names its own
+ * machineId gets pinned back by a target that understands it, so the link works both ways. */
+ self?: { machineId?: string; kind: 'machine' | 'viewer'; label?: string }
}): Promise<PwConnectResult> {
const url = `${opts.backendWsBase}/api/web-ws?autonomousEnv=${encodeURIComponent(opts.autonomousEnv)}`
const ws = new WebSocket(url, [opts.accessToken])
@@ -273,13 +277,14 @@ export async function connectWithPassword(opts: {
const targetPub = C.b64d(targetId.id)
if (!C.pairBindVerify(targetPub, th, C.b64d(targetId.sig))) { finish({ ok: false, error: 'WRONG_PASSWORD' }); return }
peerPub = targetPub
- const sealed = C.aeadSeal(C.pairKey(isk, ci), 4, C.utf8('e2e-id'), C.utf8(JSON.stringify({ id: C.b64e(opts.selfIdentity.pub), sig: C.b64e(C.pairBindSig(opts.selfIdentity.priv, th)) })))
+ const joiner = { id: C.b64e(opts.selfIdentity.pub), sig: C.b64e(C.pairBindSig(opts.selfIdentity.priv, th)), ...(opts.self ?? {}) }
+ const sealed = C.aeadSeal(C.pairKey(isk, ci), 4, C.utf8('e2e-id'), C.utf8(JSON.stringify(joiner)))
ws.send(JSON.stringify({ type: 'e2e_pw_pake', payload: { sid: sidB64, round: 4, enc: C.b64e(sealed) } }))
return
}
if (round === 5) {
if (payload.ok === true && peerPub) {
- finish({ ok: true, peerPub, fingerprint: typeof payload.fingerprint === 'string' ? payload.fingerprint : C.fingerprint(peerPub) })
+ finish({ ok: true, peerPub, fingerprint: typeof payload.fingerprint === 'string' ? payload.fingerprint : C.fingerprint(peerPub), mutual: payload.mutual === 1 })
} else {
const retryAt = typeof payload.retryAt === 'number' ? payload.retryAt : undefined
finish({ ok: false, error: typeof payload.error === 'string' ? payload.error : 'PAIR_FAILED', ...(retryAt !== undefined ? { retryAt } : {}) })
diff --git a/cli/src/lib/e2ee/relayLink.spec.ts b/cli/src/lib/e2ee/relayLink.spec.ts
index 6e1ad2b5e..0f0ee4da7 100644
--- a/cli/src/lib/e2ee/relayLink.spec.ts
+++ b/cli/src/lib/e2ee/relayLink.spec.ts
@@ -231,12 +231,13 @@ describe('remote-password link + relay session crypto (interop with the real E2e
/** Spin up the same fake `/api/web-ws` (machine_select -> connected, then e2e_* frame relay) used
* above, wired to a fresh real E2eeManager, and return both plus a cleanup function. */
- function fakeMachine(): { manager: InstanceType<typeof E2eeManagerCtor>; wsBase: Promise<string>; close: () => Promise<void> } {
+ function fakeMachine(onPeerLinked?: (peer: import('./manager.js').LinkedPeer) => void): { manager: InstanceType<typeof E2eeManagerCtor>; wsBase: Promise<string>; close: () => Promise<void> } {
const wss = new WebSocketServer({ port: 0 })
const manager = new E2eeManagerCtor({
machineId: MACHINE_ID,
sendTo: (_connId, frame) => { for (const client of wss.clients) client.send(JSON.stringify(frame)) },
isConnected: () => true,
+ onPeerLinked,
})
wss.on('connection', (ws) => {
let selected = false
@@ -260,6 +261,96 @@ describe('remote-password link + relay session crypto (interop with the real E2e
return { manager, wsBase, close: () => new Promise<void>((resolve) => wss.close(() => resolve())) }
}
+ it('a machine joiner that says who it is is trusted with its machineId and reported for pin-back (mutual link)', async () => {
+ const JOINER_ID = 'a1b2c3d4e5f60718293a4b5c6d7e8f90'
+ const linked: Array<import('./manager.js').LinkedPeer> = []
+ const { manager, wsBase, close } = fakeMachine((peer) => linked.push(peer))
+ try {
+ await manager.setRemotePassword(REMOTE_PASSWORD)
+ const joiner = C.newIdentity()
+ const result = await connectWithPassword({
+ targetMachineId: MACHINE_ID,
+ password: REMOTE_PASSWORD,
+ selfIdentity: joiner,
+ accessToken: 'unused',
+ backendWsBase: await wsBase,
+ autonomousEnv: 'prod',
+ timeoutMs: 5_000,
+ self: { kind: 'machine', machineId: JOINER_ID, label: 'studio-mac' },
+ })
+ expect(result.ok).toBe(true)
+ if (!result.ok) return
+ expect(result.mutual).toBe(true)
+ expect(linked).toEqual([{ pub: C.b64e(joiner.pub), machineId: JOINER_ID, kind: 'machine', label: 'studio-mac' }])
+ const paired = manager.pairedPeers().find((p) => p.identityPub === C.b64e(joiner.pub))
+ expect(paired).toMatchObject({ machineId: JOINER_ID, kind: 'machine', label: 'studio-mac', role: 'web' })
+ } finally {
+ await close()
+ }
+ }, PW_SCRYPT_TEST_TIMEOUT_MS)
+
+ it('an older joiner (no self description) still links one-way under the default label', async () => {
+ const linked: Array<import('./manager.js').LinkedPeer> = []
+ const { manager, wsBase, close } = fakeMachine((peer) => linked.push(peer))
+ try {
+ await manager.setRemotePassword(REMOTE_PASSWORD)
+ const joiner = C.newIdentity()
+ const result = await connectWithPassword({
+ targetMachineId: MACHINE_ID,
+ password: REMOTE_PASSWORD,
+ selfIdentity: joiner,
+ accessToken: 'unused',
+ backendWsBase: await wsBase,
+ autonomousEnv: 'prod',
+ timeoutMs: 5_000,
+ })
+ expect(result.ok).toBe(true)
+ expect(linked).toEqual([{ pub: C.b64e(joiner.pub), kind: undefined, machineId: undefined, label: 'harness link' }])
+ const paired = manager.pairedPeers().find((p) => p.identityPub === C.b64e(joiner.pub))
+ expect(paired?.machineId).toBeUndefined()
+ expect(paired?.kind).toBeUndefined()
+ } finally {
+ await close()
+ }
+ }, PW_SCRYPT_TEST_TIMEOUT_MS)
+
+ it('a machine joiner with a malformed machineId is not taken for a machine', async () => {
+ const linked: Array<import('./manager.js').LinkedPeer> = []
+ const { manager, wsBase, close } = fakeMachine((peer) => linked.push(peer))
+ try {
+ await manager.setRemotePassword(REMOTE_PASSWORD)
+ const result = await connectWithPassword({
+ targetMachineId: MACHINE_ID,
+ password: REMOTE_PASSWORD,
+ selfIdentity: C.newIdentity(),
+ accessToken: 'unused',
+ backendWsBase: await wsBase,
+ autonomousEnv: 'prod',
+ timeoutMs: 5_000,
+ self: { kind: 'machine', machineId: '../../etc/passwd' },
+ })
+ expect(result.ok).toBe(true)
+ expect(linked[0].kind).toBeUndefined()
+ expect(linked[0].machineId).toBeUndefined()
+ } finally {
+ await close()
+ }
+ }, PW_SCRYPT_TEST_TIMEOUT_MS)
+
+ it('trustPeer makes a linked machine able to open a session here (the mutual half)', async () => {
+ const other = C.newIdentity()
+ const hello = async (): Promise<Frame> => new RelaySessionCrypto({ machineId: MACHINE_ID, selfIdentity: other, peerPub: C.newIdentity().pub }).helloFrame()
+ const frames: Frame[] = []
+ const manager = new E2eeManagerCtor({ machineId: MACHINE_ID, sendTo: (_c, f) => frames.push(f), isConnected: () => true })
+ manager.handleFrame('c1', await hello())
+ expect(frames.at(-1)?.type).toBe('e2e_denied')
+ manager.trustPeer({ pub: C.b64e(other.pub), machineId: 'a1b2c3d4e5f60718293a4b5c6d7e8f90', kind: 'machine', label: 'b' })
+ manager.handleFrame('c2', await hello())
+ expect(frames.at(-1)?.type).toBe('e2e_welcome')
+ expect(manager.untrustPeer(C.b64e(other.pub))).toBe(true)
+ expect(manager.untrustPeer(C.b64e(other.pub))).toBe(false)
+ })
+
it('NO_REMOTE_PASSWORD when the target machine never set one', async () => {
const { manager, wsBase, close } = fakeMachine()
try {
diff --git a/cli/src/lib/e2ee/store.ts b/cli/src/lib/e2ee/store.ts
index 36ab06052..946bafa6d 100644
--- a/cli/src/lib/e2ee/store.ts
+++ b/cli/src/lib/e2ee/store.ts
@@ -38,7 +38,15 @@ export interface PairedClient {
label: string // UA-derived, for display
pairedAt: number
role: PairRole // old records without this field are treated as web
+ /** Set for a peer that joined over the remote password (or was learned from a trust-group sync): the
+ * joining machine's id when `kind` is 'machine', absent for a viewer app. Absent on older records. */
+ machineId?: string
+ kind?: PeerKind
}
+
+/** What a password-linked peer is: another harness machine (which also serves, so it can be dialed back)
+ * or a viewer app (mobile / viewer desktop — dial-out only). */
+export type PeerKind = 'machine' | 'viewer'
function writeSecure(file: string, data: unknown): void {
mkdirSync(DIR, { recursive: true, mode: 0o700 })
writeFileSync(file, JSON.stringify(data, null, 2), { mode: 0o600 })
@@ -104,8 +112,16 @@ export class E2eeStore {
return this.paired.get(identityPubB64)?.label ?? null
}
- addPaired(identityPubB64: string, label: string, at: number, role: PairRole = 'web'): void {
- this.paired.set(identityPubB64, { identityPub: identityPubB64, label, pairedAt: at, role })
+ pairedPeer(identityPubB64: string): PairedClient | null {
+ return this.paired.get(identityPubB64) ?? null
+ }
+
+ addPaired(identityPubB64: string, label: string, at: number, role: PairRole = 'web', peer?: { machineId?: string; kind?: PeerKind }): void {
+ this.paired.set(identityPubB64, {
+ identityPub: identityPubB64, label, pairedAt: at, role,
+ ...(peer?.machineId ? { machineId: peer.machineId } : {}),
+ ...(peer?.kind ? { kind: peer.kind } : {}),
+ })
writeSecure(PAIRED_FILE, [...this.paired.values()])
}
diff --git a/cli/src/lib/e2ee/trustGroup.spec.ts b/cli/src/lib/e2ee/trustGroup.spec.ts
new file mode 100644
index 000000000..37c5876f1
--- /dev/null
+++ b/cli/src/lib/e2ee/trustGroup.spec.ts
@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest'
+import { mkdtempSync, rmSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// ADAPTER_DATA_DIR must be set before config/env.js loads (see manager.test.ts).
+let C: typeof import('./core.js')
+let G: typeof import('./trustGroup.js')
+
+beforeAll(async () => {
+ process.env.ADAPTER_DATA_DIR = mkdtempSync(join(tmpdir(), 'e2ee-group-'))
+ C = await import('./core.js')
+ G = await import('./trustGroup.js')
+})
+
+beforeEach(() => {
+ try { rmSync(join(process.env.ADAPTER_DATA_DIR as string, 'e2e'), { recursive: true, force: true }) } catch { /* none */ }
+})
+
+const pub = (): string => C.b64e(C.newIdentity().pub)
+const MID_B = 'b'.repeat(32)
+const MID_C = 'c'.repeat(32)
+const empty = (): import('./trustGroup.js').Roster => ({ members: [], removed: [] })
+
+describe('parseMember / parseRoster', () => {
+ it('keeps a well-formed machine and viewer, drops malformed ones', () => {
+ const now = 1_000_000
+ const good = { pub: pub(), machineId: MID_B, kind: 'machine', label: 'b', at: 10 }
+ const viewer = { pub: pub(), kind: 'viewer', label: "Dee's iPhone", at: 11, machineId: MID_C }
+ const roster = G.parseRoster({
+ members: [
+ good,
+ viewer,
+ { ...good, pub: 'not-a-key' },
+ { ...good, machineId: '../etc' }, // a machine without a valid id is refused
+ { ...good, kind: 'server' },
+ { ...good, at: now + 25 * 60 * 60 * 1000 }, // stamped too far ahead
+ { ...good, at: -1 },
+ 'junk',
+ ],
+ removed: [{ pub: good.pub, at: 5 }, { pub: 'x', at: 1 }],
+ }, now)
+ expect(roster.members).toEqual([good, { pub: viewer.pub, kind: 'viewer', label: "Dee's iPhone", at: 11 }])
+ expect(roster.removed).toEqual([{ pub: good.pub, at: 5 }])
+ })
+
+ it('cleans a label and falls back to the machine id', () => {
+ const p = pub()
+ expect(G.parseMember({ pub: p, machineId: MID_B, kind: 'machine', label: ' a\u0000b\n ', at: 1 })?.label).toBe('a b')
+ expect(G.parseMember({ pub: p, machineId: MID_B, kind: 'machine', at: 1 })?.label).toBe(MID_B)
+ })
+
+ it('caps the lists', () => {
+ const members = Array.from({ length: G.MAX_MEMBERS + 10 }, (_, i) => ({ pub: pub(), kind: 'viewer', label: 'v', at: i + 1 }))
+ expect(G.parseRoster({ members }).members).toHaveLength(G.MAX_MEMBERS)
+ })
+})
+
+describe('mergeRoster', () => {
+ it('takes new members, reporting them as upserted', () => {
+ const self = pub()
+ const b = { pub: pub(), machineId: MID_B, kind: 'machine' as const, label: 'b', at: 10 }
+ const r = G.mergeRoster(empty(), { members: [b], removed: [] }, self)
+ expect(r.roster.members).toEqual([b])
+ expect(r.upserted).toEqual([b])
+ expect(r.dropped).toEqual([])
+ })
+
+ it('never takes itself in, and ignores a tombstone for itself', () => {
+ const self = pub()
+ const r = G.mergeRoster(empty(), { members: [{ pub: self, kind: 'viewer', label: 'me', at: 5 }], removed: [{ pub: self, at: 9 }] }, self)
+ expect(r.roster).toEqual(empty())
+ })
+
+ it('the newer entry for a key wins; an equal or older one changes nothing', () => {
+ const self = pub()
+ const k = pub()
+ const old = { pub: k, machineId: MID_B, kind: 'machine' as const, label: 'old', at: 10 }
+ const renamed = { ...old, label: 'new', at: 20 }
+ const r1 = G.mergeRoster({ members: [old], removed: [] }, { members: [renamed], removed: [] }, self)
+ expect(r1.roster.members).toEqual([renamed])
+ expect(r1.upserted).toEqual([renamed])
+ const r2 = G.mergeRoster({ members: [renamed], removed: [] }, { members: [old], removed: [] }, self)
+ expect(r2.roster.members).toEqual([renamed])
+ expect(r2.upserted).toEqual([])
+ })
+
+ it('a tombstone beats every entry it is not older than, and reports what it dropped', () => {
+ const self = pub()
+ const b = { pub: pub(), machineId: MID_B, kind: 'machine' as const, label: 'b', at: 10 }
+ const r = G.mergeRoster({ members: [b], removed: [] }, { members: [], removed: [{ pub: b.pub, at: 10 }] }, self)
+ expect(r.roster.members).toEqual([])
+ expect(r.roster.removed).toEqual([{ pub: b.pub, at: 10 }])
+ expect(r.dropped).toEqual([b])
+ // …and an incoming stale copy of the removed member stays out.
+ const again = G.mergeRoster(r.roster, { members: [b], removed: [] }, self)
+ expect(again.roster.members).toEqual([])
+ expect(again.upserted).toEqual([])
+ })
+
+ it('linking again stamps a newer entry, which beats the tombstone', () => {
+ const self = pub()
+ const k = pub()
+ const removed = { members: [], removed: [{ pub: k, at: 10 }] }
+ const relinked = { pub: k, machineId: MID_B, kind: 'machine' as const, label: 'b', at: 11 }
+ const r = G.mergeRoster(removed, { members: [relinked], removed: [] }, self)
+ expect(r.roster.members).toEqual([relinked])
+ expect(r.upserted).toEqual([relinked])
+ })
+
+ it('two separate groups become one', () => {
+ const self = pub()
+ const a = { pub: pub(), machineId: 'a'.repeat(32), kind: 'machine' as const, label: 'a', at: 1 }
+ const b = { pub: pub(), machineId: MID_B, kind: 'machine' as const, label: 'b', at: 2 }
+ const c = { pub: pub(), machineId: MID_C, kind: 'machine' as const, label: 'c', at: 3 }
+ const phone = { pub: pub(), kind: 'viewer' as const, label: 'phone', at: 4 }
+ const r = G.mergeRoster({ members: [a, b], removed: [] }, { members: [c, phone], removed: [] }, self)
+ expect(new Set(r.roster.members.map((m) => m.pub))).toEqual(new Set([a.pub, b.pub, c.pub, phone.pub]))
+ })
+
+ it('the digest ignores order and tracks content', () => {
+ const a = { pub: pub(), kind: 'viewer' as const, label: 'a', at: 1 }
+ const b = { pub: pub(), kind: 'viewer' as const, label: 'b', at: 2 }
+ expect(G.rosterDigest({ members: [a, b], removed: [] })).toBe(G.rosterDigest({ members: [b, a], removed: [] }))
+ expect(G.rosterDigest({ members: [a], removed: [] })).not.toBe(G.rosterDigest({ members: [a, b], removed: [] }))
+ })
+})
+
+describe('TrustGroupStore', () => {
+ it('persists 0600, uncached, and remove() stamps past the current entry', () => {
+ const self = pub()
+ const store = new G.TrustGroupStore()
+ const b = { pub: pub(), machineId: MID_B, kind: 'machine' as const, label: 'b', at: 5_000 }
+ store.add(b, self)
+ expect(new G.TrustGroupStore().read().members).toEqual([b])
+ const file = join(process.env.ADAPTER_DATA_DIR as string, 'e2e', 'group.json')
+ expect(statSync(file).mode & 0o777).toBe(0o600)
+ // A clock behind the entry's stamp must still remove it.
+ const r = store.remove(b.pub, self, 1_000)
+ expect(r.dropped).toEqual([b])
+ expect(store.read().removed).toEqual([{ pub: b.pub, at: 5_001 }])
+ expect(store.list()).toEqual([])
+ })
+})
+
+describe('group_sync on the wire', () => {
+ it('is always sealed, both ways — the roster carries keys', async () => {
+ const F = await import('./applicationFrames.js')
+ expect(F.encryptDownFrame('group_sync')).toBe(true)
+ expect(F.encryptRpcResult('group_sync_result')).toBe(true)
+ })
+})
diff --git a/cli/src/lib/e2ee/trustGroup.ts b/cli/src/lib/e2ee/trustGroup.ts
new file mode 100644
index 000000000..41605a41f
--- /dev/null
+++ b/cli/src/lib/e2ee/trustGroup.ts
@@ -0,0 +1,216 @@
+/**
+ * The trust group: every machine and viewer app of one account that has linked, directly or through
+ * another member, so each can reach every other without typing a remote password again.
+ *
+ * Deliberately simple, by product decision (UX over strictness): any two devices that already share an
+ * E2EE session exchange their whole roster, and whatever an authenticated peer sends is taken as-is —
+ * no signed introductions, no confirmation step. So A links B, A links C ⇒ A tells B about C and C
+ * about B, and B↔C work. The cost: compromising ANY member lets it add keys the whole group trusts.
+ * The backend still cannot, since rosters only cross sealed E2EE sessions between the devices.
+ *
+ * Removal propagates as a tombstone that beats any entry for that key it is not older than; linking
+ * again stamps a newer entry, which beats the tombstone.
+ *
+ * Persistence mirrors machinePeers.ts: ${ADAPTER_DATA_DIR}/e2e/group.json, 0600, never cached — the
+ * daemon and a short-lived `harness link …` process both read and write it.
+ */
+import { createHash } from 'crypto'
+import { mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { env } from '../../config/env.js'
+import { b64d, fingerprint } from './core.js'
+import type { PeerKind } from './store.js'
+
+export interface GroupMember {
+ pub: string // base64 Ed25519 identity — the key every member pins/trusts
+ machineId?: string // set for kind 'machine' (a machine can be dialed; a viewer cannot)
+ kind: PeerKind
+ label: string
+ at: number // when this entry was stamped (link time); the newest entry for a key wins
+}
+
+export interface GroupTombstone {
+ pub: string
+ at: number
+}
+
+export interface Roster {
+ members: GroupMember[]
+ removed: GroupTombstone[]
+}
+
+export interface MergeResult {
+ roster: Roster
+ /** Members new to this roster, or whose entry changed (label/machineId). */
+ upserted: GroupMember[]
+ /** Members this merge dropped because a tombstone beat them. */
+ dropped: GroupMember[]
+}
+
+export const MAX_MEMBERS = 256
+export const MAX_TOMBSTONES = 256
+const MACHINE_ID_RE = /^[a-f0-9]{32}$/
+/** An entry stamped further in the future than this is refused — it would outlive every later removal. */
+const MAX_CLOCK_SKEW_MS = 24 * 60 * 60 * 1000
+
+const DIR = join(env.ADAPTER_DATA_DIR, 'e2e')
+const FILE = join(DIR, 'group.json')
+/** Keys this machine's own user unpaired (`harness unpair`): kept out of the trust stores here however
+ * often the group names them. Local only — never sent, so unpairing stays the one-machine act it was;
+ * `harness group remove` is the group-wide one. A new link to the key lifts it. */
+const BLOCKED_FILE = join(DIR, 'group-blocked.json')
+
+function isPub(v: unknown): v is string {
+ if (typeof v !== 'string' || v.length > 64) return false
+ try { return b64d(v).length === 32 } catch { return false }
+}
+
+function cleanLabel(v: unknown): string | null {
+ if (typeof v !== 'string') return null
+ const label = v.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 60)
+ return label || null
+}
+
+function isStamp(v: unknown, now: number): v is number {
+ return typeof v === 'number' && Number.isFinite(v) && v > 0 && v <= now + MAX_CLOCK_SKEW_MS
+}
+
+/** One member as received from a peer or read from disk; null when anything about it is off. */
+export function parseMember(raw: unknown, now = Date.now()): GroupMember | null {
+ if (!raw || typeof raw !== 'object') return null
+ const r = raw as Record<string, unknown>
+ if (!isPub(r.pub) || !isStamp(r.at, now)) return null
+ if (r.kind !== 'machine' && r.kind !== 'viewer') return null
+ const machineId = typeof r.machineId === 'string' && MACHINE_ID_RE.test(r.machineId) ? r.machineId : undefined
+ if (r.kind === 'machine' && !machineId) return null
+ const label = cleanLabel(r.label) ?? (machineId ?? 'device')
+ return { pub: r.pub, kind: r.kind, label, at: r.at, ...(r.kind === 'machine' ? { machineId } : {}) }
+}
+
+export function parseTombstone(raw: unknown, now = Date.now()): GroupTombstone | null {
+ if (!raw || typeof raw !== 'object') return null
+ const r = raw as Record<string, unknown>
+ if (!isPub(r.pub) || !isStamp(r.at, now)) return null
+ return { pub: r.pub, at: r.at }
+}
+
+/** A roster as received from a peer: malformed entries are dropped, and the lists are capped. */
+export function parseRoster(raw: unknown, now = Date.now()): Roster {
+ const r = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+ const members = Array.isArray(r.members) ? r.members.slice(0, MAX_MEMBERS).map((m) => parseMember(m, now)).filter((m): m is GroupMember => !!m) : []
+ const removed = Array.isArray(r.removed) ? r.removed.slice(0, MAX_TOMBSTONES).map((t) => parseTombstone(t, now)).filter((t): t is GroupTombstone => !!t) : []
+ return { members, removed }
+}
+
+function sameMember(a: GroupMember, b: GroupMember): boolean {
+ return a.pub === b.pub && a.kind === b.kind && a.label === b.label && a.machineId === b.machineId && a.at === b.at
+}
+
+/**
+ * Fold `incoming` into `local`. Pure. `selfPub` is this device's own identity: it is never taken in as
+ * a member (a device does not trust itself through the group) and a tombstone for it is ignored — once
+ * removed, the other members stop trusting it, which is what removal has to achieve.
+ */
+export function mergeRoster(local: Roster, incoming: Roster, selfPub: string): MergeResult {
+ const tombs = new Map<string, number>()
+ for (const t of [...local.removed, ...incoming.removed]) {
+ if (t.pub === selfPub) continue
+ tombs.set(t.pub, Math.max(tombs.get(t.pub) ?? 0, t.at))
+ }
+ const members = new Map<string, GroupMember>()
+ for (const m of local.members) if (m.pub !== selfPub) members.set(m.pub, m)
+ const before = new Map(members)
+
+ for (const m of incoming.members) {
+ if (m.pub === selfPub) continue
+ const existing = members.get(m.pub)
+ if (!existing || m.at > existing.at) members.set(m.pub, m)
+ }
+ const dropped: GroupMember[] = []
+ for (const [pub, m] of [...members]) {
+ const tomb = tombs.get(pub)
+ if (tomb !== undefined && tomb >= m.at) {
+ members.delete(pub)
+ if (before.has(pub)) dropped.push(before.get(pub)!)
+ }
+ }
+ // A tombstone only matters while some entry it beats could still be around; keep the newest ones.
+ const removed = [...tombs].map(([pub, at]) => ({ pub, at })).sort((a, b) => b.at - a.at).slice(0, MAX_TOMBSTONES)
+ const kept = [...members.values()].sort((a, b) => b.at - a.at).slice(0, MAX_MEMBERS)
+ const upserted = kept.filter((m) => { const prev = before.get(m.pub); return !prev || !sameMember(prev, m) })
+ return { roster: { members: kept, removed }, upserted, dropped }
+}
+
+/** Order-independent digest, so two members can tell in one message whether they already agree. */
+export function rosterDigest(roster: Roster): string {
+ const members = [...roster.members].sort((a, b) => a.pub.localeCompare(b.pub)).map((m) => [m.pub, m.kind, m.machineId ?? '', m.label, m.at])
+ const removed = [...roster.removed].sort((a, b) => a.pub.localeCompare(b.pub)).map((t) => [t.pub, t.at])
+ return createHash('sha256').update(JSON.stringify({ members, removed })).digest('base64')
+}
+
+export class TrustGroupStore {
+ read(): Roster {
+ try {
+ return parseRoster(JSON.parse(readFileSync(FILE, 'utf-8')))
+ } catch {
+ return { members: [], removed: [] }
+ }
+ }
+
+ write(roster: Roster): void {
+ mkdirSync(DIR, { recursive: true, mode: 0o700 })
+ writeFileSync(FILE, JSON.stringify(roster, null, 2), { mode: 0o600 })
+ }
+
+ /** Merge and persist; returns what changed so the caller can pin/trust or unpin/untrust. */
+ merge(incoming: Roster, selfPub: string): MergeResult {
+ const result = mergeRoster(this.read(), incoming, selfPub)
+ if (result.upserted.length || result.dropped.length || this.digestChanged(result.roster)) this.write(result.roster)
+ return result
+ }
+
+ /** Stamp a member (a fresh link, or one learned outside a sync) with `at`. */
+ add(member: GroupMember, selfPub: string): MergeResult {
+ return this.merge({ members: [member], removed: [] }, selfPub)
+ }
+
+ /** Remove a member everywhere: a tombstone newer than its current entry. */
+ remove(pub: string, selfPub: string, at = Date.now()): MergeResult {
+ const current = this.read().members.find((m) => m.pub === pub)
+ return this.merge({ members: [], removed: [{ pub, at: Math.max(at, (current?.at ?? 0) + 1) }] }, selfPub)
+ }
+
+ blocked(): Set<string> {
+ try {
+ const raw = JSON.parse(readFileSync(BLOCKED_FILE, 'utf-8')) as unknown
+ return new Set(Array.isArray(raw) ? raw.filter(isPub) : [])
+ } catch {
+ return new Set()
+ }
+ }
+
+ block(pub: string): void {
+ const blocked = this.blocked()
+ if (blocked.has(pub)) return
+ blocked.add(pub)
+ this.writeBlocked(blocked)
+ }
+
+ unblock(pub: string): void {
+ const blocked = this.blocked()
+ if (blocked.delete(pub)) this.writeBlocked(blocked)
+ }
+
+ list(): Array<GroupMember & { fingerprint: string }> {
+ return this.read().members.map((m) => ({ ...m, fingerprint: fingerprint(b64d(m.pub)) }))
+ }
+
+ private writeBlocked(blocked: Set<string>): void {
+ mkdirSync(DIR, { recursive: true, mode: 0o700 })
+ writeFileSync(BLOCKED_FILE, JSON.stringify([...blocked].slice(-MAX_MEMBERS)), { mode: 0o600 })
+ }
+
+ private digestChanged(next: Roster): boolean {
+ return rosterDigest(this.read()) !== rosterDigest(next)
+ }
+}
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.ts
index cb0276540..ded0e4cac 100644
--- a/cli/src/lib/remoteRelay.ts
+++ b/cli/src/lib/remoteRelay.ts
@@ -238,6 +238,9 @@ export interface RemoteRelayPoolOptions {
dialCooldownMs?: number
/** Share one failure record between pools (the background pools all draw on the parent's). */
dialFailures?: Map<string, { at: number; error: unknown }>
+ /** A fresh E2EE session to `machineId` is up (the trust group compares rosters then). Not passed on
+ * to the background pools — the group's own exchange runs on one of those. */
+ onSessionReady?: (machineId: string) => void
}
export class RemoteRelayPool {
@@ -248,6 +251,7 @@ export class RemoteRelayPool {
private readonly p2pEnabled: boolean
private readonly lingerMs: number
private readonly dialCooldownMs: number
+ private readonly onSessionReady: ((machineId: string) => void) | null
/** Warm background pools per machine, each holding one lingering session nobody is attached to —
* see acquireIsolated(). A pool is either here (idle) or in a client's hands, never both. */
private readonly idleIsolated = new Map<string, RemoteRelayPool[]>()
@@ -262,6 +266,7 @@ export class RemoteRelayPool {
this.p2pEnabled = opts.p2p !== false
this.lingerMs = opts.lingerMs ?? LINGER_MS
this.dialCooldownMs = opts.dialCooldownMs ?? 0
+ this.onSessionReady = opts.onSessionReady ?? null
this.lastDialFailure = opts.dialFailures ?? new Map()
}
@@ -500,6 +505,7 @@ export class RemoteRelayPool {
if (frame.type === 'e2e_welcome') {
const ok = crypto.handleWelcome((frame.payload ?? {}) as Record<string, unknown>)
if (!ok) { if (!settled) { settled = true; clearTimeout(timeout); reject(new RelayConnectError('E2EE_WELCOME_INVALID')) } ; return }
+ try { this.onSessionReady?.(machineId) } catch { /* an observer must not break the session */ }
// Three ways p2p never even starts, and until now all three looked identical from outside —
// the terminal just quietly stayed on the ws relay. The peer-version case is the important
// one: a machine whose CLI predates p2p answers no offer, so NO amount of STUN or TURN can
diff --git a/desktop/lib/e2ee/envelope.dart b/desktop/lib/e2ee/envelope.dart
index 2ce7afe0a..bdc20b730 100644
--- a/desktop/lib/e2ee/envelope.dart
+++ b/desktop/lib/e2ee/envelope.dart
@@ -42,6 +42,8 @@ const Set<String> encryptedDownTypes = {
'fs_list_dir',
'project_preview',
'git_project_info',
+ // The trust-group roster swap (`viewer/group_sync.dart`): the keys every member trusts.
+ 'group_sync',
'codex_profiles_list',
'codex_profile_link',
// Asks the machine to read its OWN agent accounts' usage (cli/src/lib/accountUsage.ts). Missing
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 50dd6fbe1..0ffbb2faa 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -4,7 +4,10 @@ import 'dart:math' show Random;
import 'package:dio/dio.dart';
-import 'dart:ui' show Color, Rect; // Rect: activeTileShape, the same one pane_preset.dart returns
+import 'dart:ui'
+ show
+ Color,
+ Rect; // Rect: activeTileShape, the same one pane_preset.dart returns
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart'
@@ -15,7 +18,9 @@ import '../analytics/analytics.dart';
import '../models/model_manager_controller.dart';
import '../api/api_client.dart';
import '../viewer/sign_in_browser.dart';
+import '../viewer/direct_link.dart';
import '../viewer/viewer_services.dart';
+import '../viewer/group_sync.dart' show GroupSyncOutcome;
import '../auth/auth_session.dart';
import '../auth/peer_link_client.dart';
import '../auth/sign_in_client.dart';
@@ -2140,6 +2145,9 @@ class AppNotifier extends ChangeNotifier {
/// What a machine hears the moment its socket is up — first connect, or a
/// reconnect after its daemon restarted, which has forgotten all of it.
void _onMachineConnected(String machineId, MachineState machine) {
+ // A viewer build keeps its own trust group (a CLI build's daemon keeps one for it): any session
+ // that comes up is the moment to compare it with this machine.
+ unawaited(_syncGroup(machineId));
_resetMachineDiscovery(machine);
_markSessionsUnreachable(
machine,
@@ -4825,6 +4833,8 @@ class AppNotifier extends ChangeNotifier {
await _pool?.closeMachine(targetId);
if (_authWorkCurrent(attempt.authRevision)) _connectMachine(state);
}
+ // One password, the whole group: this machine learns this device's other machines, and they it.
+ unawaited(_syncGroup(targetId, spread: true));
} catch (_) {
error = 'Could not link this machine. Try again.';
} finally {
@@ -4836,6 +4846,45 @@ class AppNotifier extends ChangeNotifier {
}
}
+ final Map<String, DateTime> _groupSyncedAt = {};
+ static const _groupResync = Duration(minutes: 5);
+
+ /// Viewer builds only: swaps trust-group rosters with [machineId] (`viewer/group_sync.dart`), at
+ /// most every few minutes per machine. With [spread] (a machine was just linked) or when the swap
+ /// taught this device a new machine, every other linked machine hears of it straight away. A
+ /// machine waiting for its password that the group now vouches for is picked up by its link retry.
+ /// No layout store means a test, which must not dial.
+ Future<void> _syncGroup(String machineId, {bool spread = false}) async {
+ // Only the app's own [DirectLink] dials for it: a CLI build's daemon keeps the group itself, and
+ // a test hands over fake links.
+ final links = peerLinks;
+ if (links is! DirectLink || _paneLayout == null) return;
+ final now = DateTime.now();
+ final last = _groupSyncedAt[machineId];
+ if (!spread && last != null && now.difference(last) < _groupResync) return;
+ _groupSyncedAt[machineId] = now;
+ // Fire-and-forget from the connection handler: a state file that is locked for a moment must not
+ // surface as an unhandled error. The next session retries.
+ try {
+ final label = localHostnameOrNull() ?? 'Desktop';
+ final GroupSyncOutcome outcome = await links.syncGroup(
+ machineId,
+ label: label,
+ );
+ if (!spread && outcome.pinned.isEmpty) return;
+ for (final other in [...machineStates.keys]) {
+ if (other == machineId || machineStates[other]?.nodeOnline == false) {
+ continue;
+ }
+ if (await links.keys.peer(other) == null) continue;
+ _groupSyncedAt[other] = DateTime.now();
+ await links.syncGroup(other, label: label);
+ }
+ } catch (_) {
+ _groupSyncedAt.remove(machineId);
+ }
+ }
+
List<LinkedMachine> linkedMachines = [];
bool linkedMachinesLoading = false;
String? linkedMachinesError;
diff --git a/desktop/lib/viewer/direct_link.dart b/desktop/lib/viewer/direct_link.dart
index 17d0dc13c..977d1c1b0 100644
--- a/desktop/lib/viewer/direct_link.dart
+++ b/desktop/lib/viewer/direct_link.dart
@@ -5,6 +5,7 @@ import '../core/config.dart';
import '../e2ee/keys.dart';
import 'direct_auth.dart';
import 'direct_auth_api.dart';
+import 'group_sync.dart';
import 'password_link.dart';
import 'viewer_key_store.dart';
@@ -64,6 +65,30 @@ class DirectLink implements PeerLinkClient {
}
}
+ /// Swaps trust-group rosters with [machineId] ([syncTrustGroup]): the machines this device learns
+ /// of are pinned — no password for them — and the machine learns this device and whatever it
+ /// linked. [label] is this device's name for itself. Never throws.
+ Future<GroupSyncOutcome> syncGroup(
+ String machineId, {
+ required String label,
+ }) async {
+ final String token;
+ try {
+ token = await auth.accessToken();
+ } catch (_) {
+ return GroupSyncOutcome.none;
+ }
+ return syncTrustGroup(
+ machineId: machineId,
+ keys: keys,
+ accessToken: token,
+ wsBaseUrl: config.wsBaseUrl,
+ autonomousEnv: config.autonomousEnv,
+ label: label,
+ socket: socket,
+ );
+ }
+
@override
Future<CliLinkListResult> list() async => CliLinkListResult(
machines: [
diff --git a/desktop/lib/viewer/group_sync.dart b/desktop/lib/viewer/group_sync.dart
new file mode 100644
index 000000000..3c61bca06
--- /dev/null
+++ b/desktop/lib/viewer/group_sync.dart
@@ -0,0 +1,383 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+import '../e2ee/bytes.dart';
+import '../e2ee/envelope.dart';
+import '../e2ee/relay_session_crypto.dart';
+import 'password_link.dart' show RelaySocketFactory, defaultRelaySocket;
+import 'viewer_key_store.dart';
+
+/// The trust group, on a device with no harness CLI — the viewer's half of `cli/src/lib/e2ee/
+/// trustGroup.ts` and `groupSyncer.ts`.
+///
+/// Every machine and phone of an account that has linked, directly or through another member, trusts
+/// every other. Any session this phone opens to a machine is a chance to swap rosters with it
+/// (`group_sync`, sealed): the phone learns every machine's key and pins it — no password for those —
+/// and the machine learns the phone and every machine the phone linked, and passes them on.
+///
+/// By product decision this favours ease over strictness: what an authenticated peer sends is taken
+/// as-is. The relay still cannot add anyone, since rosters only cross sealed sessions.
+
+/// A device's entry for ITSELF is stamped older than anything, so any removal beats it — see
+/// groupSyncer.ts `SELF_STAMP`.
+const int groupSelfStamp = 1;
+const int _maxMembers = 256;
+const int _maxTombstones = 256;
+const Duration _maxClockSkew = Duration(hours: 24);
+final RegExp _machineIdPattern = RegExp(r'^[a-f0-9]{32}$');
+
+class GroupMember {
+ const GroupMember({
+ required this.pub,
+ required this.kind,
+ required this.label,
+ required this.at,
+ this.machineId,
+ });
+
+ final String pub;
+ final String kind; // 'machine' | 'viewer'
+ final String label;
+ final int at;
+ final String? machineId;
+
+ bool get isMachine => kind == 'machine';
+
+ /// Null for anything malformed — the same rule as trustGroup.ts `parseMember`.
+ static GroupMember? tryParse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return null;
+ final pub = raw['pub'], at = raw['at'], kind = raw['kind'];
+ if (!_isPub(pub) || !_isStamp(at, now ?? DateTime.now())) return null;
+ if (kind != 'machine' && kind != 'viewer') return null;
+ final id = raw['machineId'];
+ final machineId = id is String && _machineIdPattern.hasMatch(id)
+ ? id
+ : null;
+ if (kind == 'machine' && machineId == null) return null;
+ return GroupMember(
+ pub: pub as String,
+ kind: kind as String,
+ label: _cleanLabel(raw['label']) ?? machineId ?? 'device',
+ at: at as int,
+ machineId: kind == 'machine' ? machineId : null,
+ );
+ }
+
+ Map<String, Object> toJson() => {
+ 'pub': pub,
+ 'kind': kind,
+ 'label': label,
+ 'at': at,
+ 'machineId': ?machineId,
+ };
+
+ bool sameAs(GroupMember o) =>
+ pub == o.pub &&
+ kind == o.kind &&
+ label == o.label &&
+ at == o.at &&
+ machineId == o.machineId;
+}
+
+class GroupTombstone {
+ const GroupTombstone(this.pub, this.at);
+ final String pub;
+ final int at;
+
+ static GroupTombstone? tryParse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return null;
+ final pub = raw['pub'], at = raw['at'];
+ if (!_isPub(pub) || !_isStamp(at, now ?? DateTime.now())) return null;
+ return GroupTombstone(pub as String, at as int);
+ }
+
+ Map<String, Object> toJson() => {'pub': pub, 'at': at};
+}
+
+class GroupRoster {
+ const GroupRoster(this.members, this.removed);
+ static const empty = GroupRoster([], []);
+
+ final List<GroupMember> members;
+ final List<GroupTombstone> removed;
+
+ static GroupRoster parse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return empty;
+ final members = raw['members'], removed = raw['removed'];
+ return GroupRoster(
+ members is List
+ ? members
+ .take(_maxMembers)
+ .map((m) => GroupMember.tryParse(m, now: now))
+ .whereType<GroupMember>()
+ .toList()
+ : const [],
+ removed is List
+ ? removed
+ .take(_maxTombstones)
+ .map((t) => GroupTombstone.tryParse(t, now: now))
+ .whereType<GroupTombstone>()
+ .toList()
+ : const [],
+ );
+ }
+
+ Map<String, Object> toJson() => {
+ 'members': [for (final m in members) m.toJson()],
+ 'removed': [for (final t in removed) t.toJson()],
+ };
+}
+
+class GroupMerge {
+ const GroupMerge(this.roster, this.upserted, this.dropped);
+ final GroupRoster roster;
+ final List<GroupMember> upserted;
+ final List<GroupMember> dropped;
+}
+
+/// trustGroup.ts `mergeRoster`, line for line: the newest entry for a key wins, a tombstone beats
+/// every entry it is not older than, and a device never takes itself in.
+GroupMerge mergeGroupRoster(
+ GroupRoster local,
+ GroupRoster incoming,
+ String selfPub,
+) {
+ final tombs = <String, int>{};
+ for (final t in [...local.removed, ...incoming.removed]) {
+ if (t.pub == selfPub) continue;
+ final prev = tombs[t.pub];
+ tombs[t.pub] = prev == null || t.at > prev ? t.at : prev;
+ }
+ final members = <String, GroupMember>{
+ for (final m in local.members)
+ if (m.pub != selfPub) m.pub: m,
+ };
+ final before = Map.of(members);
+ for (final m in incoming.members) {
+ if (m.pub == selfPub) continue;
+ final existing = members[m.pub];
+ if (existing == null || m.at > existing.at) members[m.pub] = m;
+ }
+ final dropped = <GroupMember>[];
+ for (final pub in [...members.keys]) {
+ final tomb = tombs[pub];
+ if (tomb != null && tomb >= members[pub]!.at) {
+ members.remove(pub);
+ if (before[pub] case final prev?) dropped.add(prev);
+ }
+ }
+ final removed = [
+ for (final e in tombs.entries) GroupTombstone(e.key, e.value),
+ ]..sort((a, b) => b.at.compareTo(a.at));
+ final kept = members.values.toList()..sort((a, b) => b.at.compareTo(a.at));
+ final roster = GroupRoster(
+ kept.take(_maxMembers).toList(),
+ removed.take(_maxTombstones).toList(),
+ );
+ final upserted = [
+ for (final m in roster.members)
+ if (before[m.pub] == null || !before[m.pub]!.sameAs(m)) m,
+ ];
+ return GroupMerge(roster, upserted, dropped);
+}
+
+/// One roster swap with a machine, as the app calls it — `DirectLink.syncGroup`.
+typedef GroupSync = Future<GroupSyncOutcome> Function(
+ String machineId, {
+ required String label,
+});
+
+/// What one exchange changed on this phone.
+class GroupSyncOutcome {
+ const GroupSyncOutcome({this.pinned = const [], this.unpinned = const []});
+ static const none = GroupSyncOutcome();
+
+ /// Machines this phone can now reach without their password.
+ final List<String> pinned;
+
+ /// Machines the group removed; this phone no longer dials them.
+ final List<String> unpinned;
+
+ bool get changed => pinned.isNotEmpty || unpinned.isNotEmpty;
+}
+
+/// Swaps rosters with one machine over a short-lived sealed session of its own, then pins what it
+/// learned. Never throws: a machine that is offline, too old to answer or refuses leaves everything
+/// as it was.
+Future<GroupSyncOutcome> syncTrustGroup({
+ required String machineId,
+ required ViewerKeyStore keys,
+ required String accessToken,
+ required String wsBaseUrl,
+ required String autonomousEnv,
+ required String label,
+ RelaySocketFactory socket = defaultRelaySocket,
+ Duration timeout = const Duration(seconds: 20),
+}) async {
+ WebSocketChannel? channel;
+ try {
+ final pin = await keys.peer(machineId);
+ if (pin == null) return GroupSyncOutcome.none;
+ final identity = await keys.identity();
+ final selfPub = b64e(identity.pub);
+ final local = await _seeded(keys, selfPub);
+ final self = GroupMember(
+ pub: selfPub,
+ kind: 'viewer',
+ label: label,
+ at: groupSelfStamp,
+ );
+ final crypto = await RelaySessionCrypto.start(
+ machineId: machineId,
+ identity: identity,
+ peerPub: pin.pub,
+ );
+ final uri = Uri.parse('$wsBaseUrl/api/web-ws')
+ .replace(queryParameters: {'autonomousEnv': autonomousEnv});
+ final ch = channel = socket(uri, [accessToken]);
+ final reply = await () async {
+ await ch.ready;
+ return _exchange(ch, crypto, machineId, {
+ 'requestId': b64e(secureRandomBytes(12)),
+ 'self': self.toJson(),
+ ...local.toJson(),
+ });
+ }().timeout(timeout, onTimeout: () => null);
+ if (reply == null || reply['error'] != null) return GroupSyncOutcome.none;
+
+ final incoming = GroupRoster.parse(reply);
+ final theirs = GroupMember.tryParse(reply['self']);
+ // The machine may describe only itself, as the key this phone dialed and verified.
+ final members = [
+ ...incoming.members,
+ if (theirs != null &&
+ theirs.machineId == machineId &&
+ theirs.pub == b64e(pin.pub))
+ theirs,
+ ];
+ final merged = mergeGroupRoster(
+ local,
+ GroupRoster(members, incoming.removed),
+ selfPub,
+ );
+ await keys.writeGroupRoster(merged.roster.toJson());
+ return await _apply(keys, merged);
+ } catch (_) {
+ return GroupSyncOutcome.none;
+ } finally {
+ if (channel != null) unawaited(channel.sink.close());
+ }
+}
+
+/// This phone's roster, with every machine it has pinned folded in — how a machine this phone linked
+/// by password reaches the rest of the group, and how links made before the group existed join it.
+Future<GroupRoster> _seeded(ViewerKeyStore keys, String selfPub) async {
+ final stored = GroupRoster.parse(await keys.groupRoster());
+ // Only pins the roster does not name yet: a pin's `linkedAt` is when THIS device pinned it (the
+ // group's own pins included), and folding that in again would restamp the member as new on every
+ // swap and push the change around the whole group.
+ final known = {for (final m in stored.members) m.pub};
+ final pins = [
+ for (final p in await keys.peers())
+ if (!known.contains(b64e(p.pub)))
+ ?GroupMember.tryParse({
+ 'pub': b64e(p.pub),
+ 'machineId': p.machineId,
+ 'kind': 'machine',
+ 'label': p.label.isEmpty ? p.machineId : p.label,
+ 'at': p.linkedAt.millisecondsSinceEpoch,
+ }),
+ ];
+ return mergeGroupRoster(stored, GroupRoster(pins, const []), selfPub).roster;
+}
+
+Future<GroupSyncOutcome> _apply(ViewerKeyStore keys, GroupMerge merged) async {
+ final pinned = <String>[], unpinned = <String>[];
+ for (final m in merged.upserted) {
+ final id = m.machineId;
+ if (!m.isMachine || id == null) continue;
+ final current = await keys.peer(id);
+ if (current != null && b64e(current.pub) == m.pub) continue;
+ await keys.pin(id, b64d(m.pub), label: m.label);
+ pinned.add(id);
+ }
+ for (final m in merged.dropped) {
+ final id = m.machineId;
+ if (id == null) continue;
+ final current = await keys.peer(id);
+ if (current == null || b64e(current.pub) != m.pub) continue;
+ if (await keys.unlink(id)) unpinned.add(id);
+ }
+ return GroupSyncOutcome(pinned: pinned, unpinned: unpinned);
+}
+
+/// select → hello/welcome → one sealed `group_sync` → its sealed `_result`.
+Future<Map<String, dynamic>?> _exchange(
+ WebSocketChannel channel,
+ RelaySessionCrypto crypto,
+ String machineId,
+ Map<String, Object?> request,
+) async {
+ void send(Map<String, dynamic> frame) => channel.sink.add(jsonEncode(frame));
+ send({
+ 'type': 'machine_select',
+ 'payload': {'machineId': machineId},
+ });
+ var selected = false;
+ await for (final raw in channel.stream) {
+ final frame = raw is String ? jsonObjectOf(utf8Bytes(raw)) : null;
+ if (frame == null) continue;
+ final type = frame['type'];
+ final payload = frame['payload'];
+ if (!selected) {
+ if (type == 'connected' &&
+ payload is Map &&
+ payload['machineId'] == machineId) {
+ selected = true;
+ send(crypto.helloFrame());
+ } else if (type == 'machine_select_error') {
+ return null;
+ }
+ continue;
+ }
+ if (type == 'e2e_denied') return null;
+ if (type == 'e2e_welcome' && payload is Map<String, dynamic>) {
+ if (!await crypto.handleWelcome(payload)) return null;
+ send(crypto.wrapOutgoing({'type': 'group_sync', 'payload': request}));
+ continue;
+ }
+ if (type == 'group_sync_result') {
+ final opened = crypto.unwrapIncoming(frame);
+ final body = opened?['payload'];
+ if (body is Map<String, dynamic> &&
+ body['requestId'] == request['requestId']) {
+ return body;
+ }
+ }
+ }
+ return null;
+}
+
+bool _isPub(Object? v) {
+ if (v is! String || v.length > 64) return false;
+ try {
+ return b64d(v).length == 32;
+ } on FormatException {
+ return false;
+ }
+}
+
+bool _isStamp(Object? v, DateTime now) =>
+ v is int && v > 0 && v <= now.add(_maxClockSkew).millisecondsSinceEpoch;
+
+String? _cleanLabel(Object? v) {
+ if (v is! String) return null;
+ final label = v
+ .replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ')
+ .replaceAll(RegExp(r'\s+'), ' ')
+ .trim();
+ if (label.isEmpty) return null;
+ return label.length > 60 ? label.substring(0, 60) : label;
+}
diff --git a/desktop/lib/viewer/password_link.dart b/desktop/lib/viewer/password_link.dart
index 5c366f989..df5edc77a 100644
--- a/desktop/lib/viewer/password_link.dart
+++ b/desktop/lib/viewer/password_link.dart
@@ -221,6 +221,9 @@ class _PasswordLinkRun {
final ours = jsonEncode({
'id': b64e(identity.pub),
'sig': b64e(await pairBindSig(identity, transcript)),
+ // A viewer, not a machine: it dials out and is never dialed, so the machine trusts it and
+ // does not pin it back. A machine that predates the field ignores it.
+ 'kind': 'viewer',
});
_send('e2e_pw_pake', {
'sid': _sidB64,
diff --git a/desktop/lib/viewer/viewer_key_store.dart b/desktop/lib/viewer/viewer_key_store.dart
index d36d676a6..1487fbc3c 100644
--- a/desktop/lib/viewer/viewer_key_store.dart
+++ b/desktop/lib/viewer/viewer_key_store.dart
@@ -62,6 +62,7 @@ class ViewerKeyStore {
static const _seedKey = 'viewer_e2ee_identity_seed';
static const _peersKey = 'viewer_e2ee_machine_peers';
+ static const _groupKey = 'viewer_e2ee_group';
/// Minted on first use and kept: every linked machine has pinned it.
Future<E2eeIdentity> identity() => _identity ??= _loadOrMintIdentity();
@@ -123,6 +124,21 @@ class ViewerKeyStore {
return true;
});
+ /// The trust group as this device last knew it (`group_sync.dart`), as stored JSON; null when
+ /// there is none yet or it cannot be read.
+ Future<Object?> groupRoster() async {
+ final raw = await _storage.read(_groupKey);
+ if (raw == null) return null;
+ try {
+ return jsonDecode(raw);
+ } on FormatException {
+ return null;
+ }
+ }
+
+ Future<void> writeGroupRoster(Map<String, Object> roster) =>
+ _storage.write(_groupKey, jsonEncode(roster));
+
Future<void> _write(List<MachinePeer> peers) => _storage.write(
_peersKey,
jsonEncode([for (final peer in peers) peer.toJson()]),
diff --git a/desktop/test/viewer/group_sync_test.dart b/desktop/test/viewer/group_sync_test.dart
new file mode 100644
index 000000000..db0a81c51
--- /dev/null
+++ b/desktop/test/viewer/group_sync_test.dart
@@ -0,0 +1,208 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/local_key_value_store.dart';
+import 'package:harness/e2ee/bytes.dart';
+import 'package:harness/e2ee/envelope.dart';
+import 'package:harness/e2ee/keys.dart';
+import 'package:harness/e2ee/primitives.dart';
+import 'package:harness/viewer/group_sync.dart';
+import 'package:harness/viewer/viewer_key_store.dart';
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+/// The viewer build's trust-group swap (`lib/viewer/group_sync.dart`) — the same code the phone
+/// runs, against a machine end that answers exactly as manager.ts does.
+
+const _machineId = 'machine-1';
+final _c = 'c' * 32;
+
+class _Memory implements LocalKeyValueStore {
+ final values = <String, String>{};
+ @override
+ Future<String?> read(String key) async => values[key];
+ @override
+ Future<void> write(String key, String value) async => values[key] = value;
+ @override
+ Future<void> delete(String key) async => values.remove(key);
+}
+
+/// A relay socket whose far end is the test.
+class _Socket implements WebSocketChannel {
+ _Socket(this.onFrame);
+ final void Function(_Socket socket, Map<String, dynamic> frame) onFrame;
+ final sent = <Map<String, dynamic>>[];
+ final _down = StreamController<dynamic>();
+ late final _sink = _Sink(this);
+ @override
+ Future<void> get ready => Future.value();
+ @override
+ Stream<dynamic> get stream => _down.stream;
+ @override
+ WebSocketSink get sink => _sink;
+ void emit(Map<String, dynamic> frame) => _down.add(jsonEncode(frame));
+ WebSocketChannel factory(Uri _, Iterable<String> _) => this;
+ @override
+ dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
+}
+
+class _Sink implements WebSocketSink {
+ _Sink(this._s);
+ final _Socket _s;
+ bool closed = false;
+ @override
+ void add(dynamic data) {
+ final frame = jsonDecode(data as String) as Map<String, dynamic>;
+ _s.sent.add(frame);
+ _s.onFrame(_s, frame);
+ }
+
+ @override
+ Future<void> close([int? closeCode, String? closeReason]) async =>
+ closed = true;
+ @override
+ dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
+}
+
+/// manager.ts `onHello` + `wrapRpcReply`, for one session.
+Future<_Socket> _machine(
+ E2eeIdentity identity,
+ Map<String, Object?> Function(Map<String, dynamic> request) reply,
+) async {
+ SessionKeys? keys;
+ var counter = 1;
+ return _Socket((socket, frame) async {
+ final payload = frame['payload'] as Map<String, dynamic>;
+ switch (frame['type']) {
+ case 'machine_select':
+ socket.emit({
+ 'type': 'connected',
+ 'payload': {'machineId': _machineId},
+ });
+ case 'e2e_hello':
+ final webEph = b64d(payload['ephPub'] as String);
+ final eph = await Ephemeral.generate();
+ final k = keys = sessionKeys(eph, webEph, _machineId, webEph, eph.pub);
+ final sig = await identity.sign(
+ lvCat(['e2e-welcome-v1', _machineId, webEph, eph.pub]),
+ );
+ final enc = aeadSeal(
+ k.s2c,
+ 0,
+ utf8Bytes('e2e-welcome'),
+ utf8Bytes(
+ jsonEncode({
+ 'groupKey': b64e(Uint8List(32)),
+ 'epoch': 'e1',
+ 'features': {'strictDown': 1},
+ }),
+ ),
+ );
+ socket.emit({
+ 'type': 'e2e_welcome',
+ 'payload': {
+ 'webEphPub': b64e(webEph),
+ 'ephPub': b64e(eph.pub),
+ 'sig': b64e(sig),
+ 'enc': b64e(enc),
+ },
+ });
+ case 'group_sync':
+ expect(
+ isWrapped(payload),
+ isTrue,
+ reason: 'the roster must never cross the relay in the clear',
+ );
+ final request = unwrapPayload(
+ keys!.c2s,
+ payload['__e2e'] as Map<String, dynamic>,
+ 'group_sync',
+ null,
+ )!;
+ socket.emit({
+ 'type': 'group_sync_result',
+ 'payload': wrapPayload(
+ keys!.s2c,
+ 'p',
+ counter++,
+ 'group_sync_result',
+ null,
+ {'requestId': request['requestId'], ...reply(request)},
+ ),
+ });
+ }
+ });
+}
+
+void main() {
+ test(
+ 'the viewer build swaps rosters sealed, and pins every machine it learns',
+ () async {
+ final keys = ViewerKeyStore(storage: _Memory());
+ final machine = await E2eeIdentity.generate();
+ final cPub = b64e((await E2eeIdentity.generate()).pub);
+ await keys.pin(_machineId, machine.pub);
+ Map<String, dynamic>? seen;
+ final socket = await _machine(machine, (request) {
+ seen = request;
+ return {
+ 'members': [
+ {
+ 'pub': cPub,
+ 'kind': 'machine',
+ 'machineId': _c,
+ 'label': 'c',
+ 'at': 50,
+ },
+ ],
+ 'removed': [],
+ };
+ });
+ final outcome = await syncTrustGroup(
+ machineId: _machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'Studio PC',
+ socket: socket.factory,
+ );
+ expect(seen!['self'], containsPair('kind', 'viewer'));
+ expect(outcome.pinned, [_c]);
+ expect(b64e((await keys.peer(_c))!.pub), cPub);
+ },
+ );
+
+ test('the merge matches the CLI: tombstones beat older entries, newer links beat tombstones', () async {
+ final self = b64e((await E2eeIdentity.generate()).pub);
+ final pub = b64e((await E2eeIdentity.generate()).pub);
+ final b = GroupMember(
+ pub: pub,
+ kind: 'machine',
+ label: 'b',
+ at: 10,
+ machineId: 'b' * 32,
+ );
+ final removed = mergeGroupRoster(
+ GroupRoster([b], const []),
+ GroupRoster(const [], [GroupTombstone(pub, 10)]),
+ self,
+ );
+ expect(removed.roster.members, isEmpty);
+ final back = mergeGroupRoster(
+ removed.roster,
+ GroupRoster([
+ GroupMember(
+ pub: pub,
+ kind: 'machine',
+ label: 'b',
+ at: 11,
+ machineId: 'b' * 32,
+ ),
+ ], const []),
+ self,
+ );
+ expect(back.roster.members.single.at, 11);
+ });
+}
diff --git a/mobile/lib/e2ee/envelope.dart b/mobile/lib/e2ee/envelope.dart
index 6e3de6905..acc344c90 100644
--- a/mobile/lib/e2ee/envelope.dart
+++ b/mobile/lib/e2ee/envelope.dart
@@ -46,6 +46,8 @@ const Set<String> encryptedDownTypes = {
'git_project_info',
// The harness's branch and pull-request history is a machine RPC too.
'git_pull_request',
+ // The trust-group roster swap (`viewer/group_sync.dart`): the keys every member trusts.
+ 'group_sync',
'codex_profiles_list',
'codex_profile_link',
// Asks the machine to read its OWN agent accounts' usage (cli/src/lib/accountUsage.ts). Missing
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 219cfcf09..58043b7a4 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -9,6 +9,8 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../analytics/analytics.dart';
import '../api/api_client.dart';
import '../viewer/direct_auth_api.dart';
+import '../viewer/direct_link.dart';
+import '../viewer/group_sync.dart';
import '../viewer/viewer_services.dart';
import '../auth/auth_session.dart';
import '../auth/peer_link_client.dart';
@@ -899,6 +901,7 @@ class AppNotifier extends ChangeNotifier {
PaneLayoutStore? paneLayoutStore,
SystemNotices? systemNotices,
MachineCache? machineCache,
+ GroupSync? groupSync,
this.turnActivityTimeout = const Duration(seconds: 12),
}) : _paneLayout = paneLayoutStore,
// On the same terms as the stores below: no layout store means a test,
@@ -935,6 +938,7 @@ class AppNotifier extends ChangeNotifier {
) {
this.cliLogin = cliLogin ?? this.viewer.login;
this.peerLinks = peerLinks ?? this.viewer.links;
+ _groupSyncOverride = groupSync;
_autonomousEnv = this.config.autonomousEnv;
api = _newApiClient();
}
@@ -1568,6 +1572,8 @@ class AppNotifier extends ChangeNotifier {
unawaited(_applyNodeStatus(machine, true));
unawaited(_loadMachineData(machine, force: true));
_startAgentSyncTimer(machineId);
+ // A session came up: the moment to compare trust groups with this machine.
+ unawaited(_syncGroup(machineId));
} else if (nextStatus == ConnectionStatus.reconnecting ||
nextStatus == ConnectionStatus.disconnected) {
_stopAgentSyncTimer(machineId);
@@ -1924,6 +1930,8 @@ class AppNotifier extends ChangeNotifier {
await _pool?.closeMachine(targetId);
_connectMachine(state);
}
+ // One password, the whole group: this machine learns the phone's other machines, and they it.
+ unawaited(_syncGroup(targetId, spread: true));
return null;
}
@@ -1958,9 +1966,82 @@ class AppNotifier extends ChangeNotifier {
await _pool?.closeMachine(state.machine.machineId);
_connectMachine(state);
}
+ unawaited(_syncGroup(result.linkedMachineId ?? machineId, spread: true));
return null;
}
+ /// A test's stand-in for the trust-group roster swap; null uses [DirectLink.syncGroup].
+ late final GroupSync? _groupSyncOverride;
+
+ /// The trust-group roster swap (`viewer/group_sync.dart`). Only the app's own [DirectLink] dials
+ /// for it — a test that hands over fake links, or has no layout store (no state file), never does.
+ GroupSync? get _groupSync {
+ if (_groupSyncOverride case final sync?) return sync;
+ final links = peerLinks;
+ return links is DirectLink && _paneLayout != null ? links.syncGroup : null;
+ }
+ final Map<String, DateTime> _groupSyncedAt = {};
+ static const _groupResync = Duration(minutes: 5);
+
+ /// Swaps trust-group rosters with [machineId], at most every few minutes per machine — any
+ /// session this phone opens is the moment. With [spread] (a machine was just linked) or when the
+ /// swap taught this phone a new machine, every other linked machine hears of it straight away.
+ Future<void> _syncGroup(String machineId, {bool spread = false}) async {
+ final sync = _groupSync;
+ if (sync == null) return;
+ final now = DateTime.now();
+ final last = _groupSyncedAt[machineId];
+ if (!spread && last != null && now.difference(last) < _groupResync) return;
+ _groupSyncedAt[machineId] = now;
+ // Fire-and-forget from the connection handler: a state file that is locked for a moment must not
+ // surface as an unhandled error. The next session retries.
+ try {
+ final label = phoneClientDescriptor().name;
+ final outcome = await sync(machineId, label: label);
+ await _afterGroupSync(outcome);
+ if (!spread && outcome.pinned.isEmpty) return;
+ for (final other in [...machineStates.keys]) {
+ if (other == machineId || machineStates[other]?.nodeOnline == false) {
+ continue;
+ }
+ if (await viewer.keys.peer(other) == null) continue;
+ _groupSyncedAt[other] = DateTime.now();
+ await _afterGroupSync(await sync(other, label: label));
+ }
+ } catch (_) {
+ _groupSyncedAt.remove(machineId);
+ }
+ }
+
+ /// What a roster swap changed, applied to the machines on screen: a machine the group removed wants
+ /// its password again; a machine waiting for one that the group has now vouched for is dialed.
+ Future<void> _afterGroupSync(GroupSyncOutcome outcome) async {
+ var changed = false;
+ for (final id in outcome.unpinned) {
+ final machine = machineStates[id];
+ if (machine == null || machine.needsLink) continue;
+ machine.needsLink = true;
+ machine.agentLoadStatus = AgentLoadStatus.needsLink;
+ await _pool?.closeMachine(id);
+ _markSessionsUnreachable(
+ machine,
+ 'This machine left your group. Enter its password to reconnect.',
+ );
+ changed = true;
+ }
+ for (final machine in [...machineStates.values]) {
+ if (!machine.needsLink) continue;
+ final id = machine.machine.machineId;
+ if (await viewer.keys.peer(id) == null) continue;
+ machine.needsLink = false;
+ machine.agentLoadStatus = AgentLoadStatus.idle;
+ await _pool?.closeMachine(id);
+ _connectMachine(machine);
+ changed = true;
+ }
+ if (changed) notifyListeners();
+ }
+
List<LinkedMachine> linkedMachines = [];
bool linkedMachinesLoading = false;
String? linkedMachinesError;
diff --git a/mobile/lib/viewer/direct_link.dart b/mobile/lib/viewer/direct_link.dart
index bd4494b98..7129e1c94 100644
--- a/mobile/lib/viewer/direct_link.dart
+++ b/mobile/lib/viewer/direct_link.dart
@@ -6,6 +6,7 @@ import '../e2ee/keys.dart';
import 'direct_auth.dart';
import 'direct_auth_api.dart';
import 'code_link.dart';
+import 'group_sync.dart';
import 'password_link.dart';
import 'viewer_key_store.dart';
@@ -151,6 +152,30 @@ class DirectLink implements PeerLinkClient {
);
}
+ /// Swaps trust-group rosters with [machineId] ([syncTrustGroup]): the machines this phone learns of
+ /// are pinned — no password for them — and the machine learns this phone and whatever it linked.
+ /// [label] is this phone's name for itself. Never throws.
+ Future<GroupSyncOutcome> syncGroup(
+ String machineId, {
+ required String label,
+ }) async {
+ final String token;
+ try {
+ token = await auth.accessToken();
+ } catch (_) {
+ return GroupSyncOutcome.none;
+ }
+ return syncTrustGroup(
+ machineId: machineId,
+ keys: keys,
+ accessToken: token,
+ wsBaseUrl: config.wsBaseUrl,
+ autonomousEnv: config.autonomousEnv,
+ label: label,
+ socket: socket,
+ );
+ }
+
@override
Future<CliLinkListResult> list() async => CliLinkListResult(
machines: [
diff --git a/mobile/lib/viewer/group_sync.dart b/mobile/lib/viewer/group_sync.dart
new file mode 100644
index 000000000..3c61bca06
--- /dev/null
+++ b/mobile/lib/viewer/group_sync.dart
@@ -0,0 +1,383 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:web_socket_channel/web_socket_channel.dart';
+
+import '../e2ee/bytes.dart';
+import '../e2ee/envelope.dart';
+import '../e2ee/relay_session_crypto.dart';
+import 'password_link.dart' show RelaySocketFactory, defaultRelaySocket;
+import 'viewer_key_store.dart';
+
+/// The trust group, on a device with no harness CLI — the viewer's half of `cli/src/lib/e2ee/
+/// trustGroup.ts` and `groupSyncer.ts`.
+///
+/// Every machine and phone of an account that has linked, directly or through another member, trusts
+/// every other. Any session this phone opens to a machine is a chance to swap rosters with it
+/// (`group_sync`, sealed): the phone learns every machine's key and pins it — no password for those —
+/// and the machine learns the phone and every machine the phone linked, and passes them on.
+///
+/// By product decision this favours ease over strictness: what an authenticated peer sends is taken
+/// as-is. The relay still cannot add anyone, since rosters only cross sealed sessions.
+
+/// A device's entry for ITSELF is stamped older than anything, so any removal beats it — see
+/// groupSyncer.ts `SELF_STAMP`.
+const int groupSelfStamp = 1;
+const int _maxMembers = 256;
+const int _maxTombstones = 256;
+const Duration _maxClockSkew = Duration(hours: 24);
+final RegExp _machineIdPattern = RegExp(r'^[a-f0-9]{32}$');
+
+class GroupMember {
+ const GroupMember({
+ required this.pub,
+ required this.kind,
+ required this.label,
+ required this.at,
+ this.machineId,
+ });
+
+ final String pub;
+ final String kind; // 'machine' | 'viewer'
+ final String label;
+ final int at;
+ final String? machineId;
+
+ bool get isMachine => kind == 'machine';
+
+ /// Null for anything malformed — the same rule as trustGroup.ts `parseMember`.
+ static GroupMember? tryParse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return null;
+ final pub = raw['pub'], at = raw['at'], kind = raw['kind'];
+ if (!_isPub(pub) || !_isStamp(at, now ?? DateTime.now())) return null;
+ if (kind != 'machine' && kind != 'viewer') return null;
+ final id = raw['machineId'];
+ final machineId = id is String && _machineIdPattern.hasMatch(id)
+ ? id
+ : null;
+ if (kind == 'machine' && machineId == null) return null;
+ return GroupMember(
+ pub: pub as String,
+ kind: kind as String,
+ label: _cleanLabel(raw['label']) ?? machineId ?? 'device',
+ at: at as int,
+ machineId: kind == 'machine' ? machineId : null,
+ );
+ }
+
+ Map<String, Object> toJson() => {
+ 'pub': pub,
+ 'kind': kind,
+ 'label': label,
+ 'at': at,
+ 'machineId': ?machineId,
+ };
+
+ bool sameAs(GroupMember o) =>
+ pub == o.pub &&
+ kind == o.kind &&
+ label == o.label &&
+ at == o.at &&
+ machineId == o.machineId;
+}
+
+class GroupTombstone {
+ const GroupTombstone(this.pub, this.at);
+ final String pub;
+ final int at;
+
+ static GroupTombstone? tryParse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return null;
+ final pub = raw['pub'], at = raw['at'];
+ if (!_isPub(pub) || !_isStamp(at, now ?? DateTime.now())) return null;
+ return GroupTombstone(pub as String, at as int);
+ }
+
+ Map<String, Object> toJson() => {'pub': pub, 'at': at};
+}
+
+class GroupRoster {
+ const GroupRoster(this.members, this.removed);
+ static const empty = GroupRoster([], []);
+
+ final List<GroupMember> members;
+ final List<GroupTombstone> removed;
+
+ static GroupRoster parse(Object? raw, {DateTime? now}) {
+ if (raw is! Map) return empty;
+ final members = raw['members'], removed = raw['removed'];
+ return GroupRoster(
+ members is List
+ ? members
+ .take(_maxMembers)
+ .map((m) => GroupMember.tryParse(m, now: now))
+ .whereType<GroupMember>()
+ .toList()
+ : const [],
+ removed is List
+ ? removed
+ .take(_maxTombstones)
+ .map((t) => GroupTombstone.tryParse(t, now: now))
+ .whereType<GroupTombstone>()
+ .toList()
+ : const [],
+ );
+ }
+
+ Map<String, Object> toJson() => {
+ 'members': [for (final m in members) m.toJson()],
+ 'removed': [for (final t in removed) t.toJson()],
+ };
+}
+
+class GroupMerge {
+ const GroupMerge(this.roster, this.upserted, this.dropped);
+ final GroupRoster roster;
+ final List<GroupMember> upserted;
+ final List<GroupMember> dropped;
+}
+
+/// trustGroup.ts `mergeRoster`, line for line: the newest entry for a key wins, a tombstone beats
+/// every entry it is not older than, and a device never takes itself in.
+GroupMerge mergeGroupRoster(
+ GroupRoster local,
+ GroupRoster incoming,
+ String selfPub,
+) {
+ final tombs = <String, int>{};
+ for (final t in [...local.removed, ...incoming.removed]) {
+ if (t.pub == selfPub) continue;
+ final prev = tombs[t.pub];
+ tombs[t.pub] = prev == null || t.at > prev ? t.at : prev;
+ }
+ final members = <String, GroupMember>{
+ for (final m in local.members)
+ if (m.pub != selfPub) m.pub: m,
+ };
+ final before = Map.of(members);
+ for (final m in incoming.members) {
+ if (m.pub == selfPub) continue;
+ final existing = members[m.pub];
+ if (existing == null || m.at > existing.at) members[m.pub] = m;
+ }
+ final dropped = <GroupMember>[];
+ for (final pub in [...members.keys]) {
+ final tomb = tombs[pub];
+ if (tomb != null && tomb >= members[pub]!.at) {
+ members.remove(pub);
+ if (before[pub] case final prev?) dropped.add(prev);
+ }
+ }
+ final removed = [
+ for (final e in tombs.entries) GroupTombstone(e.key, e.value),
+ ]..sort((a, b) => b.at.compareTo(a.at));
+ final kept = members.values.toList()..sort((a, b) => b.at.compareTo(a.at));
+ final roster = GroupRoster(
+ kept.take(_maxMembers).toList(),
+ removed.take(_maxTombstones).toList(),
+ );
+ final upserted = [
+ for (final m in roster.members)
+ if (before[m.pub] == null || !before[m.pub]!.sameAs(m)) m,
+ ];
+ return GroupMerge(roster, upserted, dropped);
+}
+
+/// One roster swap with a machine, as the app calls it — `DirectLink.syncGroup`.
+typedef GroupSync = Future<GroupSyncOutcome> Function(
+ String machineId, {
+ required String label,
+});
+
+/// What one exchange changed on this phone.
+class GroupSyncOutcome {
+ const GroupSyncOutcome({this.pinned = const [], this.unpinned = const []});
+ static const none = GroupSyncOutcome();
+
+ /// Machines this phone can now reach without their password.
+ final List<String> pinned;
+
+ /// Machines the group removed; this phone no longer dials them.
+ final List<String> unpinned;
+
+ bool get changed => pinned.isNotEmpty || unpinned.isNotEmpty;
+}
+
+/// Swaps rosters with one machine over a short-lived sealed session of its own, then pins what it
+/// learned. Never throws: a machine that is offline, too old to answer or refuses leaves everything
+/// as it was.
+Future<GroupSyncOutcome> syncTrustGroup({
+ required String machineId,
+ required ViewerKeyStore keys,
+ required String accessToken,
+ required String wsBaseUrl,
+ required String autonomousEnv,
+ required String label,
+ RelaySocketFactory socket = defaultRelaySocket,
+ Duration timeout = const Duration(seconds: 20),
+}) async {
+ WebSocketChannel? channel;
+ try {
+ final pin = await keys.peer(machineId);
+ if (pin == null) return GroupSyncOutcome.none;
+ final identity = await keys.identity();
+ final selfPub = b64e(identity.pub);
+ final local = await _seeded(keys, selfPub);
+ final self = GroupMember(
+ pub: selfPub,
+ kind: 'viewer',
+ label: label,
+ at: groupSelfStamp,
+ );
+ final crypto = await RelaySessionCrypto.start(
+ machineId: machineId,
+ identity: identity,
+ peerPub: pin.pub,
+ );
+ final uri = Uri.parse('$wsBaseUrl/api/web-ws')
+ .replace(queryParameters: {'autonomousEnv': autonomousEnv});
+ final ch = channel = socket(uri, [accessToken]);
+ final reply = await () async {
+ await ch.ready;
+ return _exchange(ch, crypto, machineId, {
+ 'requestId': b64e(secureRandomBytes(12)),
+ 'self': self.toJson(),
+ ...local.toJson(),
+ });
+ }().timeout(timeout, onTimeout: () => null);
+ if (reply == null || reply['error'] != null) return GroupSyncOutcome.none;
+
+ final incoming = GroupRoster.parse(reply);
+ final theirs = GroupMember.tryParse(reply['self']);
+ // The machine may describe only itself, as the key this phone dialed and verified.
+ final members = [
+ ...incoming.members,
+ if (theirs != null &&
+ theirs.machineId == machineId &&
+ theirs.pub == b64e(pin.pub))
+ theirs,
+ ];
+ final merged = mergeGroupRoster(
+ local,
+ GroupRoster(members, incoming.removed),
+ selfPub,
+ );
+ await keys.writeGroupRoster(merged.roster.toJson());
+ return await _apply(keys, merged);
+ } catch (_) {
+ return GroupSyncOutcome.none;
+ } finally {
+ if (channel != null) unawaited(channel.sink.close());
+ }
+}
+
+/// This phone's roster, with every machine it has pinned folded in — how a machine this phone linked
+/// by password reaches the rest of the group, and how links made before the group existed join it.
+Future<GroupRoster> _seeded(ViewerKeyStore keys, String selfPub) async {
+ final stored = GroupRoster.parse(await keys.groupRoster());
+ // Only pins the roster does not name yet: a pin's `linkedAt` is when THIS device pinned it (the
+ // group's own pins included), and folding that in again would restamp the member as new on every
+ // swap and push the change around the whole group.
+ final known = {for (final m in stored.members) m.pub};
+ final pins = [
+ for (final p in await keys.peers())
+ if (!known.contains(b64e(p.pub)))
+ ?GroupMember.tryParse({
+ 'pub': b64e(p.pub),
+ 'machineId': p.machineId,
+ 'kind': 'machine',
+ 'label': p.label.isEmpty ? p.machineId : p.label,
+ 'at': p.linkedAt.millisecondsSinceEpoch,
+ }),
+ ];
+ return mergeGroupRoster(stored, GroupRoster(pins, const []), selfPub).roster;
+}
+
+Future<GroupSyncOutcome> _apply(ViewerKeyStore keys, GroupMerge merged) async {
+ final pinned = <String>[], unpinned = <String>[];
+ for (final m in merged.upserted) {
+ final id = m.machineId;
+ if (!m.isMachine || id == null) continue;
+ final current = await keys.peer(id);
+ if (current != null && b64e(current.pub) == m.pub) continue;
+ await keys.pin(id, b64d(m.pub), label: m.label);
+ pinned.add(id);
+ }
+ for (final m in merged.dropped) {
+ final id = m.machineId;
+ if (id == null) continue;
+ final current = await keys.peer(id);
+ if (current == null || b64e(current.pub) != m.pub) continue;
+ if (await keys.unlink(id)) unpinned.add(id);
+ }
+ return GroupSyncOutcome(pinned: pinned, unpinned: unpinned);
+}
+
+/// select → hello/welcome → one sealed `group_sync` → its sealed `_result`.
+Future<Map<String, dynamic>?> _exchange(
+ WebSocketChannel channel,
+ RelaySessionCrypto crypto,
+ String machineId,
+ Map<String, Object?> request,
+) async {
+ void send(Map<String, dynamic> frame) => channel.sink.add(jsonEncode(frame));
+ send({
+ 'type': 'machine_select',
+ 'payload': {'machineId': machineId},
+ });
+ var selected = false;
+ await for (final raw in channel.stream) {
+ final frame = raw is String ? jsonObjectOf(utf8Bytes(raw)) : null;
+ if (frame == null) continue;
+ final type = frame['type'];
+ final payload = frame['payload'];
+ if (!selected) {
+ if (type == 'connected' &&
+ payload is Map &&
+ payload['machineId'] == machineId) {
+ selected = true;
+ send(crypto.helloFrame());
+ } else if (type == 'machine_select_error') {
+ return null;
+ }
+ continue;
+ }
+ if (type == 'e2e_denied') return null;
+ if (type == 'e2e_welcome' && payload is Map<String, dynamic>) {
+ if (!await crypto.handleWelcome(payload)) return null;
+ send(crypto.wrapOutgoing({'type': 'group_sync', 'payload': request}));
+ continue;
+ }
+ if (type == 'group_sync_result') {
+ final opened = crypto.unwrapIncoming(frame);
+ final body = opened?['payload'];
+ if (body is Map<String, dynamic> &&
+ body['requestId'] == request['requestId']) {
+ return body;
+ }
+ }
+ }
+ return null;
+}
+
+bool _isPub(Object? v) {
+ if (v is! String || v.length > 64) return false;
+ try {
+ return b64d(v).length == 32;
+ } on FormatException {
+ return false;
+ }
+}
+
+bool _isStamp(Object? v, DateTime now) =>
+ v is int && v > 0 && v <= now.add(_maxClockSkew).millisecondsSinceEpoch;
+
+String? _cleanLabel(Object? v) {
+ if (v is! String) return null;
+ final label = v
+ .replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ')
+ .replaceAll(RegExp(r'\s+'), ' ')
+ .trim();
+ if (label.isEmpty) return null;
+ return label.length > 60 ? label.substring(0, 60) : label;
+}
diff --git a/mobile/lib/viewer/password_link.dart b/mobile/lib/viewer/password_link.dart
index 70850d4e3..7e0730356 100644
--- a/mobile/lib/viewer/password_link.dart
+++ b/mobile/lib/viewer/password_link.dart
@@ -252,6 +252,9 @@ class _PasswordLinkRun {
'id': b64e(identity.pub),
'sig': b64e(await pairBindSig(identity, transcript)),
if (label case final label? when label.trim().isNotEmpty) 'label': label,
+ // A viewer, not a machine: it dials out and is never dialed, so the machine trusts it and
+ // does not pin it back. A machine that predates the field ignores it.
+ 'kind': 'viewer',
});
_send('e2e_pw_pake', {
'sid': _sidB64,
diff --git a/mobile/lib/viewer/viewer_key_store.dart b/mobile/lib/viewer/viewer_key_store.dart
index 317d4f527..1f73732f3 100644
--- a/mobile/lib/viewer/viewer_key_store.dart
+++ b/mobile/lib/viewer/viewer_key_store.dart
@@ -77,6 +77,7 @@ class ViewerKeyStore {
static const _seedKey = 'viewer_e2ee_identity_seed';
static const _peersKey = 'viewer_e2ee_machine_peers';
+ static const _groupKey = 'viewer_e2ee_group';
/// Minted on first use and kept: every linked machine has pinned it.
Future<E2eeIdentity> identity() => _identity ??= _heldUnlessItFails(
@@ -165,6 +166,21 @@ class ViewerKeyStore {
return true;
}
+ /// The trust group as this phone last knew it (`group_sync.dart`), as stored JSON; null when
+ /// there is none yet or it cannot be read.
+ Future<Object?> groupRoster() async {
+ final raw = await _storage.read(_groupKey);
+ if (raw == null) return null;
+ try {
+ return jsonDecode(raw);
+ } on FormatException {
+ return null;
+ }
+ }
+
+ Future<void> writeGroupRoster(Map<String, Object> roster) =>
+ _storage.write(_groupKey, jsonEncode(roster));
+
/// The one path that changes the peer list, so the one place the cache is
/// replaced.
///
diff --git a/mobile/test/viewer/group_sync_test.dart b/mobile/test/viewer/group_sync_test.dart
new file mode 100644
index 000000000..4967e86dc
--- /dev/null
+++ b/mobile/test/viewer/group_sync_test.dart
@@ -0,0 +1,303 @@
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:harness_mobile/e2ee/bytes.dart';
+import 'package:harness_mobile/e2ee/keys.dart';
+import 'package:harness_mobile/viewer/group_sync.dart';
+import 'package:harness_mobile/viewer/viewer_key_store.dart';
+
+import '../e2ee/machine_session.dart' as ms;
+import '../voice_fakes.dart' show MemoryKeyValueStore;
+import 'fake_relay_socket.dart';
+
+final _b = 'b' * 32;
+final _c = 'c' * 32;
+
+Future<String> _pub() async => b64e((await E2eeIdentity.generate()).pub);
+
+GroupMember _machine(String pub, String id, int at) => GroupMember(
+ pub: pub,
+ kind: 'machine',
+ label: id.substring(0, 1),
+ at: at,
+ machineId: id,
+);
+
+/// A machine answering one roster swap: it acks the select, answers the hello with a real
+/// welcome, opens the sealed `group_sync` and replies with [reply] sealed back.
+FakeRelaySocket _machineSocket(
+ E2eeIdentity machine,
+ Map<String, Object?> Function(Map<String, dynamic> request) reply, {
+ void Function(Map<String, dynamic> request)? onRequest,
+}) {
+ late FakeRelaySocket socket;
+ ms.MachineSession? session;
+ socket = FakeRelaySocket(
+ onFrame: (frame) async {
+ switch (frame['type']) {
+ case 'machine_select':
+ socket.emit('connected', {'machineId': ms.machineId});
+ case 'e2e_hello':
+ session = await ms.MachineSession.answer(frame, identity: machine);
+ socket.emit('e2e_welcome', await session!.welcome());
+ case 'group_sync':
+ final request = session!.openDown(frame)!;
+ onRequest?.call(request);
+ final sealed = session!.target('group_sync_result', {
+ 'requestId': request['requestId'],
+ ...reply(request),
+ });
+ socket.emitRaw(jsonEncode(sealed));
+ }
+ },
+ );
+ return socket;
+}
+
+void main() {
+ group('mergeGroupRoster', () {
+ test(
+ 'takes new members, the newest entry per key, and never itself',
+ () async {
+ final self = await _pub();
+ final b = _machine(await _pub(), _b, 10);
+ final renamed = GroupMember(
+ pub: b.pub,
+ kind: 'machine',
+ label: 'B2',
+ at: 20,
+ machineId: _b,
+ );
+ final r1 = mergeGroupRoster(
+ GroupRoster.empty,
+ GroupRoster([
+ b,
+ GroupMember(pub: self, kind: 'viewer', label: 'me', at: 5),
+ ], const []),
+ self,
+ );
+ expect(r1.roster.members.map((m) => m.pub), [b.pub]);
+ expect(r1.upserted.single.pub, b.pub);
+ final r2 = mergeGroupRoster(
+ r1.roster,
+ GroupRoster([renamed], const []),
+ self,
+ );
+ expect(r2.roster.members.single.label, 'B2');
+ final r3 = mergeGroupRoster(
+ r2.roster,
+ GroupRoster([b], const []),
+ self,
+ );
+ expect(r3.upserted, isEmpty);
+ },
+ );
+
+ test('a tombstone beats what it is not older than; a newer link beats the tombstone', () async {
+ final self = await _pub();
+ final b = _machine(await _pub(), _b, 10);
+ final removed = mergeGroupRoster(
+ GroupRoster([b], const []),
+ GroupRoster(const [], [GroupTombstone(b.pub, 10)]),
+ self,
+ );
+ expect(removed.roster.members, isEmpty);
+ expect(removed.dropped.single.pub, b.pub);
+ final relinked = mergeGroupRoster(
+ removed.roster,
+ GroupRoster([_machine(b.pub, _b, 11)], const []),
+ self,
+ );
+ expect(relinked.roster.members.single.at, 11);
+ });
+
+ test('parse drops malformed entries: a machine needs its id', () async {
+ final good = _machine(await _pub(), _b, 1).toJson();
+ final roster = GroupRoster.parse({
+ 'members': [
+ good,
+ {...good, 'machineId': 'nope'},
+ {...good, 'pub': 'x'},
+ {...good, 'kind': 'server'},
+ ],
+ 'removed': [
+ {'pub': good['pub'], 'at': 1},
+ {'pub': 'x', 'at': 1},
+ ],
+ });
+ expect(roster.members, hasLength(1));
+ expect(roster.removed, hasLength(1));
+ });
+ });
+
+ group('syncTrustGroup', () {
+ test('sends this phone and every machine it pinned, sealed; pins every machine it learns', () async {
+ final keys = ViewerKeyStore(storage: MemoryKeyValueStore());
+ final machine = await E2eeIdentity.generate();
+ final bPub = await _pub();
+ final cPub = await _pub();
+ await keys.pin(ms.machineId, machine.pub);
+ await keys.pin(_b, b64d(bPub), label: 'b');
+ Map<String, dynamic>? seen;
+ final socket = _machineSocket(
+ machine,
+ (_) => {
+ 'members': [_machine(cPub, _c, 50).toJson()],
+ 'removed': [],
+ },
+ onRequest: (r) => seen = r,
+ );
+
+ final outcome = await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: "Dee's iPhone",
+ socket: socket.factory,
+ );
+
+ // What left the phone went sealed (the machine could open it) and said who the phone is.
+ final groupFrame = socket.sent.firstWhere(
+ (f) => f['type'] == 'group_sync',
+ );
+ expect((groupFrame['payload'] as Map).containsKey('__e2e'), isTrue);
+ expect(seen!['self'], containsPair('kind', 'viewer'));
+ expect(seen!['self'], containsPair('label', "Dee's iPhone"));
+ final sentMembers = (seen!['members'] as List).cast<Map>();
+ expect(sentMembers.map((m) => m['machineId']), contains(_b));
+
+ expect(outcome.pinned, [_c]);
+ expect(b64e((await keys.peer(_c))!.pub), cPub);
+ expect(socket.closedByPhone, isTrue);
+ });
+
+ test(
+ 'a pin the roster already names is not restamped by re-pinning',
+ () async {
+ final keys = ViewerKeyStore(storage: MemoryKeyValueStore());
+ final machine = await E2eeIdentity.generate();
+ final bPub = await _pub();
+ await keys.pin(ms.machineId, machine.pub);
+ await keys.pin(_b, b64d(bPub), label: 'b');
+ final sent = <int>[];
+ Future<void> swap() async {
+ final socket = _machineSocket(
+ machine,
+ (_) => {'members': [], 'removed': []},
+ onRequest: (r) => sent.add(
+ ((r['members'] as List).cast<Map>().firstWhere(
+ (m) => m['machineId'] == _b,
+ ))['at']
+ as int,
+ ),
+ );
+ await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'p',
+ socket: socket.factory,
+ );
+ }
+
+ await swap();
+ await Future<void>.delayed(const Duration(milliseconds: 5));
+ await keys.pin(
+ _b,
+ b64d(bPub),
+ label: 'b',
+ ); // what the group's own pin does
+ await swap();
+ expect(sent, hasLength(2));
+ expect(sent[1], sent[0]);
+ },
+ );
+
+ test('a member the group removed is unpinned', () async {
+ final keys = ViewerKeyStore(storage: MemoryKeyValueStore());
+ final machine = await E2eeIdentity.generate();
+ final cPub = await _pub();
+ await keys.pin(ms.machineId, machine.pub);
+ await keys.pin(_c, b64d(cPub));
+ final socket = _machineSocket(
+ machine,
+ (_) => {
+ 'members': [],
+ 'removed': [
+ {'pub': cPub, 'at': DateTime.now().millisecondsSinceEpoch},
+ ],
+ },
+ );
+ final outcome = await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'p',
+ socket: socket.factory,
+ );
+ expect(outcome.unpinned, [_c]);
+ expect(await keys.peer(_c), isNull);
+ });
+
+ test(
+ 'a machine that is not linked, refuses, or never answers changes nothing',
+ () async {
+ final keys = ViewerKeyStore(storage: MemoryKeyValueStore());
+ expect(
+ (await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'p',
+ socket: FakeRelaySocket().factory,
+ )).changed,
+ isFalse,
+ );
+
+ final machine = await E2eeIdentity.generate();
+ await keys.pin(ms.machineId, machine.pub);
+ late FakeRelaySocket denied;
+ denied = FakeRelaySocket(
+ onFrame: (frame) {
+ if (frame['type'] == 'machine_select')
+ denied.emit('connected', {'machineId': ms.machineId});
+ if (frame['type'] == 'e2e_hello')
+ denied.emit('e2e_denied', {'reason': 'unpaired'});
+ },
+ );
+ final refused = await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'p',
+ socket: denied.factory,
+ );
+ expect(refused.changed, isFalse);
+
+ final silent = await syncTrustGroup(
+ machineId: ms.machineId,
+ keys: keys,
+ accessToken: 't',
+ wsBaseUrl: 'wss://relay.test',
+ autonomousEnv: 'prod',
+ label: 'p',
+ socket: FakeRelaySocket().factory,
+ timeout: const Duration(milliseconds: 50),
+ );
+ expect(silent.changed, isFalse);
+ expect(await keys.peer(ms.machineId), isNotNull);
+ },
+ );
+ });
+}