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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* Shared tabs across accounts (docs/superpowers/specs/2026-10-15-agent-messages-across-accounts-design.md, "Trust: the
* signed roster" and "Messages across accounts"): who is in a tab shared with other accounts, how that changes, and the
* sealed requests Agent Messages sends another account's machine through the tab (`request`), which the service answers
* on the other side (`answer`, service.ts) against its own roster.
*
* The owner's computer is the only authority over a shared tab (the spec's "Authority"). It builds the roster from
* its desk's panes and the members the backend says accepted, signs it with its machine key, stores it on the backend
* and sends it to the tab's other machines. The backend is a mailbox and a relay: it keeps the invitations, the latest
* signed roster and who accepted, and carries sealed frames between machines without reading them. A member's add or
* remove is a request, which the owner's computer checks and applies, and which waits while that computer is away.
*
* Frames between machines go over the tab's relay (`TabRelay`). In the clear, only what opens a session
* (`TabKey`, lib/e2ee/tabSession.ts), each with its `kind`:
* { kind: 'hello', hello, pub } the lower machine id starts a session; `pub` is its key, which only the owner's
* computer may take, for a member's machine the roster does not list yet
* { kind: 'welcome', welcome, to } the answer; `to` names the hello it answers (its ephemeral key), so a late
* welcome for an older hello is ignored instead of spending the current one
* { kind: 'knock', pub } the higher id asks the lower to start one, or either says it has none
* Everything else is sealed for the session (`{ __e2e }`), and once opened is one of:
* { kind: 'roster', signed } the owner's roster (a SignedRoster)
* { kind: 'roster_request', id, op, harness } a member asks to add or remove its harness; `id` is
* `<op>:<machineId>/<agentId>`, the same for the same ask
* { kind: 'roster_refused', id, error } the owner's answer to a request it will not apply
* { kind: 'agent_messages', rid, action, ... } an Agent Messages request from any machine of the tab to any
* other (`deliver`, `status`, `who`), for its service to answer;
* `rid` names it, 24 hex characters (tabDelivery.ts)
* { kind: 'agent_messages_result', rid, ... } the answer, sealed back to the machine that asked: what the
* service answered, or `{ error, detail }` for its refusal
* Each is checked as it arrives: anything else, or anything malformed, is dropped. A result is taken only from the
* machine its request went to, in the tab it went through.
*
* A member's other computers take the tab from the one that accepted it, over the account's paired relay (service.ts
* `tab_pin`, `tab_pin_changed`): the owner key it pinned and the roster it holds, which they check as their own.
*
* The owner stops a tab from any of its computers, and moves its authority to another (`move`): the new computer asks
* the old one, over the paired relay, to sign its key for the tab (`tab_keychange`), and signs the next roster with that
* change attached, which members' pins follow (roster.ts `verifyRoster`). With the old computer away there is no change
* to attach: members cannot verify the new roster and trust its owner again (`retrust`), each computer on its own word.
*/
import { randomBytes } from 'node:crypto'
import type { TabFrame, TabKey, TabLink, TabRelay } from '../core/api.js'
import { b64d, fingerprint, verify } from '../lib/e2ee/core.js'
import { MessageError } from './model.js'
import { NoticeStore } from './noticeStore.js'
import type { QueuedRequest, RequestStore } from './requestStore.js'
import { cleanName, encodeRoster, fitsRoster, keyChangeBytes, parseRoster, ROSTER_LIMITS, verifyRoster, type KeyChange, type Roster, type RosterHarness, type SignedRoster } from './roster.js'
import type { ConsentStore } from './consentStore.js'
import type { RosterStore } from './rosterStore.js'
import { composeCut, harnessRef, judge, peerKey, PUB, record, same, sameRoster, sharedTabIdOf, shareOf, signedOf, UNNAMED, wireHarness, type ShareView } from './sharedTabsRoster.js'
import { fitsRequest, REQUEST_ID_LENGTH, type TabContext } from './tabDelivery.js'
/** How often a member's waiting request is tried again, with the shares read again, while the owner's computer is away. */
export const RETRY_MS = 30_000
/** How long a hello or a knock with no answer is left before another: a hello sent again on every try would replace
* the one whose welcome is on its way. */
export const HELLO_RETRY_MS = 10_000
/** How long a member's computer that could not take a tab's pin from another of its account's waits before asking
* again: every `desk_changed`, and every 30 s retry, reads the shares, and a computer whose others are asleep would
* otherwise ask them all each time. The one that accepts says when to ask at once (`pinChanged`). */
export const PULL_RETRY_MS = 60_000
/** How long a tab's relay waits to be opened again after another socket of this machine took it over (4409): opened
* again at once, it would take the tab back from that socket, which would take it back in turn, and so on. Long
* enough for a socket that was only replacing this one (a gateway that restarted) to have settled. */
export const RELAY_TAKEOVER_MS = 30_000
/** Taken over more than RELAY_TAKEOVERS times within RELAY_TAKEOVER_WINDOW_MS, the relay is not opened again: something
* else of this machine keeps wanting the tab (a second daemon under the same machine id), and the person is told
* (`relay_taken`) rather than have the two take it from each other for good. */
export const RELAY_TAKEOVERS = 3
export const RELAY_TAKEOVER_WINDOW_MS = 10 * 60_000
/** After accepting, the shares are read this many times more, ACCEPT_RETRY_MS apart, while they cannot be read or do not
* list the tab yet: a backend that blinked once would otherwise have the person leave a tab they just joined. */
export const ACCEPT_RETRIES = 3
export const ACCEPT_RETRY_MS = 1_000
/** The most `roster_request`s the owner takes from one member account in REQUEST_WINDOW_MS (the spec's "Limits", as
* for messages): each one may sign and send a roster, which a member's daemon could otherwise ask for without end. */
export const REQUESTS_PER_MEMBER = 30
export const REQUEST_WINDOW_MS = 10 * 60_000
type Wire = Record<string, unknown>
type Me = { machineId: string; accountId: string; email: string }
type Pane = { machineId: string; agentId: string; name: string; engine: string }
export interface SharedTabsDeps {
key: TabKey
relay: TabRelay
store: RosterStore
backend(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }>
/** This machine and the account signed in on it. */
self(): Promise<Me>
/** The owner's own panes in a desk tab, with each harness's name and engine, from the account's directory; null when
* the directory cannot be read, so that a roster never loses the owner's harnesses to a failed read. */
ownPanes(tabId: string): Promise<Pane[] | null>
/** The leader the account's tab setting names for a desk tab, from its directory: null for none, or one that may lead it
* no more. Undefined when it is not known: the directory not read yet (a failed read keeps the last good listing), or
* a backend that lists no leaders; the roster then keeps its own. Unset, a roster keeps its own leader too. */
ownLeader?(tabId: string): Promise<{ machineId: string; agentId: string } | null | undefined>
/** This account's machines' identity keys, by machine id, each as that machine reports it; null when it cannot be asked. */
machineKey(machineId: string): Promise<string | null>
/** An `agent_messages` request to another machine of this account, over the paired relay: its answer;
* `{ error: { code, message } }` when it answered with a refusal; null when it could not be asked. */
askMachine(machineId: string, payload: Record<string, unknown>): Promise<Record<string, unknown> | null>
/** This account's machine ids, from its directory; null when it cannot be read. */
ownMachines(): Promise<string[] | null>
/** Where the member's queued requests are kept, so a restart does not drop them; unset, they live in memory only. */
requests?: RequestStore
/** The harnesses this account asked to have in a tab, from this machine (consentStore.ts): only those are watched by the
* tab's other accounts. Unset, nothing is recorded, and Share grants no member harness here a view. */
consent?: ConsentStore
/** What the directory merges in may have changed: a roster taken, a tab left, or the shares read (service.ts
* rebuilds the directory, which tells deliveries and notes only of a real change). */
changed?(): void
/** An Agent Messages request another machine of the tab sent (`agent_messages`), with the tab and who the relay says
* sent it: its answer is sealed back. Unset, every request is answered as an unknown one. */
answer?(ctx: TabContext, payload: Record<string, unknown>): Promise<Record<string, unknown>>
/** A session with a machine of the tab just opened: what waits for that machine can go now (service.ts hands its
* outbox over), rather than at its next try. */
opened?(sharedTabId: string, machineId: string): void
/** What the windows show changed: a notice, a waiting request, or the invitations or untrusted tabs a refresh read
* (service.ts tells them `shared_tabs_changed`). */
announce?(): void
/** Where notices are kept until dismissed; unset, they are kept in memory only, and gone with the process. */
notices?: NoticeStore
now?(): number
}
/** The owner's email as a notice carries it: control and format characters out, at most 254. */
const ownerEmailOf = (roster: Roster): string => cleanName(roster.owner.email).slice(0, 254)
export interface SharedNotice { id: string; sharedTabId: string; kind: 'refused' | 'removed' | 'relay_taken' | 'full' | 'unsent'; at: string; error?: string; machineId?: string; agentId?: string
/** The tab owner's email (cleaned, at most 254), for `removed` and `relay_taken`: the roster is gone by the time a window shows them. */
ownerEmail?: string }
interface Link extends TabLink { userId: string; state: 'hello' | 'knock' | 'open' | 'idle'; at: number; hello?: string }
interface Request { sharedTabId: string; id: string; op: 'add' | 'remove'; harness: RosterHarness; since: number }
const requestId = (op: Request['op'], h: Pick<RosterHarness, 'machineId' | 'agentId'>) => `${op}:${h.machineId}/${h.agentId}`
const requestOf = (q: QueuedRequest): Request => ({ ...q, id: requestId(q.op, q.harness) })
const unavailable = () => new MessageError('SHARES_UNAVAILABLE', 'Harness could not read the shared tabs. Try again in a moment.')
const invalid = () => new MessageError('INVALID_HARNESS', 'Name a harness by its machine, agent, name and engine.')
const rosterInvalid = () => new MessageError('ROSTER_INVALID', 'The shared tab\'s roster could not be verified. Try again in a moment.')
const notOwner = () => new MessageError('NOT_OWNER', 'Only the computer that shares this tab can change it.')
const shareIdMismatch = () => new MessageError('SHARE_ID_MISMATCH', 'The backend named the shared tab otherwise than Harness expects, so this computer did not sign for it.')
const notOwnAccount = () => new MessageError('NOT_OWNER', 'Only the account that shares this tab can stop it or move it.')
const peerAway = () => new MessageError('PEER_AWAY', 'That computer cannot be reached through the shared tab right now.')
const rosterPath = (tabId: string) => `/api/agent-messages/shares/${encodeURIComponent(tabId)}/roster`
const memberPath = (id: string, accountId: string) => `/api/agent-messages/shares/${id}/members/${encodeURIComponent(accountId)}`
const ignore = (): void => {}
const linkOf = (l: Link): TabLink => ({ sharedTabId: l.sharedTabId, machineId: l.machineId, peerPub: l.peerPub })
type Reply = { status: number; body: Record<string, unknown> }
const unsupported = () => new MessageError('SHARED_TABS_UNSUPPORTED', 'Shared tabs need a newer Harness service; nothing was shared.')
/** A route the backend does not have: a backend from before shared tabs answers every one of theirs 404 with Fastify's own
* body, no code of ours. A 404 with a code (`NOT_FOUND`, an invitation gone) is the route's answer, told as it said it.
* Said as BACKEND_UNAVAILABLE, "try again in a moment" never came true until that backend was updated. */
const missing = (reply: Reply): boolean => reply.status === 404 && typeof record(reply.body.error)?.code !== 'string'
/** What a route answered, or the error it gave, as it said it. */
const dataOf = (reply: Reply): Wire => {
const data = record(reply.body.data)
if (reply.status === 200 && reply.body.success === true && data) return data
if (missing(reply)) throw unsupported()
const error = record(reply.body.error)
throw typeof error?.code === 'string' ? new MessageError(error.code, String(error.message))
: new MessageError('BACKEND_UNAVAILABLE', 'Harness could not reach the backend. Try again in a moment.')
}
/** The version the backend holds, when it refused a roster for not being newer; null for any other answer. */
const staleAt = (reply: Reply): number | null => {
const error = record(reply.body.error)
return error?.code === 'STALE_ROSTER' && typeof error.version === 'number' ? error.version : null
}
export class SharedTabs {
private readonly links = new Map<string, Link>()
private readonly queue = new Map<string, Request>()
/** The tabs this computer shares: the desk tab the roster is put under, the version the backend holds, and the old
* computer's signed change to this one's key when the tab moved here (`move`), attached to every roster from then on. */
private readonly owned = new Map<string, { tabId: string; floor: number; keyChange?: KeyChange }>()
/** The desk tab each of this account's shares is shared from, as the shares list it: on every computer of the account,
* not only the one that shares it, whose harnesses in that tab are teammates of the members' too (`deskTab`). */
private readonly desks = new Map<string, string>()
private readonly noticed: NoticeStore
/** The machines `checkOwn` looked at, for the version of each tab it last looked at: a roster is checked once. */
private readonly checked = new Map<string, { version: number; machines: Set<string> }>()
/** When this computer last began, or failed, to take each tab's pin from another of its account's (`pull`). */
private readonly pulled = new Map<string, number>()
/** When this computer last asked for the key of the computer its account's tab moved to (`follow`). */
private readonly followed = new Map<string, number>()
/** Each tab's relay taken over (4409): when, within the last RELAY_TAKEOVER_WINDOW_MS; the wait to open it again; and
* whether it is opened no more. While it waits or has stopped, nothing opens it (`openRelay`). */
private readonly takeovers = new Map<string, { at: number[]; timer: ReturnType<typeof setTimeout> | null; stopped: boolean }>()
/** When each member account's `roster_request`s came, within the last REQUEST_WINDOW_MS (`apply`). */
private readonly requestsFrom = new Map<string, number[]>()
/** The Agent Messages requests this computer sent and waits on (`request`), by their `rid`. */
private readonly asking = new Map<string, { sharedTabId: string; machineId: string; timer: ReturnType<typeof setTimeout>;
resolve(reply: Wire): void; reject(error: Error): void }>()
/** The request file could not be read (`restore`): nothing is written to it until it is, which the next refresh tries
* again. Requests made meanwhile wait in memory and join the file's once it reads. */
private unloaded = false
private chain: Promise<unknown> = Promise.resolve()
private timer: ReturnType<typeof setInterval> | null = null
private closed = false
private me: Me | null = null
private pub: string | null = null
private readonly now: () => number
constructor(private readonly deps: SharedTabsDeps) {
this.now = deps.now ?? Date.now
this.noticed = deps.notices ?? new NoticeStore(null, this.now)
this.restore()
}
/**
* Takes back the requests a restart interrupted. Resending is safe: the owner applies a request once and answers a
* repeat with the roster it already published. A tab this computer no longer holds has nothing to ask for. Whose
* machine each request names is known only once `self` is read, so that check follows: only the harness's own machine
* sends an add, so an add naming another machine is dropped. A remove may come from any machine of the account
* (`judge`), so removes stay.
*
* A file that cannot be read at all leaves the queue as it is in memory and marks it unloaded (`persist` then writes
* nothing): writing what is in memory would put an empty or partial queue over the requests the file still holds.
* Read later (`refresh`), the file's requests join those made meanwhile, which win for the same harness, and the
* whole is written down.
*/
private restore(): void {
const store = this.deps.requests
if (!store) return
let loaded: QueuedRequest[]
try { loaded = store.load() } catch { this.unloaded = true; return }
const retried = this.unloaded
this.unloaded = false
for (const q of loaded) {
const held = this.deps.store.current(q.sharedTabId)?.roster
if (!held) continue
const r = requestOf(q)
// Already settled: the owner applied it and this computer saved that roster before the queue was written down,
// and the owner's repeat answer would be that same roster, which `adopt` never sees again. Same test as `adopt`.
if (held.harnesses.some((h) => same(h, r.harness)) === (r.op === 'add')) continue
// On a load retried after a failed one, what the person asked since is newer than the file: a request in memory
// for the same harness, the same op or its opposite, wins, as `enqueue` lets only the latest word stand. Left to
// both be sent, the order they arrived in would decide, and a remove asked after the add could lose (review of A7).
const opposite = `${r.sharedTabId}:${requestId(r.op === 'add' ? 'remove' : 'add', r.harness)}`
if (this.queue.has(`${r.sharedTabId}:${r.id}`) || this.queue.has(opposite)) continue
this.queue.set(`${r.sharedTabId}:${r.id}`, r)
}
if (retried || this.queue.size !== loaded.length) this.persist()
this.timed()
void this.self().then((me) => {
let dropped = false
for (const [k, r] of this.queue) if (r.op === 'add' && r.harness.machineId !== me.machineId) { this.queue.delete(k); dropped = true }
if (dropped) { this.persist(); this.timed() }
}).catch(ignore)
}
/** Writes the queue down after every change. A disk that refuses costs only the restart's memory of it. */
private persist(): void {
if (this.unloaded) return
try { this.deps.requests?.save([...this.queue.values()].map(({ sharedTabId, op, harness, since }) => ({ sharedTabId, op, harness, since }))) } catch { /* the queue still works in memory */ }
this.deps.announce?.()
}
/** One thing at a time: two changes that each read the roster and raise its version would put the same version twice. */
private serial<T>(work: () => Promise<T>): Promise<T> {
const run = this.chain.then(work)
this.chain = run.catch(ignore)
return run
}
private async self(): Promise<Me> { return this.me ??= await this.deps.self() }
private async myPub(): Promise<string> { return this.pub ??= await this.deps.key.publicKey() }
private async owns(roster: Roster): Promise<boolean> { return roster.owner.machineId === (await this.self()).machineId }
private async call(method: string, path: string, body?: unknown): Promise<Wire> {
return dataOf(await this.deps.backend(method, path, body))
}
/** The shares as the backend lists them; null when they cannot be read now. A backend without the route says so
* (SHARED_TABS_UNSUPPORTED) rather than "cannot be read now", which no wait would change. */
private async shares(): Promise<ShareView[] | null> {
const reply = await this.deps.backend('GET', '/api/agent-messages/shares')
if (missing(reply)) throw unsupported()
const list = reply.status === 200 && reply.body.success === true ? record(reply.body.data)?.shares : null
return Array.isArray(list) ? list.flatMap((s) => { const view = shareOf(s); return view ? [view] : [] }) : null
}
/** A socket is opened again before each use: a gateway that restarted dropped it without a word (gateway/tabRelay.ts).
* Not while a takeover waits or stopped it (`takenOver`): opened at once, it would take the tab back too soon. */
private async openRelay(id: string): Promise<boolean> {
const taken = this.takeovers.get(id)
if (this.closed || taken?.timer || taken?.stopped) return false
await this.deps.relay.open(id)
return true
}
// ── the owner ─────────────────────────────────────────────────────────────────────────────────────
/** The backend names the share (`sharedTabId`, from the owner's account and the desk tab): the first roster is put
* before the id is known, and the second carries it. The id is derived here too, and one the backend answers
* otherwise is refused: every roster from then on would be signed for a tab of the backend's choosing. */
share(tabId: string, name: string): Promise<{ sharedTabId: string }> {
return this.serial(async () => {
const me = await this.self()
const shares = await this.shares()
if (!shares) throw unavailable()
const held = shares.find((s) => s.owner && s.tabId === tabId)
if (held && held.ownerMachineId !== me.machineId) {
throw new MessageError('SHARED_ELSEWHERE', 'This tab is already shared from another of your computers. Change it there.')
}
if (held && held.sharedTabId !== sharedTabIdOf(me.accountId, tabId)) throw shareIdMismatch()
if (held) { await this.reread(shares); return { sharedTabId: held.sharedTabId } }
const own = await this.ownHarnesses(tabId, [])
const { roster: draft, cut } = composeCut(await this.empty(UNNAMED, name), { own: own ?? [], ...await this.leaderOf(tabId) })
// Version 1, or past the version a share of this tab stopped at: shared again, it carries on from there.
const first = await this.put(tabId, draft)
const sharedTabId = String(first.data.sharedTabId)
if (sharedTabId !== sharedTabIdOf(me.accountId, tabId)) throw shareIdMismatch()
this.owned.set(sharedTabId, { tabId, floor: first.roster.version })
await this.pinSelf(sharedTabId)
await this.publish({ ...draft, sharedTabId, version: first.roster.version + 1 })
if (cut) this.full(sharedTabId)
return { sharedTabId }
})
}
invite(sharedTabId: string, emails: string[], days: 7 | 30 | 90): Promise<{ invited: string[]; refused: { email: string; error: string }[] }> {
return this.serial(async () => {
const roster = await this.authority(sharedTabId)
if (![7, 30, 90].includes(days) || !Array.isArray(emails)) throw new MessageError('USAGE', 'Invite one or more addresses for 7, 30 or 90 days.')
const room = ROSTER_LIMITS.members - roster.members.length
const invited: string[] = [], refused: { email: string; error: string }[] = []
for (const [i, email] of [...new Set(emails.map((e) => String(e).trim().toLowerCase()).filter(Boolean))].entries()) {
if (i >= room) { refused.push({ email, error: 'TAB_FULL' }); continue }
try {
await this.call('POST', `/api/agent-messages/shares/${sharedTabId}/invites`, { email, days })
invited.push(email)
} catch (error) { refused.push({ email, error: (error as MessageError).code }) }
}
await this.reread(await this.shares())
return { invited, refused }
})
}
revoke(inviteId: string): Promise<void> {
return this.serial(async () => {
await this.call('DELETE', `/api/agent-messages/invites/${encodeURIComponent(inviteId)}`)
await this.reread(await this.shares())
})
}
/**
* The person chose the tab's leader, from any computer of the owner's account: written to the owner's tab setting
* (`PATCH /api/agent-messages/tabs/<tabId>`), the one source of a tab's leader, shared or not (the spec's "A leader in
* every tab"). Nothing is signed here: the backend tells every computer of the account (`desk_changed`), and the one
* that shares the tab signs its next roster with it (`reshare`), at once or when it wakes. 1c let only that computer
* change the leader, so the owner could not from a laptop while the studio slept. The backend checks that the leader
* is a harness of the tab on a machine of the account (`INVALID_LEADER`).
*/
async setLeader(sharedTabId: string, leader: { machineId: string; agentId: string } | null): Promise<void> {
const wanted = leader && harnessRef(leader)
if (leader && !wanted) throw new MessageError('INVALID_LEADER', 'Choose a harness in this tab.')
const shares = await this.shares()
if (!shares) throw unavailable()
const share = shares.find((s) => s.sharedTabId === sharedTabId && s.owner)
if (!share) throw new MessageError('NOT_OWNER', 'Only the account that shares this tab can choose its leader.')
// A share listed under an id the backend did not derive from the account and the tab names some other desk tab.
if (sharedTabId !== sharedTabIdOf((await this.self()).accountId, share.tabId)) throw shareIdMismatch()
await this.call('PATCH', `/api/agent-messages/tabs/${encodeURIComponent(share.tabId)}`, { leader: wanted })
}
removeMember(sharedTabId: string, accountId: string): Promise<void> {
return this.serial(async () => {
const roster = await this.authority(sharedTabId)
await this.call('DELETE', memberPath(sharedTabId, accountId))
await this.change(roster, { members: roster.members.filter((m) => m.accountId !== accountId) })
})
}
/**
* The owner removes any member's harness at once; a member asks the owner to remove its own. The owner's own
* harnesses are its desk's panes: one leaves when the person moves it out of the tab.
*
* A member's harness on another machine of this account is handed to that machine (`forwarded`), which takes back its
* consent (consentStore.ts) and asks the owner itself, as an add is. Taking the consent back there, at once, is what
* keeps the view away: left to the owner, one that never applied the removal would keep watching, and one that applied
* it and listed the harness again while that machine was away would be seen only listing it, never taking it out
* (review of C1, round 2). That machine away, the removal is refused, as an add is, and nothing changes: a removal
* remembered here to hand on later would need a queue and a timer of its own, for a harness nobody can watch while its
* machine is away anyway. A removal handed on for a harness not on this machine is refused, never handed on again.
*/
async removeHarness(sharedTabId: string, machineId: string, agentId: string, forwarded = false): Promise<Record<string, unknown>> {
const me = await this.self()
if (forwarded && machineId !== me.machineId) throw new MessageError('NOT_THIS_MACHINE', 'That harness is not on this machine: take it out from the machine it runs on.')
const held = this.held(sharedTabId)
if (machineId !== me.machineId && !await this.owns(held.roster)) {
const entry = held.roster.harnesses.find((h) => same(h, { machineId, agentId }))
if (!entry) throw new MessageError('NOT_IN_TAB', 'That harness is not in the tab.')
if (entry.accountId !== me.accountId) throw new MessageError('NOT_YOURS', 'Only its own person can take a harness out of the tab.')
const answer = await this.deps.askMachine(machineId, { action: 'share_remove', sharedTabId, machineId, agentId, forwarded: true })
if (!answer) throw new MessageError('MACHINE_AWAY', 'That machine could not be asked to take it out. Try again once it is on.')
const refused = record(answer.error)
if (refused) throw new MessageError(String(refused.code), String(refused.message))
return answer
}
// On the harness's own machine its consent goes first, whatever the roster held here says: the person asked.
if (machineId === me.machineId) this.deps.consent?.revoke(sharedTabId, machineId, agentId)
return this.serial(async () => {
const held = this.held(sharedTabId)
const entry = held.roster.harnesses.find((h) => same(h, { machineId, agentId }))
if (!entry) {
// Still `Joining…`: its add waits here for the owner's computer. The person withdrew it, so the add goes now
// (its consent went above), never later: applied once that computer came back, it would share a harness the
// person took back (final review of 1c, I3).
if (machineId === me.machineId && this.queue.delete(`${sharedTabId}:${requestId('add', { machineId, agentId })}`)) {
this.persist()
this.timed()
return { ok: true }
}
throw new MessageError('NOT_IN_TAB', 'That harness is not in the tab.')
}
if (await this.owns(held.roster)) {
if (entry.accountId === held.roster.owner.accountId) throw new MessageError('OWNER_PANE', 'Move it out of the tab on your desk.')
const roster = await this.authority(sharedTabId)
await this.change(roster, { others: roster.harnesses.filter((h) => !same(h, entry)) })
return { ok: true }
}
if (entry.accountId !== me.accountId) throw new MessageError('NOT_YOURS', 'Only its own person can take a harness out of the tab.')
this.enqueue(sharedTabId, 'remove', entry)
await this.flush(sharedTabId)
return { ok: true }
})
}
/** Any computer of the owner's account stops a tab, whichever one shares it: the backend checks the account, and the
* computer that shares it hears the relay close (4403). A computer that cannot reach that one still ends the share. */
stop(sharedTabId: string): Promise<void> {
return this.serial(async () => {
const shares = await this.shares()
if (!shares) throw unavailable()
if (!shares.some((s) => s.sharedTabId === sharedTabId && s.owner)) throw notOwnAccount()
await this.call('DELETE', `/api/agent-messages/shares/${sharedTabId}`)
this.drop(sharedTabId)
})
}
/**
* Moves a tab this account shares to this computer. First, best effort, the computer whose roster this one holds signs
* this one's key for the tab (`keyChange`), which lets members' pins follow; it is asked outside the queue, as an away
* machine costs an 8 s wait (`addHarness`). Then the backend takes this computer as the tab's, and only then does this
* one pin its own key and sign the next roster, past every version held: a move the backend refuses changes nothing
* here. The roster carries on from the one held (members' harnesses included); a computer that held none starts from
* the desk's panes and the members the backend lists, and members add their harnesses again. Moved to where it is,
* nothing is asked or signed.
*/
async move(sharedTabId: string): Promise<{ sharedTabId: string; version: number }> {
const me = await this.self(), pub = await this.myPub()
const shares = await this.shares()
if (!shares) throw unavailable()
const share = shares.find((s) => s.sharedTabId === sharedTabId && s.owner)
if (!share) throw notOwnAccount()
if (sharedTabId !== sharedTabIdOf(me.accountId, share.tabId)) throw shareIdMismatch()
const held = this.deps.store.current(sharedTabId)?.roster
if (held && held.owner.machineId === me.machineId && held.owner.machinePublicKey === pub && share.ownerMachineId === me.machineId) {
return { sharedTabId, version: held.version }
}
const from = held?.owner ?? null
const keyChange = from && from.machineId !== me.machineId ? await this.askKeyChange(sharedTabId, from, pub) : undefined
await this.call('POST', `/api/agent-messages/shares/${sharedTabId}/move`, { machineId: me.machineId })
return this.serial(async () => {
// The listing just read may hold a newer roster than this computer's (harnesses members added since it last heard
// from the old computer): taken first, when it verifies under the pin, or the move would sign them out of the tab
// (final review of 1b). One that does not verify, or is older, changes nothing.
const listed = signedOf(share.roster)
if (listed) this.deps.store.offer(listed)
const base = this.deps.store.current(sharedTabId)?.roster
this.owned.set(sharedTabId, { tabId: share.tabId, floor: Math.max(share.version, base?.version ?? 0), ...(keyChange ? { keyChange } : {}) })
const start = base ?? { ...await this.empty(sharedTabId, parseRoster(signedOf(share.roster)?.body ?? '')?.name ?? ''), version: 0 }
const own = await this.ownHarnesses(share.tabId, start.harnesses)
await this.change(start, { members: share.members, invites: share.invites, ...(own ? { own } : {}), ...await this.leaderOf(share.tabId) }, true, true)
return { sharedTabId, version: this.owned.get(sharedTabId)!.floor }
})
}
/** The old computer's signature over this one's key, kept only when it verifies under the key the held roster names:
* anything else would only make members record a roster they cannot verify, which no change does as well. */
private async askKeyChange(id: string, from: Roster['owner'], nextPub: string): Promise<KeyChange | undefined> {
const answer = await this.deps.askMachine(from.machineId, { action: 'tab_keychange', sharedTabId: id, nextPub, machineId: (await this.self()).machineId })
const signature = answer?.signature
if (answer?.previousPub !== from.machinePublicKey || typeof signature !== 'string') return undefined
return verify(b64d(from.machinePublicKey), keyChangeBytes(id, nextPub), b64d(signature)) ? { previousPub: from.machinePublicKey, signature } : undefined
}
/**
* Another computer of this account is taking a tab (service.ts `tab_keychange`, only over the paired relay): signed
* only while this computer is its authority, the roster it holds naming it under the key pinned here, which is its
* own. A computer that began again with a new key, or holds the tab as another's, has no key members trust to sign.
* The key must be the one the named machine of this account reports itself (`machineKey`, which reaches only the
* account's paired machines): the paired relay also carries the owner's apps (a phone, a remote window), and the
* signature has no version, so a key no machine holds would move every member's pin to it for good (review of A6).
* Asked before the queue: a machine that cannot be asked costs an 8 s wait.
*/
async keyChange(sharedTabId: string, nextPub: unknown, machineId: unknown): Promise<{ previousPub: string; signature: string }> {
if (typeof nextPub !== 'string' || !PUB.test(nextPub)) throw new MessageError('INVALID_KEY', 'Name the key of the computer the tab moves to.')
if (typeof machineId !== 'string' || !machineId || await this.deps.machineKey(machineId) !== nextPub) {
throw new MessageError('NOT_OUR_MACHINE', 'That key is not the one a computer of this account reports.')
}
return this.serial(async () => {
const held = this.deps.store.current(sharedTabId), pub = await this.myPub()
if (!held || !await this.owns(held.roster) || this.deps.store.pinned(sharedTabId) !== pub) throw notOwner()
return { previousPub: pub, signature: await this.deps.key.signKeyChange(sharedTabId, nextPub) }
})
}
/** Re-read the shares (on wake, on `desk_changed`, and while a request waits): the owner republishes when its members
* or its panes changed; a member takes the newest roster the backend holds, if its owner's key signed it. */
refresh(): Promise<void> {
return this.serial(async () => {
if (this.closed) return
if (this.unloaded) this.restore()
// A backend from before shared tabs has nothing to read; the tabs held here still open their relays, which a
// backend that has them again then carries.
const shares = await this.shares().catch((error: unknown) => {
if (error instanceof MessageError && error.code === 'SHARED_TABS_UNSUPPORTED') return null
throw error
})
await this.reread(shares)
// Every tab held, listed or not: a tab the backend no longer lists for this account is one it was removed from
// while away, which the relay answers with 4403, and that forgets it here.
for (const roster of this.deps.store.all()) await this.openRelay(roster.sharedTabId)
if (shares) await this.announceIfChanged(shares)
this.deps.changed?.()
})
}
/** The invitations and untrusted tabs as last told, so a refresh that changed neither tells the windows nothing. */
private told = ''
private async announceIfChanged(shares: ShareView[]): Promise<void> {
const invites = await this.invites().catch(() => null)
if (!invites) return
const untrusted = this.untrustedOf(shares, await this.self())
const digest = JSON.stringify([invites.map((i) => i.id).sort(), untrusted.map((u) => u.sharedTabId).sort()])
if (digest === this.told) return
this.told = digest
this.deps.announce?.()
}
/** The desk tab a tab of this account's is shared from, for the directory to merge the members' harnesses into; null
* for a tab shared with this account, or one whose shares this computer has not read yet. */
deskTab(sharedTabId: string): string | null {
return this.owned.get(sharedTabId)?.tabId ?? this.desks.get(sharedTabId) ?? null
}
private async reread(shares: ShareView[] | null): Promise<void> {
if (!shares) return
const me = await this.self()
for (const share of shares) {
// A share of this account under an id the backend did not derive from the account and the tab: signing for it
// would put this computer's key on a tab of the backend's choosing, which `share` refused (SHARE_ID_MISMATCH).
if (share.owner && share.sharedTabId !== sharedTabIdOf(me.accountId, share.tabId)) { this.misnamed(share.sharedTabId); continue }
if (share.owner) this.desks.set(share.sharedTabId, share.tabId)
if (!share.owner || share.ownerMachineId !== me.machineId) { await this.retake(share); continue }
// Both fields are the backend's word. A tab held here as another computer's is never taken for this one's: a
// listing saying otherwise would have this computer sign a roster over the real owner's and pin its own key.
const held = this.deps.store.current(share.sharedTabId)?.roster
if (!held || (held.owner.machineId === me.machineId && held.owner.machinePublicKey === await this.myPub())) await this.reshare(share)
}
for (const id of new Set([...this.queue.values()].map((r) => r.sharedTabId))) await this.flush(id)
}
/** Recorded once for the person (it stays in the alerts across restarts), however often the shares are read. */
private misnamed(id: string): void {
if (!this.deps.store.alerts().some((a) => a.sharedTabId === id && a.error === 'share_id_mismatch')) this.deps.store.alert(id, 'share_id_mismatch')
}
/** One of this computer's shares, as the backend has it now: members accepted or removed, invitations, and the
* desk's panes. A roster this computer lost (a new data folder) is taken back from the backend when its own key
* signed it, and otherwise begun again past the backend's version. */
private async reshare(share: ShareView): Promise<void> {
const id = share.sharedTabId, had = this.owned.get(id)
// A restart forgets the old computer's key change; the roster this computer signed with it last still carries it.
const keyChange = had?.keyChange ?? this.deps.store.current(id)?.signed.keyChange
this.owned.set(id, { tabId: share.tabId, floor: Math.max(had?.floor ?? 0, share.version), ...(keyChange ? { keyChange } : {}) })
let held = this.deps.store.current(id)?.roster
const signed = signedOf(share.roster)
if (!held) {
await this.pinSelf(id)
const offered = signed ? this.deps.store.offer(signed) : null
held = offered && 'roster' in offered ? offered.roster : undefined
}
const base = held ?? { ...await this.empty(id, parseRoster(signed?.body ?? '')?.name ?? ''), version: 0 }
const own = await this.ownHarnesses(share.tabId, base.harnesses)
await this.change(base, { members: share.members, invites: share.invites, ...(own ? { own } : {}), ...await this.leaderOf(share.tabId) }, !held)
}
/** A share of another computer: a member's, whose owner key was pinned when the person accepted, on this computer or
* another of the account's (`pull`), or one this account shares from another of its computers, whose key that
* computer reports. */
private async retake(share: ShareView): Promise<void> {
if (share.owner && !this.deps.store.current(share.sharedTabId)) {
const pub = await this.deps.machineKey(share.ownerMachineId)
if (pub) this.deps.store.pin(share.sharedTabId, pub)
}
if (!share.owner && !this.deps.store.pinned(share.sharedTabId)) this.pull(share.sharedTabId)
const signed = signedOf(share.roster)
const offered = signed && this.deps.store.offer(signed)
if (offered && 'roster' in offered) await this.adopt(offered.roster)
const now = this.deps.store.current(share.sharedTabId)?.roster
if (share.owner && now && now.owner.machineId !== share.ownerMachineId) this.follow(share)
}
/**
* This account's tab moved to another of its computers with no key change this one could verify (the old computer
* was away): the owner's computers trust each other's machine keys (`retake`, `tab_pub`), never a fingerprint, so this
* one takes the new computer's roster under the key that computer reports, never the key the roster names. Only a
* roster that verifies under it, names that computer under that same key (a key change it signed to some other key
* would verify too, review of A6) and this account, and is newer than the one held: a backend that
* named another computer of the account could otherwise steer this one back to an older roster of that computer's.
* Asked beside the queue, at most once every PULL_RETRY_MS: the new computer may be asleep, and its 8 s wait would
* hold up every frame on each read of the shares.
*/
private follow(share: ShareView): void {
const id = share.sharedTabId, last = this.followed.get(id)
if (last !== undefined && this.now() - last < PULL_RETRY_MS) return
this.followed.set(id, this.now())
void this.deps.machineKey(share.ownerMachineId).then((pub) => pub ? this.serial(async () => {
const me = await this.self(), held = this.deps.store.current(id)?.roster, signed = signedOf(share.roster)
const checked = signed && verifyRoster(signed, pub)
if (!held || !checked || 'error' in checked || checked.roster.sharedTabId !== id || checked.roster.owner.machineId !== share.ownerMachineId
|| checked.roster.owner.machinePublicKey !== pub || checked.roster.owner.accountId !== me.accountId || checked.roster.version <= held.version) return
this.deps.store.forget(id)
this.deps.store.pin(id, pub)
this.deps.store.offer(signed)
this.followed.delete(id)
await this.adopt(checked.roster)
await this.openRelay(id)
}) : undefined).catch(ignore)
}
private async authority(id: string): Promise<Roster> {
const held = this.deps.store.current(id)
if (!held || !await this.owns(held.roster)) throw notOwner()
if (!this.owned.has(id)) await this.reread(await this.shares())
if (!this.owned.has(id)) throw unavailable()
return this.deps.store.current(id)!.roster
}
private held(id: string): { roster: Roster; signed: SignedRoster } {
const held = this.deps.store.current(id)
if (!held) throw new MessageError('NOT_SHARED', 'This computer holds no such shared tab.')
return held
}
private async empty(sharedTabId: string, name: string): Promise<Roster> {
const me = await this.self()
return { sharedTabId, version: 1, name: name.slice(0, 200), leader: null, members: [], harnesses: [], invites: [],
owner: { accountId: me.accountId, email: me.email, machineId: me.machineId, machinePublicKey: await this.myPub() } }
}
/** The roster's leader as the owner's tab setting names it (`setLeader`): the setting is the one source, so a roster
* this computer signs follows it, a leader that may lead no more included. Nothing while the setting is not known: the
* roster keeps its own. `composeCut` drops one the roster does not list. */
private async leaderOf(tabId: string): Promise<{ leader?: Roster['leader'] }> {
const leader = await this.deps.ownLeader?.(tabId)
return leader === undefined ? {} : { leader }
}
/** The desk tab's panes as the owner's harnesses, each with its machine's key; a machine that cannot be asked keeps
* the key the roster had for it, and one never listed is left out until it can be. */
private async ownHarnesses(tabId: string, had: RosterHarness[]): Promise<RosterHarness[] | null> {
const panes = await this.deps.ownPanes(tabId)
if (!panes) return null
const me = await this.self(), keys = new Map<string, string | null>()
const out: RosterHarness[] = []
for (const pane of panes) {
if (!keys.has(pane.machineId)) {
keys.set(pane.machineId, await this.deps.machineKey(pane.machineId)
?? had.find((h) => h.machineId === pane.machineId && h.accountId === me.accountId)?.machinePublicKey ?? null)
}
const harness = wireHarness({ ...pane, name: String(pane.name).slice(0, 200), engine: String(pane.engine).slice(0, 64),
accountId: me.accountId, machinePublicKey: keys.get(pane.machineId) })
if (harness) out.push(harness)
}
return out
}
/**
* Sign a roster and store it on the backend. A version only grows (the spec's "Authority"), across a stop and a share
* again too: a put that is not newer than what the backend holds is refused with the version it holds
* (`STALE_ROSTER`), and signed once more, past it. A second refusal is told as the backend said it.
*/
private async put(tabId: string, roster: Roster): Promise<{ data: Wire; roster: Roster; signed: SignedRoster }> {
const me = await this.self()
const keyChange = this.owned.get(roster.sharedTabId)?.keyChange
const once = async (r: Roster) => {
if (!fitsRoster(r)) throw new MessageError('TAB_FULL', 'The shared tab\'s roster would be too large for its members to take. Take a harness out of it.')
const signed = { ...await this.sign(r), ...(keyChange ? { keyChange } : {}) }
return { reply: await this.deps.backend('PUT', rosterPath(tabId), { machineId: me.machineId, version: r.version, roster: signed }), roster: r, signed }
}
let tried = await once(roster)
const held = staleAt(tried.reply)
if (held !== null) tried = await once({ ...roster, version: Math.max(held, roster.version) + 1 })
return { data: dataOf(tried.reply), roster: tried.roster, signed: tried.signed }
}
private async sign(roster: Roster): Promise<SignedRoster> {
const body = encodeRoster(roster)
return { body, signature: await this.deps.key.signRoster(roster.sharedTabId, roster.version, body) }
}
/** The owner trusts its own key for its own tabs: a key it no longer has (a new identity) is replaced, not kept. Only
* for a tab whose held roster is this computer's, or that holds none: a member's pin is its owner's, and replacing
* it would take every real roster for a forgery from then on. */
private async pinSelf(id: string): Promise<void> {
const pub = await this.myPub()
if (this.deps.store.pin(id, pub) === 'pinned') return
const held = this.deps.store.current(id)
if (held && !await this.owns(held.roster)) throw new MessageError('NOT_OWNER', 'That tab is shared with this computer by another: it cannot share it.')
this.deps.store.forget(id)
this.deps.store.pin(id, pub)
}
/** The next roster when it says something new, one version past both what is held here and what the backend has. */
private async change(roster: Roster, delta: Parameters<typeof composeCut>[1], always = false, takeOver = false): Promise<void> {
const { roster: next, cut } = composeCut(roster, { owner: { ...(await this.empty(roster.sharedTabId, '')).owner }, ...delta })
if (!always && sameRoster(roster, next)) return
await this.publish({ ...next, version: Math.max(roster.version, this.owned.get(roster.sharedTabId)!.floor) + 1 }, takeOver)
if (cut) this.full(roster.sharedTabId)
}
/** A roster just published was cut to the harness limit: the owner's desk has more panes than a tab holds. Told once
* for each roster that cut, and not again while the last such notice is unread: a desk that stays too big is cut on
* every change, and the person needs telling once. */
private full(id: string): void {
if (!this.noticed.unread().some((n) => n.sharedTabId === id && n.kind === 'full')) this.notice({ sharedTabId: id, kind: 'full', error: 'TAB_FULL' })
}
/** Sign, store on the backend, keep, and send to every other machine the roster lists: one whose session is not open
* yet gets it once it opens (`opened`). A tab moving here (`takeOver`) gives up the roster held under the old
* computer's key once the backend took this one's, not before: a put that fails leaves it as it was. */
private async publish(draft: Roster, takeOver = false): Promise<void> {
const me = await this.self(), id = draft.sharedTabId
const { roster: next, signed } = await this.put(this.owned.get(id)!.tabId, draft)
this.owned.get(id)!.floor = next.version
if (takeOver) this.deps.store.forget(id)
await this.pinSelf(id)
this.deps.store.offer(signed)
await this.adopt(next)
await this.openRelay(id)
const machines = new Map(next.harnesses.filter((h) => h.machineId !== me.machineId).map((h) => [h.machineId, h.accountId]))
for (const [machineId, accountId] of machines) {
if (await this.ensure(next, machineId, accountId)) await this.sealTo(next, machineId, { kind: 'roster', signed })
}
}
/** A member's request, from a machine whose session proved the key it has here. Applied only for the sender's own
* account, which must be a member; the same request twice changes nothing the second time. The sender always gets
* the outcome: a refusal, or the roster, which settles its request even when its machine is not listed in it. */
private async apply(id: string, from: { machineId: string; userId: string }, link: Link, frame: Wire): Promise<void> {
let roster: Roster
try { roster = await this.authority(id) } catch { return }
const reqId = typeof frame.id === 'string' ? frame.id.slice(0, 400) : null
if (!reqId || (frame.op !== 'add' && frame.op !== 'remove')) return
const verdict = judge(roster, from, link.peerPub, frame.op, frame.harness)
if (typeof verdict === 'string') { await this.sealTo(roster, from.machineId, { kind: 'roster_refused', id: reqId, error: verdict }); return }
// Only a request that changes the roster counts: a member sends every waiting request again on each retry, refresh
// and new session, and a repeat already applied (or a remove already done) costs a reply, not a signature.
if (verdict && !this.admitRequest(from.userId)) { await this.sealTo(roster, from.machineId, { kind: 'roster_refused', id: reqId, error: 'RATE_LIMITED' }); return }
if (verdict) await this.change(roster, verdict)
const now = this.held(id)
if (!verdict || !now.roster.harnesses.some((h) => h.machineId === from.machineId)) await this.sealTo(now.roster, from.machineId, { kind: 'roster', signed: now.signed })
}
/** Whether a member account's change is within REQUESTS_PER_MEMBER in REQUEST_WINDOW_MS, counting it if so. One
* refused is not counted: a member that asks too often is let in again as its earlier requests age out. */
private admitRequest(accountId: string): boolean {
const now = this.now(), recent = (this.requestsFrom.get(accountId) ?? []).filter((at) => now - at < REQUEST_WINDOW_MS)
const admitted = recent.length < REQUESTS_PER_MEMBER
this.requestsFrom.set(accountId, admitted ? [...recent, now] : recent)
return admitted
}
// ── a member ──────────────────────────────────────────────────────────────────────────────────────
async invites(): Promise<Array<{ id: string; sharedTabId: string; ownerEmail: string; ownerMachineId: string; expiresAt: string; tabName: string }>> {
const data = await this.call('GET', '/api/agent-messages/invites')
return (Array.isArray(data.invites) ? data.invites : []).flatMap((i) => {
const r = record(i)
return r && [r.id, r.sharedTabId, r.ownerEmail, r.ownerMachineId, r.expiresAt].every((v) => typeof v === 'string')
// The tab's name is the owner's, unverified until the roster is read after Accept: cleaned again here, and '' from a
// backend that sends none (an older one), so a window says "a tab".
? [{ id: r.id as string, sharedTabId: r.sharedTabId as string, ownerEmail: r.ownerEmail as string, ownerMachineId: r.ownerMachineId as string, expiresAt: r.expiresAt as string,
tabName: typeof r.tabName === 'string' ? cleanName(r.tabName).slice(0, 200) : '' }]
: []
})
}
/**
* The invitee cannot see the owner's key before accepting (the backend shows a roster only to members), so trust is
* on first use: the key of the first roster read after accepting is pinned, and its fingerprint returned for the
* person to compare. A key the person was shown (`ownerPub`) must be that one. A roster that does not verify, or
* the wrong key, leaves the tab again at once: a membership whose roster cannot be trusted is only a way in.
*
* A roster that cannot be read at all (the backend down, or not listing the tab yet) is not one that failed: the
* shares are read again (`acceptedShare`), and still unreadable the person stays a member, `pending`, with nothing
* pinned. The tab is then among the `untrusted`, whose owner the person trusts once its roster can be read.
*/
accept(inviteId: string, ownerPub?: string): Promise<{ sharedTabId: string; fingerprint: string } | { sharedTabId: string; pending: true }> {
return this.serial(async () => {
const me = await this.self()
const id = String((await this.call('POST', `/api/agent-messages/invites/${encodeURIComponent(inviteId)}/accept`)).sharedTabId)
const share = await this.acceptedShare(id)
if (!share) return { sharedTabId: id, pending: true as const }
const signed = signedOf(share.roster)
const roster = signed && parseRoster(signed.body)
const leave = async (code: string, message: string): Promise<never> => {
await this.deps.backend('DELETE', memberPath(id, me.accountId))
this.deps.store.forget(id)
throw new MessageError(code, message)
}
if (!signed || !roster || roster.sharedTabId !== id) return leave('ROSTER_INVALID', 'The shared tab\'s roster could not be verified, so you left it again. Ask its owner to invite you again.')
const pub = roster.owner.machinePublicKey
if (ownerPub && ownerPub !== pub) return leave('OWNER_KEY_MISMATCH', 'The shared tab is signed by another computer than the one you were shown, so you left it again.')
if (!await this.trust(id, signed, pub)) return leave('ROSTER_INVALID', 'The shared tab\'s roster could not be verified, so you left it again. Ask its owner to invite you again.')
return { sharedTabId: id, fingerprint: fingerprint(b64d(pub)) }
})
}
/** The share just accepted as the backend lists it, read again up to ACCEPT_RETRIES times ACCEPT_RETRY_MS apart while
* the shares cannot be read or do not list it; null when they never did. In the queue, as the accept is: up to 3 s. */
private async acceptedShare(id: string): Promise<ShareView | null> {
for (let tries = 0; ; tries++) {
const share = (await this.shares().catch(() => null))?.find((s) => s.sharedTabId === id)
if (share || tries === ACCEPT_RETRIES) return share ?? null
await new Promise((done) => setTimeout(done, ACCEPT_RETRY_MS))
}
}
/**
* The first of two steps to trust a tab's owner again without a new invitation (the spec's Errors row "the member is
* asked to accept again" now means "confirm the new fingerprint"): the key the backend's roster names, which signed
* it, beside the one pinned here, for the person to compare. Nothing changes here. Refused for this account's own
* tabs, whose trust is its computers' keys (`retake`), and for a tab the backend lists no membership of.
*/
retrustOffer(sharedTabId: string): Promise<{ sharedTabId: string; ownerEmail: string; ownerPub: string; fingerprint: string; version: number; pinnedFingerprint: string | null }> {
return this.serial(async () => {
const { share, roster } = await this.listed(sharedTabId)
const pub = roster.owner.machinePublicKey, pinned = this.deps.store.pinned(sharedTabId)
return { sharedTabId, ownerEmail: share.ownerEmail, ownerPub: pub, fingerprint: fingerprint(b64d(pub)), version: roster.version,
pinnedFingerprint: pinned && fingerprint(b64d(pinned)) }
})
}
/**
* The second step: the person confirmed the fingerprint of `ownerPub`, which is pinned in place of whatever was, with
* the roster it signed. The roster is read again, not taken from the check: a key that changed in between is not the
* one the person saw (`OWNER_KEY_MISMATCH`, and the old pin stays). A roster older than one that verifies here is
* refused (`STALE_ROSTER`): a backend serving an old roster under another key would otherwise have the person trade
* the owner's current key for it.
*/
retrust(sharedTabId: string, ownerPub: string): Promise<{ sharedTabId: string; fingerprint: string }> {
return this.serial(async () => {
const { signed, roster } = await this.listed(sharedTabId)
if (roster.owner.machinePublicKey !== ownerPub) {
throw new MessageError('OWNER_KEY_MISMATCH', 'The shared tab is now signed by another computer than the one you were shown. Check its fingerprint again.')
}
const held = this.deps.store.current(sharedTabId)?.roster
if (held && held.version > roster.version) {
throw new MessageError('STALE_ROSTER', 'This computer holds a newer roster of that tab than the backend serves, so nothing changed. Try again in a moment.')
}
// It verified against this key (`listed`), so it is taken.
await this.trust(sharedTabId, signed, ownerPub)
return { sharedTabId, fingerprint: fingerprint(b64d(ownerPub)) }
})
}
/**
* The memberships the backend lists for this account that no roster held here verifies, for the person to trust the
* owner again (`retrustOffer`): no key pinned here (a new data folder, and none of the account's other computers
* had one to give, `pull`), or the pinned key cannot verify what the backend serves now (the owner began again with
* a new key and no change signed by the old, `unpinned_key`). A read only: it pulls nothing and pins nothing.
*/
private pendingByTab = new Map<string, Array<{ id: string; email: string; expiresAt: string }>>()
async untrusted(): Promise<Array<{ sharedTabId: string; ownerEmail: string }>> {
const shares = await this.shares()
if (!shares) throw unavailable()
this.pendingByTab = new Map(shares.filter((s) => s.owner).map((s) => [s.sharedTabId, s.pending]))
return this.untrustedOf(shares, await this.self())
}
/** The owner's pending invitations of a tab, with their ids, as the last read of `untrusted()` listed them; none for
* a tab not owned here or not read yet. Taken from that read so a `shares` answer costs one backend read. */
pendingInvites(sharedTabId: string): Array<{ id: string; email: string; expiresAt: string }> {
return this.pendingByTab.get(sharedTabId) ?? []
}
private untrustedOf(shares: ShareView[], me: Me): Array<{ sharedTabId: string; ownerEmail: string }> {
return shares.filter((s) => {
// The owner's own tabs, by the backend's word or by the roster's: its computers trust each other's keys (`follow`).
if (s.owner || parseRoster(signedOf(s.roster)?.body ?? '')?.owner.accountId === me.accountId) return false
const pin = this.deps.store.pinned(s.sharedTabId), signed = signedOf(s.roster)
const checked = pin && signed ? verifyRoster(signed, pin) : null
return !checked || 'error' in checked || checked.roster.sharedTabId !== s.sharedTabId
}).map((s) => ({ sharedTabId: s.sharedTabId, ownerEmail: s.ownerEmail }))
}
/** This account's membership of a tab as the backend lists it, and the roster it serves, verified against the key that
* roster names: what the owner's computer signed, if the person trusts that key. */
private async listed(id: string): Promise<{ share: ShareView; signed: SignedRoster; roster: Roster }> {
const isOwner = () => new MessageError('IS_OWNER', 'Your account shares this tab: there is no owner to trust again.')
const held = this.deps.store.current(id)
if (held && await this.owns(held.roster)) throw isOwner()
const shares = await this.shares()
if (!shares) throw unavailable()
const share = shares.find((s) => s.sharedTabId === id)
if (share?.owner) throw isOwner()
if (!share) throw new MessageError('NOT_SHARED', 'Your account is not a member of that shared tab.')
const signed = signedOf(share.roster), own = signed && parseRoster(signed.body)
const checked = own && verifyRoster(signed, own.owner.machinePublicKey)
if (!checked || 'error' in checked || checked.roster.sharedTabId !== id) throw rosterInvalid()
// A roster of this account's own tab, whatever the backend's owner flag says: a backend that called one of the
// owner's computers a member would otherwise have it trust a key of the backend's choosing on a fingerprint.
if (checked.roster.owner.accountId === (await this.self()).accountId) throw isOwner()
return { share, signed: signed!, roster: checked.roster }
}
/**
* First trust, or trust again: what this computer held for the tab (a pin, a roster of a share since stopped and
* started again at version 1, a roster under a key the person no longer trusts) gives way to the key the person was
* shown and the roster it signed. A session with a machine under a key that roster does not list ends (`adopt`).
* False when the roster does not verify against the key, and then nothing is pinned: a pin that never verified a
* roster would refuse the real one from then on.
*/
private async trust(id: string, signed: SignedRoster, pub: string): Promise<boolean> {
this.deps.store.forget(id)
this.deps.store.pin(id, pub)
const offered = this.deps.store.offer(signed)
if (!('roster' in offered)) { this.deps.store.forget(id); return false }
await this.adopt(offered.roster)
await this.openRelay(id)
// The account's other computers take the pin from here now (`pull`), rather than once their wait is over. Not
// waited for: one asleep would hold the accept for the 8 s its ask takes to fail.
void this.tellOthers(id).catch(ignore)
return true
}
/**
* Asks the owner's computer to add a harness of this account: queued until the owner's roster lists it, which may be
* once that computer is back. The owner takes an add only from the harness's own machine (`judge`), so a harness on
* another machine of this account is handed to that machine, which asks for it itself; this one never sends a request
* naming another machine. That machine's answer is waited for outside the queue: up to 8 s of it would hold up every
* frame and change here. Its refusal is told as it said it (`NOT_SHARED` there is not a machine away). An add handed
* on (`forwarded`) for a harness that is not this machine's is refused, never handed on again: two machines that
* each took the harness for the other's would otherwise pass it back and forth.
*/
async addHarness(sharedTabId: string, harness: Pane, forwarded = false): Promise<Record<string, unknown>> {
const held = this.held(sharedTabId)
if (await this.owns(held.roster)) throw new MessageError('OWNER_PANE', 'Put the pane in the tab on your desk: your own harnesses come from there.')
const ref = harnessRef(harness)
if (!ref) throw invalid()
if (ref.machineId !== (await this.self()).machineId) {
if (forwarded) throw new MessageError('NOT_THIS_MACHINE', 'That harness is not on this machine: add it from the machine it runs on.')
const answer = await this.deps.askMachine(ref.machineId, { action: 'share_add', sharedTabId, harness, forwarded: true })
if (!answer) throw new MessageError('MACHINE_AWAY', 'That machine could not be asked to add it. Try again once it is on.')
const refused = record(answer.error)
if (refused) throw new MessageError(String(refused.code), String(refused.message))
return answer
}
return this.serial(async () => {
const pub = await this.deps.machineKey(ref.machineId)
if (!pub) throw new MessageError('MACHINE_AWAY', 'That machine could not be asked for its key. Try again once it is on.')
const full = wireHarness({ ...harness, accountId: (await this.self()).accountId, machinePublicKey: pub })
if (!full) throw invalid()
const listed = this.held(sharedTabId).roster.harnesses.some((h) => same(h, full))
// Asked here, on the harness's own machine: the only word that lets the tab's other accounts watch it.
this.deps.consent?.grant(sharedTabId, full.machineId, full.agentId, listed)
if (!listed) {
this.enqueue(sharedTabId, 'add', full)
await this.flush(sharedTabId)
}
return { queued: true as const }
})
}
/** What another computer of this account takes a tab from (service.ts `tab_pin`): the owner key pinned here and the
* roster held, which verified against it. */
pinOf(sharedTabId: string): { ownerPub: string; signed: SignedRoster } {
const { signed } = this.held(sharedTabId)
return { ownerPub: this.deps.store.pinned(sharedTabId)!, signed }
}
/** Another computer of this account pinned a tab (service.ts `tab_pin_changed`): it is asked at once, whatever wait an
* earlier failed ask left. */
pinChanged(sharedTabId: string): Promise<void> {
this.pulled.delete(sharedTabId)
return this.refresh()
}
private async tellOthers(id: string): Promise<void> {
const me = await this.self()
for (const machineId of await this.deps.ownMachines() ?? []) {
if (machineId !== me.machineId) void this.deps.askMachine(machineId, { action: 'tab_pin_changed', sharedTabId: id })
}
}
/**
* A tab this account is a member of, which this computer holds no pin for: the person accepted on another of its
* computers. Its pin and roster are taken from the first of the account's other computers whose answer verifies, as
* this computer checks any roster: the key it names must sign the roster it gives. Trusting a pin because another
* computer of the same account vouches for it is the trust `tab_pub` and the owner's own `retake` already give the
* account's machines: the paired relay carries only this account's machines, and a computer that lied could as well
* have accepted the invitation itself. Asked together and beside the queue: one asleep costs one 8 s wait, and holds
* up no frame. A computer that could not take it asks again after PULL_RETRY_MS, or when told the pin changed.
*/
private pull(id: string): void {
const last = this.pulled.get(id)
if (last !== undefined && this.now() - last < PULL_RETRY_MS) return
this.pulled.set(id, this.now())
void this.pullFrom(id).catch(ignore)
}
private async pullFrom(id: string): Promise<void> {
const me = await this.self()
const others = (await this.deps.ownMachines() ?? []).filter((m) => m !== me.machineId)
const taken = await Promise.all(others.map(async (machineId) => {
const answer = await this.deps.askMachine(machineId, { action: 'tab_pin', sharedTabId: id })
return !!answer && this.serial(() => this.takePin(id, answer))
}))
if (taken.includes(true)) this.pulled.delete(id)
else this.pulled.set(id, this.now())
}
/** One computer's answer: kept only when its roster is this tab's and verifies against the key it names. One that
* does not leaves no pin behind: a pin that never verified a roster would refuse the real one from then on. */
private async takePin(id: string, answer: Wire): Promise<boolean> {
if (this.deps.store.pinned(id)) return true
const signed = signedOf(answer.signed)
if (typeof answer.ownerPub !== 'string' || !signed || parseRoster(signed.body)?.sharedTabId !== id) return false
// No pin is held here (above), so this one is taken: the roster must then verify against it.
this.deps.store.pin(id, answer.ownerPub)
const offered = this.deps.store.offer(signed)
if (!('roster' in offered)) { this.deps.store.forget(id); return false }
await this.adopt(offered.roster)
await this.openRelay(id)
return true
}
leave(sharedTabId: string): Promise<void> {
return this.serial(async () => {
const held = this.deps.store.current(sharedTabId)
if (held && await this.owns(held.roster)) throw new MessageError('IS_OWNER', 'You share this tab: stop sharing it instead.')
await this.call('DELETE', memberPath(sharedTabId, (await this.self()).accountId))
this.drop(sharedTabId)
})
}
private enqueue(sharedTabId: string, op: Request['op'], harness: RosterHarness): void {
const id = requestId(op, harness)
// The opposite request for the same harness is now stale: only the latest word is worth sending.
this.queue.delete(`${sharedTabId}:${requestId(op === 'add' ? 'remove' : 'add', harness)}`)
if (!this.queue.has(`${sharedTabId}:${id}`)) this.queue.set(`${sharedTabId}:${id}`, { sharedTabId, id, op, harness, since: this.now() })
this.persist()
this.timed()
}
private waiting(id: string): Request[] { return [...this.queue.values()].filter((r) => r.sharedTabId === id) }
/** Send what waits for the tab's owner, over a session with its computer, or start one: once it opens, `opened` sends. */
private async flush(id: string): Promise<void> {
const held = this.deps.store.current(id), waiting = this.waiting(id)
if (!held || !waiting.length) return
const owner = held.roster.owner
if (!await this.ensure(held.roster, owner.machineId, owner.accountId)) return
for (const r of waiting) await this.sealTo(held.roster, owner.machineId, { kind: 'roster_request', id: r.id, op: r.op, harness: r.harness })
}
/** The 30 s retry runs only while something waits. */
private timed(): void {
if (this.queue.size && !this.timer && !this.closed) {
this.timer = setInterval(() => { void this.refresh().catch(ignore) }, RETRY_MS)
this.timer.unref()
}
if (!this.queue.size && this.timer) { clearInterval(this.timer); this.timer = null }
}
// ── both ──────────────────────────────────────────────────────────────────────────────────────────
rosters(): Roster[] { return this.deps.store.all() }
/** What waits for the owner's computer, for the person to see as `Joining…`. */
pending(): Array<{ sharedTabId: string; op: Request['op']; machineId: string; agentId: string; name: string; since: string }> {
return [...this.queue.values()].map((r) => ({ sharedTabId: r.sharedTabId, op: r.op, machineId: r.harness.machineId,
agentId: r.harness.agentId, name: r.harness.name, since: new Date(r.since).toISOString() }))
}
/** What happened that the person has not dismissed: it stays until `dismissNotice`, so a window that was closed or a
* restart in between loses nothing. */
notices(): SharedNotice[] { return this.noticed.unread() }
/** The person dismissed one: false when it is already gone. */
dismissNotice(id: string): boolean {
const gone = this.noticed.dismiss(id)
if (gone) this.deps.announce?.()
return gone
}
private notice(n: Omit<SharedNotice, 'id' | 'at'>): void {
if (this.noticed.add(n)) this.deps.announce?.()
}
/** Asleep: no socket stays open and no timer runs (service.ts makes a new one on waking). */
close(): void {
this.closed = true
if (this.timer) clearInterval(this.timer)
this.timer = null
for (const id of [...this.takeovers.keys()]) this.untake(id)
for (const roster of this.deps.store.all()) this.deps.relay.close(roster.sharedTabId)
for (const [k, link] of this.links) this.forget(k, link)
this.giveUp(null)
}
/** This computer is out of the tab: what it held for it goes. With `keepPin` (a 4403 for a tab another account owns,
* `heard`), the owner key pinned stays (rosterStore.ts `release`); leaving and stopping forget it too. The consent
* goes either way: a harness is in a tab again only once this machine asks again. */
private drop(id: string, keepPin = false): void {
this.deps.consent?.forgetTab(id)
if (keepPin) this.deps.store.release(id)
else this.deps.store.forget(id)
this.deps.relay.close(id)
this.untake(id)
this.owned.delete(id)
this.desks.delete(id)
this.checked.delete(id)
for (const [k, link] of this.links) if (link.sharedTabId === id) this.forget(k, link)
for (const [k, r] of this.queue) if (r.sharedTabId === id) this.queue.delete(k)
this.giveUp(id)
this.persist()
this.timed()
this.deps.changed?.()
}
/** A sealed frame the relay would not take (too big for a frame, or not sent within its wait): the person is told,
* once per machine while unread, rather than the frame vanish. A request waiting for it is sent again on its retry. */
private unsent(id: string, machineId: string): void {
if (!this.noticed.unread().some((n) => n.sharedTabId === id && n.kind === 'unsent' && n.machineId === machineId)) this.notice({ sharedTabId: id, kind: 'unsent', machineId })
}
/**
* Another socket of this machine took the tab's relay over (4409), and the gateway dialled no more: opened again after
* RELAY_TAKEOVER_MS, while the tab is still held and Agent Messages awake, unless this is one takeover too many within
* RELAY_TAKEOVER_WINDOW_MS, which stops it and tells the person once.
*/
private takenOver(id: string, ownerEmail: string): void {
const now = this.now(), taken = this.takeovers.get(id) ?? { at: [], timer: null, stopped: false }
this.takeovers.set(id, taken)
if (taken.stopped) return
taken.at = [...taken.at.filter((at) => now - at < RELAY_TAKEOVER_WINDOW_MS), now]
if (taken.timer) clearTimeout(taken.timer)
taken.timer = null
if (taken.at.length > RELAY_TAKEOVERS) {
taken.stopped = true
this.notice({ sharedTabId: id, kind: 'relay_taken', ownerEmail })
return
}
taken.timer = setTimeout(() => {
taken.timer = null
void this.serial(async () => { if (this.deps.store.current(id)) await this.openRelay(id) })
}, RELAY_TAKEOVER_MS)
taken.timer.unref()
}
/** What a tab's takeovers left (its wait, its stop) goes with the tab, or as Agent Messages goes to sleep. */
private untake(id: string): void {
const timer = this.takeovers.get(id)?.timer
if (timer) clearTimeout(timer)
this.takeovers.delete(id)
}
private forget(k: string, link: Link): void {
this.deps.key.drop(linkOf(link))
this.links.delete(k)
}
/** A newer roster is held: a session with a machine that left it, or whose key it changed, never carries on; a
* request it now shows settled waits no more; and a member checks what it lists under its own account. */
private async adopt(roster: Roster): Promise<void> {
const authority = await this.owns(roster)
for (const [k, link] of this.links) {
if (link.sharedTabId === roster.sharedTabId && peerKey(roster, link.machineId, link.userId, link.peerPub, authority) !== link.peerPub) this.forget(k, link)
}
let settled = false
for (const [k, r] of this.queue) {
if (r.sharedTabId === roster.sharedTabId && roster.harnesses.some((h) => same(h, r.harness)) === (r.op === 'add')) { this.queue.delete(k); settled = true }
}
if (settled) this.persist()
this.timed()
// Its harnesses are teammates now, in the directory (service.ts), and one that left is one no longer.
this.deps.changed?.()
// Off the queue: it only records alerts, and a machine of this account that is asleep would otherwise hold every
// frame of every tab for the 8 s its key ask takes to fail, on each new version (review of A1, 2026-10-15).
if (!authority) void this.checkOwn(roster).catch(ignore)
}
/**
* The owner's word, and the backend's, decide what a roster lists under this account; only this account knows its own
* machines. An entry on a machine its directory does not list (`foreign_machine`), or under another key than that
* machine reports (`machine_key_mismatch`), is recorded for the person to see, never removed: detect, not block (a
* member that rewrote what it was given would let a lying backend steer it). A machine that cannot be asked is
* skipped. Each machine once per version, asked together: an unreachable one costs one wait, not one each. Run
* beside the queue (`adopt`), never in it.
*/
private async checkOwn(roster: Roster): Promise<void> {
const me = await this.self(), id = roster.sharedTabId, last = this.checked.get(id)
const seen = last?.version === roster.version ? last.machines : new Set<string>()
this.checked.set(id, { version: roster.version, machines: seen })
const machines = [...new Set(roster.harnesses.filter((h) => h.accountId === me.accountId && !seen.has(h.machineId)).map((h) => h.machineId))]
// Entries under another account, by machine, kept apart from this account's in `seen` (a machine can be in both).
const listed = [...new Set(roster.harnesses.filter((h) => h.accountId !== me.accountId && !seen.has(`listed:${h.machineId}`)).map((h) => h.machineId))]
if (!machines.length && !listed.length) return
for (const machineId of machines) seen.add(machineId)
for (const machineId of listed) seen.add(`listed:${machineId}`)
const own = await this.deps.ownMachines()
// One of this account's machines under another account: the directory never takes it as theirs (sharedDirectory.ts),
// which would hide every pane of it from this account's own tabs, and the person is told (review of B1). With the
// directory unreadable only this machine is known to be its own; the others are looked at again at the next check.
for (const machineId of listed) {
if (machineId === me.machineId || own?.includes(machineId)) this.deps.store.alert(id, 'own_machine_listed')
else if (!own) seen.delete(`listed:${machineId}`)
}
await Promise.all(machines.map(async (machineId) => {
// This machine is always its own, whatever a directory read says.
if (own && machineId !== me.machineId && !own.includes(machineId)) return this.deps.store.alert(id, 'foreign_machine')
const pub = await this.deps.machineKey(machineId)
if (pub && roster.harnesses.some((h) => h.accountId === me.accountId && h.machineId === machineId && h.machinePublicKey !== pub)) this.deps.store.alert(id, 'machine_key_mismatch')
}))
}
/**
* A session with a machine of the tab: true when one is open. Otherwise the lower machine id says hello, and the
* higher knocks for the lower to: two hellos crossing would each end the other's (`TabSessions.accept` drops this
* side's pending hello). The owner's computer knocks, too, at a member's machine whose key it has not been told.
*/
private async ensure(roster: Roster, machineId: string, userId: string, claimed?: unknown): Promise<boolean> {
const id = roster.sharedTabId
if (!await this.openRelay(id)) return false
const k = `${id}:${machineId}`, link = this.links.get(k)
const authority = await this.owns(roster)
const pub = peerKey(roster, machineId, userId, claimed ?? link?.peerPub, authority)
if (!pub && !(authority && roster.members.some((m) => m.accountId === userId))) return false
if (link?.state === 'open' && link.peerPub === pub) return true
if (link && link.state !== 'open' && link.peerPub === (pub ?? '') && this.now() - link.at < HELLO_RETRY_MS) return false
if (link) this.forget(k, link)
const me = await this.self(), at = this.now()
let frame: Wire
if (pub && me.machineId < machineId) {
const hello = await this.deps.key.hello({ sharedTabId: id, machineId, peerPub: pub })
this.links.set(k, { sharedTabId: id, machineId, peerPub: pub, userId, state: 'hello', at, hello: String(hello.ephemeral) })
frame = { kind: 'hello', hello, pub: await this.myPub() }
} else {
this.links.set(k, { sharedTabId: id, machineId, peerPub: pub ?? '', userId, state: 'knock', at })
frame = { kind: 'knock', pub: await this.myPub() }
}
if (!await this.deps.relay.send(id, machineId, frame)) this.links.delete(k)
return false
}
/** Send a frame sealed for the session with a machine: true once the relay took it. A session the gateway no longer
* has is started again, and that frame is not sent. */
private async sealTo(roster: Roster, machineId: string, frame: Wire): Promise<boolean> {
const id = roster.sharedTabId, link = this.links.get(`${id}:${machineId}`)
if (link?.state !== 'open') return false
const sealed = await this.deps.key.seal(linkOf(link), frame)
if ('frame' in sealed) {
if (await this.deps.relay.send(id, machineId, sealed.frame)) return true
this.unsent(id, machineId)
return false
}
link.state = 'idle'
link.at = -Infinity
await this.ensure(roster, machineId, link.userId)
return false
}
/** A session just opened: the owner sends its roster, a member what waits for the owner, and Agent Messages what
* waits for that machine (`opened`, which only starts it: it never holds up the frames). */
private async opened(id: string, machineId: string, held: { roster: Roster; signed: SignedRoster }): Promise<void> {
this.deps.opened?.(id, machineId)
if (await this.owns(held.roster)) await this.sealTo(held.roster, machineId, { kind: 'roster', signed: held.signed })
if (held.roster.owner.machineId !== machineId) return
for (const r of this.waiting(id)) await this.sealTo(held.roster, machineId, { kind: 'roster_request', id: r.id, op: r.op, harness: r.harness })
}
// ── Agent Messages' requests ──────────────────────────────────────────────────────────────────────
/**
* An Agent Messages request to another account's machine through the tab (`agent_messages`): its result, or its
* refusal as `{ error, detail }`, as that machine's service said it. Rejected PEER_AWAY when no session with the
* machine is open (one is started: the lower machine id says hello) or the relay cannot reach it, RELAY_TAKEN while
* another socket of this machine holds the tab's relay (4409), TOO_LARGE for a request no frame holds, and
* UNCONFIRMED when no result came within `timeoutMs`: the request may have been answered, and asked again is answered
* the same (service.ts takes a message once). Sent in the queue, waited on outside it: the result comes in through
* `onFrame`, which runs in the queue, and awaited inside it would never arrive.
*/
request(sharedTabId: string, machineId: string, payload: Record<string, unknown>, timeoutMs: number): Promise<Wire> {
// Measured before anything is sent: the gateway would refuse it every time, and the person is told now.
if (!fitsRequest(payload)) return Promise.reject(new MessageError('TOO_LARGE', 'That is too large to send through a shared tab: shorten the message or send to fewer teammates.'))
const rid = randomBytes(REQUEST_ID_LENGTH / 2).toString('hex')
const reply = new Promise<Wire>((resolve, reject) => {
const timer = setTimeout(() => this.settle(rid, new MessageError('UNCONFIRMED', 'That computer did not answer in time.')), timeoutMs)
timer.unref()
this.asking.set(rid, { sharedTabId, machineId, timer, resolve, reject })
})
void this.serial(async () => {
if (this.closed) throw peerAway()
const held = this.held(sharedTabId)
const taken = this.takeovers.get(sharedTabId)
// A relay another socket of this machine took (A5) is not opened again for a while, or at all after the fourth time:
// said so, for the message to wait with a reason rather than be lost in a socket that is not there.
if (taken?.timer || taken?.stopped) throw new MessageError('RELAY_TAKEN', 'Another Harness on this computer holds the shared tab\'s connection.')
// Only a machine with a harness in the tab: a message goes to harnesses, and a session only to a machine listed.
const userId = held.roster.harnesses.find((h) => h.machineId === machineId)?.accountId
if (!userId) throw new MessageError('NOT_IN_TAB', 'That computer is not in the shared tab.')
const frame = { ...payload, kind: 'agent_messages', rid }
if (!await this.ensure(held.roster, machineId, userId) || !await this.sealTo(held.roster, machineId, frame)) throw peerAway()
}).catch((error: Error) => this.settle(rid, error))
return reply
}
/** A request ends: answered, refused, or given up on. Its result, or its end, counts once. */
private settle(rid: string, outcome: Wire | Error): void {
const waiting = this.asking.get(rid)
if (!waiting) return
this.asking.delete(rid)
clearTimeout(waiting.timer)
if (outcome instanceof Error) waiting.reject(outcome)
else waiting.resolve(outcome)
}
/** What waits on a tab, or on one machine of it, can no longer be answered: given up on at once, not at its timeout. */
private giveUp(sharedTabId: string | null, machineId?: string): void {
for (const [rid, p] of [...this.asking]) {
if ((sharedTabId === null || p.sharedTabId === sharedTabId) && (machineId === undefined || p.machineId === machineId)) this.settle(rid, peerAway())
}
}
/** Another machine's request, answered beside the queue (the service may read the tabs first) and sealed back. A
* request with no id that can be its answer's is not answered at all. */
private answerFrame(id: string, from: TabContext['from'], frame: Wire): void {
const { kind: _kind, rid, ...payload } = frame
if (typeof rid !== 'string' || rid.length > 64) return
const answer = this.deps.answer ?? (async () => { throw new MessageError('UNKNOWN_ACTION', 'Unknown Agent Messages request.') })
void Promise.resolve().then(() => answer({ sharedTabId: id, from }, payload))
.catch((error: unknown) => (error instanceof MessageError ? { error: error.code, detail: error.message }
: { error: 'MESSAGES_UNAVAILABLE', detail: 'Agent Messages are unavailable on that computer right now.' }))
.then((reply) => this.serial(async () => {
const held = this.deps.store.current(id)
// The tab gone, or the tabs asleep, while the answer was made: there is no session to seal it for.
if (held && !this.closed) await this.sealTo(held.roster, from.machineId, { ...reply, kind: 'agent_messages_result', rid })
}))
}
// ── frames ────────────────────────────────────────────────────────────────────────────────────────
onFrame(event: TabFrame): Promise<void> {
return this.serial(async () => { if (!this.closed) await this.heard(event) })
}
private async heard(e: TabFrame): Promise<void> {
const id = e.sharedTabId, held = this.deps.store.current(id)
if (!held) return
// 4403: the relay no longer admits this machine to the tab (removed, left elsewhere, or sharing stopped). Only the
// relay's word: in a tab another account owns, the pin stays (`drop`), and a backend that closed the tab when it was
// not stopped cannot have the person trust a new key on first use. This account's own tabs trust its machines' keys
// (`retake`), not a pin, and forget it as before; so does a computer that cannot read its account just now (a
// restart before the core answers), rather than leave a tab it was removed from running.
if (e.closed) {
if (e.closed.code === 4403) {
this.notice({ sharedTabId: id, kind: 'removed', ownerEmail: ownerEmailOf(held.roster) })
const me = await this.self().catch(() => null)
this.drop(id, !!me && held.roster.owner.accountId !== me.accountId)
}
else if (e.closed.code === 4409) this.takenOver(id, ownerEmailOf(held.roster))
return
}
if (e.ready) return this.flush(id)
if (e.undeliverable) {
// Never reached: the next try may say hello again at once, without waiting for an answer that cannot come; and a
// request to that machine will get none.
const link = this.links.get(`${id}:${e.undeliverable}`)
if (link && link.state !== 'open') this.links.delete(`${id}:${e.undeliverable}`)
this.giveUp(id, e.undeliverable)
return
}
const from = e.from, payload = record(e.payload)
if (!from || !payload) return
const k = `${id}:${from.machineId}`, link = this.links.get(k)
if (payload.__e2e !== undefined) {
const opened = link?.state === 'open' && link.userId === from.userId ? await this.deps.key.open(linkOf(link), payload) : { lost: true as const }
if ('frame' in opened) return this.dispatch(id, from, link!, opened.frame)
if ('unreadable' in opened) return
// Sealed with a session this side does not have (its gateway restarted, or it never had one): start another.
if (link?.state === 'open') { link.state = 'idle'; link.at = -Infinity }
await this.ensure(held.roster, from.machineId, from.userId)
return
}
const authority = await this.owns(held.roster)
if (payload.kind === 'hello') {
// Refused before anything is opened: a machine the roster does not list, under the account the relay stamped.
const pub = peerKey(held.roster, from.machineId, from.userId, payload.pub, authority), hello = record(payload.hello)
if (!pub || !hello) return
const tl = { sharedTabId: id, machineId: from.machineId, peerPub: pub }
const answer = await this.deps.key.accept(tl, hello)
if (!('welcome' in answer)) return
this.links.set(k, { ...tl, userId: from.userId, state: 'open', at: this.now() })
await this.deps.relay.send(id, from.machineId, { kind: 'welcome', welcome: answer.welcome, to: hello.ephemeral })
await this.opened(id, from.machineId, held)
} else if (payload.kind === 'welcome') {
const welcome = record(payload.welcome)
if (link?.state !== 'hello' || link.userId !== from.userId || !welcome || payload.to !== link.hello) return
if (await this.deps.key.welcome(linkOf(link), welcome)) {
link.state = 'open'
await this.opened(id, from.machineId, held)
return
}
// The hello is spent (its finish is one-shot): another, once the last is old enough.
link.state = 'idle'
await this.ensure(held.roster, from.machineId, from.userId)
} else if (payload.kind === 'knock') {
// The sender has no session with this machine: whatever this side has is stale.
if (link?.state === 'open') this.forget(k, link)
await this.ensure(held.roster, from.machineId, from.userId, payload.pub)
}
}
private async dispatch(id: string, from: { machineId: string; userId: string }, link: Link, frame: Wire): Promise<void> {
const held = this.held(id)
if (frame.kind === 'roster') {
// Only the owner's account signs a roster and sends it; a member never does. Taken from any session, a member's
// machine sending a parseable roster with a bad signature 20 times a second had every one recorded as an alert,
// the file written and Share woken each time (final review of 1b).
if (from.userId !== held.roster.owner.accountId) return
const signed = signedOf(frame.signed)
if (!signed || parseRoster(signed.body)?.sharedTabId !== id) return
const offered = this.deps.store.offer(signed)
if ('roster' in offered) await this.adopt(offered.roster)
} else if (frame.kind === 'roster_request') {
await this.apply(id, from, link, frame)
} else if (frame.kind === 'roster_refused') {
const r = typeof frame.id === 'string' ? this.queue.get(`${id}:${frame.id}`) : undefined
if (!r || from.machineId !== held.roster.owner.machineId) return
this.queue.delete(`${id}:${r.id}`)
this.persist()
this.notice({ sharedTabId: id, kind: 'refused', error: String(frame.error).slice(0, 64), machineId: r.harness.machineId, agentId: r.harness.agentId })
this.timed()
} else if (frame.kind === 'agent_messages') {
this.answerFrame(id, from, frame)
} else if (frame.kind === 'agent_messages_result') {
const waiting = typeof frame.rid === 'string' ? this.asking.get(frame.rid) : undefined
// Only the machine it was asked of, through the tab it went through, answers a request.
if (!waiting || waiting.sharedTabId !== id || waiting.machineId !== from.machineId) return
const { kind: _kind, rid, ...reply } = frame
this.settle(String(rid), reply)
}
}
}