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
/**
* Keeps this machine in step with its account's device key log (deviceLog.ts) and turns what the log
* says into trust: every key the log leaves active is trusted here, through the same path a trust-group
* member is (GroupSyncer), and every key a `remove` takes out is forgotten.
*
* - register(): this machine's own key goes into the log, once per sign-in — so an existing sign-in,
* from before the log existed, joins it with no action from anyone.
* - refresh(): read the log from the head this machine already verified; verify every new entry.
* A backend that rewrote the log (a different entry at a position already verified) or rolled it
* back (a head older than one verified) FREEZES it here: no key is added from the log until someone
* looks at what changed and trusts it again (rebaseline). Removals still take effect.
* - gossip: the head rides every `group_sync`, so two devices shown different logs find out, and a
* device that is behind is handed the entries it is missing (a removal the backend held back).
* - announce: an `add` past the point this machine joined the log is a "New device: X" and stays
* `pending` until someone marks it seen — the one way a device added by whoever got hold of the
* account (or by the backend itself) is seen. Decided from the log alone, never from what the trust
* group already holds: a roster that outran the log must not hide it.
* - history: what the log says about every add and remove, as this machine verified it.
* - confirm: "It's mine" here (`dismiss` with `confirm`) is signed and shared beside the log
* (deviceAck.ts), and one another trusted device shared takes a key off `pending` here — so the person
* confirms a new device once, on any of their devices, not on every one.
*/
import {
applyDevLogEntries, compareDevLogHead, DevLogError, devLogHash, devLogMessage, emptyDevLogState, nextDevLogEntry,
parseDevLogEntry, signDevLogEntry, type DevLogEntry, type DevLogHead, type DevLogMember, type DevLogState,
} from './deviceLog.js'
import { checkDevAck, DEVACK_VERSION, signDevAck, type DevAck } from './deviceAck.js'
import {
DEVLOG_DEPARTED, DEVLOG_RECENT, type DevLogConfirmed, type DevLogConflict, type DevLogDeparted, type DevLogFile, type DevLogFreeze,
type DeviceLogStore,
} from './deviceLogStore.js'
import { devLogHistory, type DevLogHistoryRow } from './deviceHistory.js'
import { b64d, fingerprint, verify } from './core.js'
export interface DeviceLogFetched { acct: string; head: DevLogHead; entries: unknown[] }
export type DeviceLogAppendAnswer = { head: DevLogHead } | { error: string; head?: DevLogHead }
/** A sign-in by hand, as this machine's session records it (authSession `signInOf`) — never anything
* the backend sends. */
export interface DevLogSignIn {
/** Which sign-in it is. */
epoch: string
/** Given to a session from before sign-ins were recorded, or a Team sign-in's (authSession `teamSignInEpoch`):
* nobody saw it being made by hand here, so it never starts the log over (it may take a file over). */
adopted: boolean
/** When it was made (ms); null when not known — then it never starts the log over either. */
at: number | null
/** The account it was made to, as the backend named it right after (authSession `signInAcct`); absent
* when that could not be asked (then only DEVLOG_RESET_WINDOW_MS opens the door), never for an
* adopted one. */
acct?: string | null
}
/** How long after a sign-in by hand a read of another account may start the log over: past it, with
* no read of that account yet, the backend has had the time to pick when it says so. */
export const DEVLOG_RESET_WINDOW_MS = 10 * 60_000
export interface DeviceLogSyncerDeps {
store: DeviceLogStore
/** This machine's identity: base64 public key and the private key that signs for it. */
identity: () => { pub: string; priv: Uint8Array }
/** How this machine describes itself in the log; no machineId = not signed in, nothing to register. */
self: () => { machineId: string | null; label: string }
/** Which sign-in by hand this machine is under; null when not known. The log of another account is
* started (or a kept one restored) only when this changed AND the backend's account differs AND it is
* the account that sign-in was made to, or it was made less than DEVLOG_RESET_WINDOW_MS ago — never
* for an adopted one. Otherwise a different account id from the backend freezes the log. While the
* file is not this sign-in's yet (no read of it so far), what peers gossip is not taken either. */
signIn: () => DevLogSignIn | null
/** The log from `since`; null when the backend has none to give (an older backend, or unreachable). */
fetch: (since: number) => Promise<DeviceLogFetched | null>
/** Append one signed entry; null when the backend could not be reached. */
append: (entry: DevLogEntry) => Promise<DeviceLogAppendAnswer | null>
/** The acknowledgements ("It's mine", deviceAck.ts) of keys added after entry `since`, as the backend
* keeps them — unchecked: every one is judged here. null when there are none to read (a backend from
* before them answers 404, which is null too). Absent: none are ever read. */
fetchAcks?: (since: number) => Promise<unknown[] | null>
/** Keep one acknowledgement this machine signed; false when the backend did not take it. Absent: none
* is shared, and "It's mine" here stays here. */
postAck?: (ack: DevAck) => Promise<boolean>
/** This machine is moving from one account's log to another's (a sign-in by hand, or a review of the
* other account's list): put away what `from` trusted here and bring back what `to` did. Called before
* the new log is written, so what it snapshots as already trusted (`trustedNow`) is `to`'s. */
switchAccount?: (from: string, to: string) => void
/** Trust these keys here (and tell the trust group, so devices that predate the log learn of them). */
adopt: (members: DevLogMember[]) => void
/** Stop trusting a key here (and tombstone it in the trust group). */
drop: (pub: string) => void
/** The keys this machine trusts right now: snapshotted once, when it joins the log (or migrates to
* this version), so what it already knew then is never news. */
trustedNow: () => string[]
/** Whether the trust group holds a removal for `pub` that predates the log. */
tombstoned: (pub: string) => boolean
/** Whether this machine's user unpaired `pub` here — a local override the log never beats. */
blocked: (pub: string) => boolean
/** Whether `pub` may open a session here right now (it is paired). Given, every read of the log trusts
* again an active key that is not: one the adoption of its entry missed stays trusted by no one. */
isTrusted?: (pub: string) => boolean
/** A key joined the log after this machine did: "New device: X". */
announce: (member: DevLogMember) => void
/** A device was taken out of the log after this machine joined (not by this machine). */
removed?: (notice: DeviceRemovalNotice) => void
/** Another key holds this machine's id in the log (first time that holder is seen). */
conflict?: (conflict: DevLogConflict) => void
/** A fork split the lists: stop trusting these keys here until `rebaseline`. */
suspend?: (pubs: string[]) => void
/** `rebaseline` cleared the suspension: trust the roster again. */
resume?: () => void
/** This machine's own key was removed from the log: it is signed out. */
signedOut: () => void
/** When each key last opened a session or read the log, from the backend; null when it could not
* be asked. Only `sweepStale` reads it. */
seen?: () => Promise<DeviceKeysSeen | null>
/** Something a window shows changed (the list, the frozen line). */
changed?: () => void
log?: (line: string) => void
now?: () => number
sleep?: (ms: number) => Promise<void>
}
export interface DeviceLogListing {
head: DevLogHead | null
frozen: DevLogFreeze | null
self: string
/** `confirmed`: another trusted device said "It's mine" for it while it was new here — which, and when. */
members: Array<DevLogMember & { fingerprint: string; self: boolean; firstSeen?: number; pending: boolean; suspended: boolean; confirmed?: DevLogConfirmed }>
/** Machines whose own copy of the log is frozen, as their last `group_sync` said. */
frozenPeers: string[]
/** Keys that joined after this machine did and nobody has marked as seen. */
pending: string[]
/** Keys not trusted here after a fork, until `rebaseline`. */
suspended: string[]
joinedSeq: number
/** The keys that were on the account before this machine joined (the "Already on your account" list):
* active, not this machine, at or before `joinedSeq` — plus any key this machine already trusted at
* joining whose entry came after it (a log cut short at the first read must not hide it). */
baseline: string[]
/** false until the "already on your account" list was acknowledged. */
baselineSeen: boolean
/** Another key holds this machine's id (and still does). */
conflict: DevLogConflict | null
/** New keys removed before anyone marked them as seen: flagged until dismissed (oldest first). */
departed: DevLogDeparted[]
/** Why the backend last refused this machine's own key (`TOO_MANY`, …), until a register gets through.
* Without it a refusal only reached the daemon's log, and the machine just stayed "not registered". */
registerError?: string
}
/** A device taken out of the account's log after this machine joined it. */
export interface DeviceRemovalNotice {
pub: string
label: string
kind: DevLogMember['kind']
fingerprint: string
signer: string
signerLabel: string
signerFingerprint: string
/** The signer is itself a new device nobody has looked at. */
signerPending: boolean
/** The device removed itself (signed out). */
selfRemoved: boolean
at: number
}
export interface DeviceLogHistory {
rows: DevLogHistoryRow[]
/** false when only part of the log could be read (offline). */
complete: boolean
frozen: DevLogFreeze | null
}
/** What `trustFromLog` made of a key: trusted, or why not. */
export type DeviceLogTrustOutcome = 'trusted' | 'self' | 'absent' | 'suspended' | 'blocked' | 'tombstoned' | 'frozen' | 'unavailable'
export type DeviceLogRemoveResult = { ok: true } | { ok: false; error: 'NOT_ACTIVE' | 'NOT_IN_LOG' | 'UNAVAILABLE' | 'REFUSED'; detail?: string }
/** `rebaseline(confirm, head)` refused: the backend's list is no longer the one that was previewed
* (`LOG_CHANGED`), or it is another account's while the log this machine keeps is the one of the
* sign-in it is under (`OTHER_ACCOUNT`: only a sign-in switches accounts). */
export interface DeviceLogRebaselineChanged { error: 'LOG_CHANGED' | 'OTHER_ACCOUNT' }
export interface DeviceLogRebaseline {
head: DevLogHead
added: DevLogMember[]
removed: DevLogMember[]
}
const APPEND_ATTEMPTS = 5
const PAGES = 20
/** The page cap of a first read of a log (and of a review): 100,000 entries. At PAGES a log past 10,000
* entries ended its join part-way, and every key after the cut was announced as a new device. */
const JOIN_PAGES = 200
/** `sweepStale`: an app key unused this long, and added at least this long ago, is taken out of the log —
* a browser whose storage was cleared, an app reinstalled, never comes back for its key, and at 256
* active keys (DEVLOG_MAX_ACTIVE) no new device can join the account. */
export const STALE_AFTER_MS = 180 * 24 * 60 * 60_000
/** When each key was last used (ms, by pub), and since when that record runs (null: unknown). A key with
* no time is unused only if the record is older than the question: a Redis that came back empty once
* read as "no app used in months", and the sweep would have removed every old app key. */
export interface DeviceKeysSeen { seen: Record<string, number>; since: number | null }
/** At most one sweep per this long on a machine; the timer that offers it runs every 10 minutes. */
const SWEEP_EVERY_MS = 6 * 60 * 60_000
/** At most this many removals per sweep (the next one goes on), each SWEEP_GAP_MS apart: the backend
* takes 10 appends a minute from a machine, and a person's own `devices remove` must still get through. */
const SWEEP_MAX = 20
const SWEEP_GAP_MS = 10_000
/** How much later each next machine (by key order) takes over a sweep the ones before it have not done. */
const SWEEP_TURN_MS = 24 * 60 * 60_000
/** The newest hashes a `group_sync` carries, so a fork can be located. */
const GOSSIP_HASHES = 64
interface Known { label: string; kind: DevLogMember['kind'] }
const fp = (pub: string): string => fingerprint(b64d(pub))
const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10)
const uniq = (xs: readonly string[]): string[] => [...new Set(xs)]
/**
* Where a peer's log first differs from `state`: the first seq, in the window of hashes the peer sent
* (`theirs.hashes`, with `theirs.head` the last of them), whose hash is not ours — only when the entry
* before it matches (or it is the first), so the split is proven rather than guessed. null when the peer
* sent no usable hashes, nothing in the shared window differs, or the split lies before the window.
*/
export function devLogDivergence(state: DevLogState, theirs: unknown): number | null {
if (!theirs || typeof theirs !== 'object') return null
const { head, hashes } = theirs as { head?: { seq?: unknown; hash?: unknown }; hashes?: unknown }
if (!Array.isArray(hashes) || !hashes.length || hashes.length > 4 * GOSSIP_HASHES) return null
const window = new Map<number, string>()
let prev = 0
for (const h of hashes) {
if (!h || typeof h !== 'object') return null
const { seq, hash } = h as { seq?: unknown; hash?: unknown }
if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 1 || typeof hash !== 'string' || hash.length > 128) return null
if (prev !== 0 && seq !== prev + 1) return null
prev = seq
window.set(seq, hash)
}
// The window must end where the peer's head is, or it describes some other log.
if (!head || head.seq !== prev || head.hash !== window.get(prev)) return null
const first = Math.min(...window.keys())
for (const [seq, hash] of window) {
if (seq > state.head.seq || state.hashes[seq - 1] === hash) continue
if (seq === 1) return 1
if (seq === first) return null
return state.hashes[seq - 2] === window.get(seq - 1) ? seq : null
}
return null
}
export class DeviceLogSyncer {
private readonly now: () => number
private readonly sleep: (ms: number) => Promise<void>
private refreshing: Promise<void> | null = null
private readonly frozenPeers = new Map<string, boolean>()
private readonly removing = new Set<string>()
private readonly inFlightRemovals = new Map<string, Promise<DeviceLogRemoveResult>>()
/** The history walk in progress, which a second `history()` joins. */
private historying: Promise<DeviceLogHistory> | null = null
/** Every entry fetched for the history so far (seq 1..n), this run only: never written to disk. */
private histCache: { acct: string; entries: DevLogEntry[] } | null = null
/** Why the backend last refused this machine's own key; this run only (the file format stays as older
* versions read it). */
private registerError: string | null = null
/** When `sweepStale` last ran here (ms); this run only. */
private lastSweep: number | null = null
constructor(private readonly deps: DeviceLogSyncerDeps) {
this.now = deps.now ?? (() => Date.now())
this.sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
}
/** Read the log and put this machine's own key into it. Never throws. */
async register(): Promise<void> {
try {
const self = this.deps.self()
if (!self.machineId) return
await this.refresh()
const { pub, priv } = this.deps.identity()
for (let attempt = 0; attempt < APPEND_ATTEMPTS; attempt++) {
const file = this.marks()
const state = file.state
if (!state || file.frozen) return
if (state.removed.includes(pub)) { this.deps.signedOut(); return }
const mine = state.active[pub]
if (mine) {
this.registerError = null
this.clearConflict()
if (mine.label === self.label || mine.machineId !== self.machineId) return
} else {
const taken = Object.values(state.active).find((m) => m.kind === 'machine' && m.machineId === self.machineId)
if (taken) { this.noteConflict(file, taken); return }
}
const entry = signDevLogEntry(nextDevLogEntry(state, {
op: 'add', pub, kind: 'machine', machineId: self.machineId, label: self.label, signer: pub,
}, this.now()), priv)
const answer = await this.deps.append(entry)
if (!answer) return
if ('head' in answer && !('error' in answer)) { this.registerError = null; await this.refresh(); return }
if (answer.error !== 'STALE_HEAD') {
this.registerError = answer.error
this.deps.log?.(`[devlog] register refused: ${answer.error}`)
this.deps.changed?.()
return
}
await this.refresh()
await this.sleep(200 + Math.floor(Math.random() * 800) * (attempt + 1))
}
} catch (err) {
this.deps.log?.(`[devlog] register failed: ${err instanceof Error ? err.message : String(err)}`)
}
}
/** Read and verify whatever the log gained. Concurrent calls share one read. Never throws. */
refresh(): Promise<void> {
if (this.refreshing) return this.refreshing
this.refreshing = this.doRefresh()
.catch((err) => { this.deps.log?.(`[devlog] refresh failed: ${err instanceof Error ? err.message : String(err)}`) })
.finally(() => { this.refreshing = null })
return this.refreshing
}
/**
* Read the log now and trust `pub` if it is on it: a hello from a key not paired here may be a device
* that joined the account after this machine last read the log (a browser signed in before this machine
* did), and without this it is denied until the next scheduled read. Says why not otherwise. Never throws.
*/
async trustFromLog(pub: string): Promise<DeviceLogTrustOutcome> {
try {
// A read already on its way may have fetched before this key was added: wait for it, then read again.
const earlier = this.refreshing
await this.refresh()
if (earlier) await this.refresh()
const file = this.deps.store.read()
if (file.frozen) return 'frozen'
const state = file.state
if (!state) return 'unavailable'
const member = state.active[pub]
if (!member) return 'absent'
if (pub === this.deps.identity().pub) return 'self'
if (this.suspendedKeys().includes(pub)) return 'suspended'
if (this.deps.blocked(pub)) return 'blocked'
if (this.deps.tombstoned(pub)) return 'tombstoned'
this.trustState(state, [member])
return 'trusted'
} catch (err) {
this.deps.log?.(`[devlog] could not read the log for a key: ${err instanceof Error ? err.message : String(err)}`)
return 'unavailable'
}
}
/** The file, with the joined point filled in for one written before it existed (or by a client that
* dropped it): everything up to what was already announced is then known, as it was. */
private marks(): DevLogFile {
const file = this.deps.store.read()
if (!file.state || file.joinedSeq !== undefined) return file
const next: DevLogFile = {
...file, joinedSeq: file.notifiedUpTo, preLog: this.deps.trustedNow(), pending: [], announced: [], baselineSeen: true,
}
this.deps.store.write(next)
return next
}
/** Whether `local` — a sign-in by hand the file is not yet the log of — may start it over for another
* account: never an adopted one, and only shortly after it was made. A backend that holds back the
* log after a sign-in must not keep that door open, to name another account days later. */
private mayStartOver(local: DevLogSignIn): boolean {
return !local.adopted && local.at !== null && Math.abs(this.now() - local.at) <= DEVLOG_RESET_WINDOW_MS
}
/** Whether the trust group may swap rosters now: the log is this sign-in's (or none was read yet) and
* not frozen on an account it was not signed in to. Before that the roster here may still be the
* account this machine just left, and handing it out would carry its devices into the new one. */
current(): boolean {
const file = this.deps.store.read()
return !file.state || (this.ownsFile(file) && file.frozen?.reason !== 'invalid')
}
/** Whether the file is the log of the sign-in this machine is under (or that cannot be told). Until a
* read of it under a new sign-in, it may be another account's: what a peer says is not judged
* against it — a peer of the new account would read as a fork of the old one. */
private ownsFile(file: DevLogFile): boolean {
const local = this.deps.signIn()
return local === null || file.owner === local.epoch
}
private archiveDeparting(file: DevLogFile): void {
const epoch = this.deps.signIn()?.epoch ?? ''
// Team agents must not inherit the departing owner's device names, keys or trust decisions.
this.deps.store.archive(file, { forget: epoch.startsWith('team:') || epoch.startsWith('adopted:team:') })
}
/** `file`, with every key a fork suspended in another account's kept log, and active in this one,
* suspended (and new) here as well: it is not trusted either way, so the list says so — and "It's
* mine" lifts it, everywhere (a review of this list does not: it never showed that suspension). */
private carrySuspensions(file: DevLogFile): DevLogFile {
const state = file.state
if (!state) return file
const selfPub = this.deps.identity().pub
const current = file.suspended ?? []
const carried = this.deps.store.archivedSuspended().filter((k) => !!state.active[k] && k !== selfPub && !current.includes(k))
if (!carried.length) return file
return { ...file, suspended: [...current, ...carried], pending: uniq([...(file.pending ?? []), ...carried]) }
}
/** `gone`, just taken out by `e`, kept flagged: it was new here and nobody had looked at it yet. */
private departedOf(gone: DevLogMember, e: DevLogEntry, signerLabel: string): DevLogDeparted {
return {
pub: gone.pub, label: gone.label, kind: gone.kind, machineId: gone.machineId, fingerprint: fp(gone.pub), addedAt: gone.addedAt,
removedAt: e.at, removedBy: e.signer, removedByLabel: signerLabel, selfRemoved: e.signer === gone.pub,
}
}
/** `prev` plus `more` (a key once, at its newest), the oldest dropped past DEVLOG_DEPARTED. */
private withDeparted(prev: DevLogDeparted[] | undefined, more: readonly DevLogDeparted[]): { departed?: DevLogDeparted[] } {
if (!more.length) return prev ? { departed: prev } : {}
const pubs = new Set(more.map((d) => d.pub))
return { departed: [...(prev ?? []).filter((d) => !pubs.has(d.pub)), ...more].slice(-DEVLOG_DEPARTED) }
}
/** What a review (`rebaseline --yes`) takes out that was new here and never looked at: a key pending
* in `base` that the reviewed list does not keep — and a key the list added and removed again at
* entries this machine never verified (while it was frozen) — stays flagged as departed. */
private reviewDeparted(
base: DevLogFile, next: DevLogState, parsed: readonly DevLogEntry[], removed: readonly DevLogMember[], selfPub: string, preLog: ReadonlySet<string>,
): DevLogDeparted[] {
const verified = base.state
if (!verified) return []
const pending = base.pending ?? []
const known = new Map<string, Known>()
const adds = new Map<string, DevLogEntry>()
const out = new Map<string, DevLogDeparted>()
for (const e of [...parsed].sort((a, b) => a.seq - b.seq)) {
if (e.op === 'add') {
if (!known.has(e.pub)) adds.set(e.pub, e) // added (not renamed)
known.set(e.pub, { label: e.label, kind: e.kind })
continue
}
const was = removed.find((m) => m.pub === e.pub)
const add = adds.get(e.pub)
const label = known.get(e.pub)?.label
known.delete(e.pub)
if (e.pub === selfPub || next.active[e.pub]) continue
// Added at an entry this machine never verified, and gone again before it could see it.
const unseen = !was && !!add && verified.hashes[add.seq - 1] !== devLogHash(add) && !preLog.has(e.pub) && !this.deps.blocked(e.pub)
if ((was && pending.includes(e.pub)) || unseen) {
const member: DevLogMember = was ?? { pub: e.pub, kind: add!.kind, machineId: add!.machineId, label: label ?? add!.label, addedAt: add!.at, seq: add!.seq }
out.set(e.pub, this.departedOf(member, e, known.get(e.signer)?.label ?? ''))
}
}
// Pending here, and not on the reviewed list at all (a branch the backend no longer serves).
for (const m of removed) {
if (out.has(m.pub) || m.pub === selfPub || !pending.includes(m.pub)) continue
out.set(m.pub, {
pub: m.pub, label: m.label, kind: m.kind, machineId: m.machineId, fingerprint: fp(m.pub), addedAt: m.addedAt,
removedAt: this.now(), removedBy: '', removedByLabel: '', selfRemoved: false,
})
}
return [...out.values()]
}
/** The first read of the log has reached its head (or stopped): what is verified from here on is news. */
private endJoin(): void {
const file = this.deps.store.read()
if (!file.joining) return
const { joining: _j, ...rest } = file
this.deps.store.write(rest)
}
/** Another key holds this machine's id: remember it, and say so the first time that holder is seen. */
private noteConflict(file: DevLogFile, holder: DevLogMember): void {
if (file.conflict?.pub === holder.pub) return
const conflict: DevLogConflict = {
pub: holder.pub, label: holder.label, machineId: holder.machineId, addedAt: holder.addedAt, seq: holder.seq,
fingerprint: fp(holder.pub), afterJoin: holder.seq > (file.joinedSeq ?? 0),
}
this.deps.store.write({ ...file, conflict })
const who = `${conflict.label || '(no name)'} (${conflict.fingerprint})`
this.deps.log?.(conflict.afterJoin
? `[devlog] ⚠ another key took this computer's place on your account after it joined: ${who} — if you did not set up Harness here again, remove that key from another device now`
: `[devlog] this computer is held by another key on your account: ${who} — if that was an earlier install of this computer, remove it from another device; this computer joins on its own once it is gone`)
this.deps.conflict?.(conflict)
this.deps.changed?.()
}
private clearConflict(): void {
const file = this.deps.store.read()
if (!file.conflict) return
const { conflict: _gone, ...rest } = file
this.deps.store.write(rest)
this.deps.changed?.()
}
private async doRefresh(): Promise<void> {
try {
await this.readPages()
} finally {
// However the read ended — at the head, on a freeze, or cut short (no answer, the page cap) — the
// first read of a log is over: what is verified from here on is news. Held open, a backend that
// stalls the second page would have every key it adds later taken for one there at joining.
this.endJoin()
}
this.reconcile()
// After the entries, so a key added and confirmed while this machine was away is first announced, as
// every new key is — the one-time "New device: X" never waits on, or is skipped for, anyone's word —
// and only then taken off the list.
await this.applyAcks()
}
/**
* Trust again every key the log leaves active that is not trusted here. A key is adopted as its entry is
* verified, and only then: the head is written first, so an adoption that threw, a process that died in
* between, or a roster that already held the member (nothing new to merge, so nothing trusted) left it
* untrusted for good — its device saw "Link required" however often it came back. Never announces: what
* is news was decided when the entry was read. Never throws.
*/
private reconcile(): void {
const isTrusted = this.deps.isTrusted
if (!isTrusted) return
try {
const file = this.deps.store.read()
const state = file.state
if (file.frozen || !state) return
const selfPub = this.deps.identity().pub
const missing = Object.values(state.active).filter((m) => m.pub !== selfPub && !isTrusted(m.pub))
const adopted = this.trustState(state, missing)
if (adopted.length) this.deps.log?.(`[devlog] trusting ${adopted.length} key(s) the log has and this machine did not: ${adopted.map((m) => fp(m.pub)).join(', ')}`)
} catch (err) {
this.deps.log?.(`[devlog] could not trust what the log has: ${err instanceof Error ? err.message : String(err)}`)
}
}
private async readPages(): Promise<void> {
this.marks()
// The first read of a log (a new install, or an existing sign-in from before the log existed) only
// learns what is there: every key it adopts, and none of it is news (it is before `joinedSeq`).
let bootstrap = !this.deps.store.read().state?.head.seq
// The cap is read each page: a first read only learns what is there, so it may go far; once it is
// over (`endJoin`, unconditional below) a stalled or endless backend gets the usual PAGES.
for (let page = 0; page < (this.deps.store.read().joining ? JOIN_PAGES : PAGES); page++) {
const file = this.deps.store.read()
const since = file.state?.head.seq ?? 0
const got = await this.deps.fetch(since)
if (!got) return
// A head that is not a position is the backend lying (or broken): nothing to verify it against.
if (!Number.isSafeInteger(got.head.seq) || got.head.seq < 0) return
const latest = this.deps.store.read()
const now = latest.state
if (file.state && now && now.acct === got.acct
&& (file.state.acct !== now.acct || file.state.head.seq !== now.head.seq || file.state.head.hash !== now.head.hash)) {
// The log moved here while this page was on its way (a peer handed over its tail): judged
// against the newer head the page would read as a rollback, or as entries out of order. Ask
// again from where the log is now.
continue
}
const local = this.deps.signIn()
let reset = !now
if (now) {
const signedInAgain = local !== null && latest.owner !== local.epoch
if (now.acct !== got.acct) {
// Another account only after a sign-in by hand here: the account it was made to, whenever; with
// none recorded, any one right after it. Otherwise it is the backend saying so — and starting
// over would clear every mark a fork put on the list, the real log then adopted whole.
if (!signedInAgain || (local.acct ? local.acct !== got.acct : !this.mayStartOver(local))) {
this.freeze('invalid')
return
}
reset = true
} else if (signedInAgain) {
// Signed in again to the same account: the same list, now this sign-in's.
this.deps.store.write({ ...latest, owner: local.epoch })
}
}
if (reset) {
if (now) {
// Ordinary sign-ins keep the departing trust and log; Team sign-ins discard them.
this.deps.switchAccount?.(now.acct, got.acct)
this.archiveDeparting(latest)
}
// Back to an account this machine was signed in to before: its log as verified then, and every
// mark on it (frozen, suspended, pending), go on from where they were.
const kept = this.deps.store.restore(got.acct, (k) => this.carrySuspensions({ ...k, ...(local ? { owner: local.epoch } : {}) }))
if (kept) {
bootstrap = !kept.state?.head.seq
continue
}
// First read, or signed in to another account here: that account's log starts from nothing.
// `joinedSeq` starts at 0 and follows the head of each page this machine VERIFIES (accept):
// never the head the backend merely claims, or it could park it far ahead and have every key
// it forges below that adopted without a word. `preLog` is what was trusted already.
const fresh: DevLogFile = {
state: emptyDevLogState(got.acct), recent: [], frozen: null, notifiedUpTo: 0,
joinedSeq: 0, preLog: this.deps.trustedNow(), pending: [], announced: [], suspended: [], baselineSeen: false,
joining: true, ...(local ? { owner: local.epoch } : {}),
}
this.deps.store.write(fresh)
bootstrap = true
if (got.head.seq === 0) return
if (since !== 0) continue
}
const current = this.deps.store.read()
const state = current.state!
// A log frozen as `invalid` from a page that claimed a head past the entries it carried heals by itself once the
// backend serves them: the backend did that whenever a device registered between its two reads, and froze every
// device that read at that moment until someone ran `harness devices rebaseline` (#1789, fixed 2026-10-27; a Mac
// frozen on 10-24 could never link its Harness Team account). The entries must continue the chain this machine
// verified and check out one by one (`accept`), or it stays frozen. A rollback or a fork never heals on its own.
const heals = current.frozen?.reason === 'invalid' && got.head.seq > state.head.seq && got.entries.length > 0
if (current.frozen && !heals) { this.looseRemovals(got.entries); return }
if (got.head.seq < state.head.seq) { this.freeze('rollback'); return }
if (got.head.seq === state.head.seq) {
if (got.head.hash !== state.head.hash) this.freeze('fork')
return
}
if (!got.entries.length) { this.freeze('invalid'); return }
if (!this.accept(got.entries, bootstrap)) return
if (heals) this.deps.log?.('[devlog] the device list checks out again: no longer frozen')
if (this.deps.store.read().state!.head.seq >= got.head.seq) return
}
}
/** `firstSeen` plus now for each newly applied key, minus keys no longer active (keeps the file small). */
private stamp(prev: Record<string, number> | undefined, added: readonly DevLogMember[], state: DevLogState): Record<string, number> {
const at = this.now()
const out: Record<string, number> = {}
for (const pub of Object.keys(state.active)) {
const t = prev?.[pub] ?? (added.some((m) => m.pub === pub) ? at : undefined)
if (t !== undefined) out[pub] = t
}
return out
}
/** `keys` cut to the ones still active — the marks never outlive the key. */
private prune(keys: readonly string[] | undefined, state: DevLogState): string[] {
return uniq(keys ?? []).filter((k) => state.active[k] !== undefined)
}
/** The confirmed marks of keys still active, as a file field (none when there are none). */
private keptConfirmed(marks: Record<string, DevLogConfirmed> | undefined, state: DevLogState): { confirmed?: Record<string, DevLogConfirmed> } {
const kept = Object.entries(marks ?? {}).filter(([k]) => state.active[k] !== undefined)
return kept.length ? { confirmed: Object.fromEntries(kept) } : {}
}
/**
* Take off `pending` every key another of the person's trusted devices said "It's mine" for
* (deviceAck.ts), and remember which device did ("Confirmed on <label>").
*
* The backend's word counts for nothing: each acknowledgement must check out against the log as THIS
* machine verified it (signature, a signer active on it, the key added at the entry it names), and
* against this machine's own marks. The key must still be new here and not suspended — an
* acknowledgement never lifts a suspension; only the person does, on this machine, with "It's mine" on
* that very device. The signer must be a device this machine trusts: not new here itself (two new
* devices must not vouch for each other), not suspended, not removed (a departed key is not active),
* not unpaired or tombstoned here, and not this machine (its own "It's mine" already took the key off).
* Nothing is read while the log is frozen or not yet this sign-in's. Never throws.
*/
private async applyAcks(): Promise<void> {
const fetchAcks = this.deps.fetchAcks
if (!fetchAcks) return
try {
const candidates = this.ackable(this.deps.store.read())
// Nothing new here: nothing to ask (and no request at all, on every read, for most of a device's life).
if (!candidates.length) return
const raw = await fetchAcks(Math.min(...candidates.map((m) => m.seq)) - 1)
if (!raw?.length) return
// Judged against the file as it is NOW: the log may have moved, or a key been looked at, meanwhile.
const file = this.deps.store.read()
const state = file.state
const open = new Set(this.ackable(file).map((m) => m.pub))
if (!state || !open.size) return
const selfPub = this.deps.identity().pub
const pending = new Set(file.pending ?? [])
const suspended = new Set(this.suspendedKeys())
const confirmed: Record<string, DevLogConfirmed> = {}
for (const r of raw) {
const checked = checkDevAck(state, r)
if (!checked.ok) continue
const { ack } = checked
if (!open.has(ack.pub) || confirmed[ack.pub]) continue
if (ack.signer === selfPub || pending.has(ack.signer) || suspended.has(ack.signer)
|| this.deps.blocked(ack.signer) || this.deps.tombstoned(ack.signer)) continue
confirmed[ack.pub] = { by: ack.signer, label: state.active[ack.signer].label, at: this.now() }
}
const pubs = Object.keys(confirmed)
if (!pubs.length) return
this.deps.store.write({
...file,
pending: (file.pending ?? []).filter((k) => !confirmed[k]),
...this.keptConfirmed({ ...file.confirmed, ...confirmed }, state),
})
for (const pub of pubs) {
const c = confirmed[pub]
this.deps.log?.(`[devlog] ${state.active[pub].label || '(no name)'} (${fp(pub)}) was confirmed as yours on ${c.label || 'another device'} (${fp(c.by)}): no longer new here`)
}
this.deps.changed?.()
} catch (err) {
// The list stays as it was; the next read asks again.
this.deps.log?.(`[devlog] could not read which devices were confirmed: ${err instanceof Error ? err.message : String(err)}`)
}
}
/** The keys an acknowledgement could take off `pending` in `file`: new here, still active, not
* suspended, not this machine — and none at all from a log that is frozen or not this sign-in's. */
private ackable(file: DevLogFile): DevLogMember[] {
const state = file.state
if (!state || file.frozen || !this.ownsFile(file)) return []
const selfPub = this.deps.identity().pub
const suspended = new Set(this.suspendedKeys())
return uniq(file.pending ?? []).map((k) => state.active[k]).filter((m): m is DevLogMember => !!m && m.pub !== selfPub && !suspended.has(m.pub))
}
/** The notice for a `remove` that took `gone` out, or null when there is nothing to say: this
* machine's own removal, this machine's own key, or a removal from before it joined. `known` says
* what each key was called, and what kind it was, BEFORE this removal — the remove entry's own label
* and kind are the signer's to pick, so they are never what the person is told. */
private removalNotice(e: DevLogEntry, joinedSeq: number, selfPub: string, pending: readonly string[], known: ReadonlyMap<string, Known>): DeviceRemovalNotice | null {
if (e.op !== 'remove' || e.seq <= joinedSeq || e.pub === selfPub || e.signer === selfPub) return null
const was = known.get(e.pub)
return {
pub: e.pub, label: was?.label ?? e.label, kind: was?.kind ?? e.kind, fingerprint: fp(e.pub),
signer: e.signer, signerLabel: known.get(e.signer)?.label ?? '', signerFingerprint: fp(e.signer),
signerPending: pending.includes(e.signer), selfRemoved: e.signer === e.pub, at: this.now(),
}
}
/** What each active key in `state` is called now, to be walked forward through entries. */
private knownOf(state: DevLogState): Map<string, Known> {
return new Map(Object.values(state.active).map((m) => [m.pub, { label: m.label, kind: m.kind }] as const))
}
/** Apply entries that continue this machine's log; freeze on anything that does not. */
private accept(entries: readonly unknown[], bootstrap: boolean): boolean {
const file = this.marks()
// While the first read of this log is open (a peer's tail can arrive between its pages too):
// whatever is verified before it reaches the head is what was there at joining.
const joining = file.joining === true
let applied
try {
applied = applyDevLogEntries(file.state!, entries)
} catch (err) {
if (!(err instanceof DevLogError)) throw err
this.freeze(err.code === 'BROKEN_CHAIN' || err.code === 'OUT_OF_ORDER' ? 'fork' : 'invalid')
return false
}
const selfPub = this.deps.identity().pub
// While joining, everything this page verified is what was there before: the joined point moves up
// to the verified head (never past it), and none of it is news.
const joinedSeq = joining ? applied.state.head.seq : file.joinedSeq ?? 0
const preLog = new Set(file.preLog ?? [])
const parsed = entries.map((e) => parseDevLogEntry(e)).filter((e): e is DevLogEntry => e !== null)
// News is decided from the log alone: an `add` past the point this machine joined, for a key it
// did not already trust then. What the roster or the pins hold now says nothing — a key can reach
// them (over `group_sync`) before this machine reads the entry that adds it.
const news = applied.added.filter((m) =>
m.seq > joinedSeq && m.pub !== selfPub && !preLog.has(m.pub) && !this.deps.blocked(m.pub))
const pendingBefore = file.pending ?? []
const announced = file.announced ?? []
const newHere = [...pendingBefore, ...news.map((m) => m.pub)]
const pending = this.prune(newHere, applied.state)
const toAnnounce = news.filter((m) => !announced.includes(m.pub))
// Walk the entries in order: a removal is described by what the key was called when it was removed.
const known = this.knownOf(file.state!)
const notices: DeviceRemovalNotice[] = []
const gone = new Map(applied.removed.map((m) => [m.pub, m] as const))
const departed: DevLogDeparted[] = []
for (const e of [...parsed].sort((a, b) => a.seq - b.seq)) {
if (e.op === 'add') known.set(e.pub, { label: e.label, kind: e.kind })
else {
const n = this.removalNotice(e, joinedSeq, selfPub, newHere, known)
if (n) notices.push(n)
// A new key nobody looked at, gone again (even within this page): it stays flagged.
const member = gone.get(e.pub)
if (member && newHere.includes(e.pub) && e.pub !== selfPub) departed.push(this.departedOf(member, e, known.get(e.signer)?.label ?? ''))
known.delete(e.pub)
}
}
// The holder of this machine's id left, or this machine got its own key in: the conflict is over.
const conflictOver = !!file.conflict && (!!applied.state.active[selfPub] || !applied.state.active[file.conflict.pub])
// A key taken into the "already on your account" list after that list was acknowledged: show it.
const unseen = joining && file.baselineSeen !== false && applied.added.some((m) => m.pub !== selfPub)
const { conflict: _c, confirmed: _k, ...rest } = file
this.deps.store.write(this.carrySuspensions({
...rest,
...(unseen ? { baselineSeen: false } : {}),
...(file.conflict && !conflictOver ? { conflict: file.conflict } : {}),
state: applied.state,
joinedSeq,
recent: [...file.recent, ...parsed].slice(-DEVLOG_RECENT),
frozen: null,
notifiedUpTo: applied.state.head.seq,
firstSeen: this.stamp(file.firstSeen, applied.added.filter((m) => m.seq > joinedSeq), applied.state),
pending,
announced: this.prune([...announced, ...toAnnounce.map((m) => m.pub)], applied.state),
suspended: this.prune(file.suspended, applied.state),
...this.withDeparted(file.departed, departed),
...this.keptConfirmed(file.confirmed, applied.state),
}))
this.trustState(applied.state, bootstrap ? Object.values(applied.state.active) : [...applied.added, ...applied.relabeled])
for (const m of applied.removed) this.deps.drop(m.pub)
for (const m of toAnnounce) this.deps.announce(m)
for (const n of notices) this.deps.removed?.(n)
if (applied.state.removed.includes(selfPub)) this.deps.signedOut()
void this.carryOverTombstones(applied.state)
this.deps.changed?.()
// Its holder gone, this machine takes its own place in the account.
if (conflictOver && !applied.state.active[selfPub]) void this.register()
return true
}
/** Trust those of `members` the log leaves active and nothing here holds back; returns them. */
private trustState(state: DevLogState, members: DevLogMember[]): DevLogMember[] {
const selfPub = this.deps.identity().pub
const suspended = this.suspendedKeys()
const adopt = members.filter((m) => m.pub !== selfPub && state.active[m.pub] && !suspended.includes(m.pub)
&& !this.deps.blocked(m.pub) && !this.deps.tombstoned(m.pub))
if (adopt.length) this.deps.adopt(adopt)
return adopt
}
/** A removal made in the trust group before the log existed must not be undone by the log: this
* machine, holding that removal, writes it into the log. */
private async carryOverTombstones(state: DevLogState): Promise<void> {
const selfPub = this.deps.identity().pub
if (!state.active[selfPub]) return
for (const m of Object.values(state.active)) {
if (m.pub !== selfPub && this.deps.tombstoned(m.pub) && !this.removing.has(m.pub)) await this.remove(m.pub)
}
}
/** While frozen, a removal still counts — if a key this machine trusts signed it. A key a fork
* suspended is not trusted here, so what it signs does not count either. */
private looseRemovals(entries: readonly unknown[]): void {
const file = this.marks()
const state = file.state
if (!state) return
const selfPub = this.deps.identity().pub
const joinedSeq = file.joinedSeq ?? 0
const suspended = new Set(file.suspended ?? [])
const loose: DevLogEntry[] = []
const notices: DeviceRemovalNotice[] = []
const departed: DevLogDeparted[] = []
const known = this.knownOf(state)
for (const raw of entries) {
const e = parseDevLogEntry(raw)
if (!e || e.op !== 'remove' || !state.active[e.signer] || suspended.has(e.signer) || !state.active[e.pub]) continue
if (!verify(b64d(e.signer), devLogMessage(e), b64d(e.sig))) continue
const notice = this.removalNotice(e, joinedSeq, selfPub, file.pending ?? [], known)
if ((file.pending ?? []).includes(e.pub) && e.pub !== selfPub) departed.push(this.departedOf(state.active[e.pub], e, known.get(e.signer)?.label ?? ''))
delete state.active[e.pub]
state.removed.push(e.pub)
this.deps.drop(e.pub)
loose.push(e)
if (notice) notices.push(notice)
}
if (!loose.length) return
this.deps.store.write({
...file, state,
looseRemoved: [...(file.looseRemoved ?? []), ...loose],
pending: this.prune(file.pending, state), announced: this.prune(file.announced, state), suspended: this.prune(file.suspended, state),
...this.withDeparted(file.departed, departed),
})
for (const n of notices) this.deps.removed?.(n)
this.deps.changed?.()
}
private freeze(reason: DevLogFreeze['reason']): void {
const file = this.deps.store.read()
if (file.frozen || !file.state) return
const { joining: _j, ...rest } = file
this.deps.store.write({ ...rest, frozen: { reason, at: this.now(), lastGoodHead: file.state.head } })
this.deps.log?.(`[devlog] FROZEN (${reason}): the device list the backend serves does not match what this machine verified — no device is added from it until someone reviews it (harness devices rebaseline)`)
this.deps.changed?.()
}
/** Remove a device from the log (and so from every device). Signed by this machine. */
remove(pub: string): Promise<DeviceLogRemoveResult> {
// One removal per key at a time: taking it out here tombstones it in the trust group, which hands
// it straight back through `onDropped` — that second ask joins this one.
const running = this.inFlightRemovals.get(pub)
if (running) return running
this.removing.add(pub)
// Started a tick later, once it is in the map: `removeOnce` drops the key before its first await, and
// that drop's `onDropped` asks again at once — begun right away, the second ask found no entry and
// appended its own removal, and this one came back NOT_IN_LOG for a key it had just taken out.
const task = Promise.resolve().then(() => this.removeOnce(pub))
.finally(() => { this.removing.delete(pub); this.inFlightRemovals.delete(pub) })
this.inFlightRemovals.set(pub, task)
return task
}
private async removeOnce(pub: string): Promise<DeviceLogRemoveResult> {
const { pub: selfPub, priv } = this.deps.identity()
for (let attempt = 0; attempt < APPEND_ATTEMPTS; attempt++) {
const file = this.deps.store.read()
const state = file.state
if (!state) return { ok: false, error: 'UNAVAILABLE' }
const target = state.active[pub]
if (!target) return { ok: false, error: 'NOT_IN_LOG' }
if (!state.active[selfPub]) return { ok: false, error: 'NOT_ACTIVE' }
// Take effect here at once, whatever the backend does with it.
this.deps.drop(pub)
const entry = signDevLogEntry(nextDevLogEntry(state, {
op: 'remove', pub, kind: target.kind, machineId: target.machineId, label: target.label, signer: selfPub,
}, this.now()), priv)
const answer = await this.deps.append(entry)
if (!answer) return { ok: false, error: 'UNAVAILABLE' }
if (!('error' in answer)) { await this.refresh(); return { ok: true } }
if (answer.error !== 'STALE_HEAD') return { ok: false, error: 'REFUSED', detail: answer.error }
await this.refresh()
await this.sleep(200 + Math.floor(Math.random() * 800) * (attempt + 1))
}
return { ok: false, error: 'UNAVAILABLE' }
}
/**
* Take out of the log the app keys nobody has used in STALE_AFTER_MS (and added that long ago too), at
* most SWEEP_MAX at a time and one sweep per SWEEP_EVERY_MS. The machine whose key is the smallest of
* the active machine keys goes first; each next one in that order waits a further SWEEP_TURN_MS before
* it takes a key, so one machine does it with no coordination — and when that one is a build from before
* the sweep (seen on a rollout: it never would) or is off, the next takes over a day later. Two that
* both do get NOT_ACTIVE on the second removal, harmless. Never a machine key: when a machine was last used
* is not something the backend can tell. Only on this sign-in's log, and never while it is frozen.
* Never throws.
*
* ponytail: last-seen comes from the backend unverified, so a backend that lies about it can have a
* machine remove an app key older than STALE_AFTER_MS (the removal is in every device's history, signed
* by this machine). Upgrade path: a last-used time the app signs itself.
*/
async sweepStale(): Promise<void> {
try {
const seen = this.deps.seen
const now = this.now()
if (!seen || (this.lastSweep !== null && now - this.lastSweep < SWEEP_EVERY_MS) || !this.current()) return
const file = this.deps.store.read()
const state = file.state
if (!state || file.frozen) return
const selfPub = this.deps.identity().pub
const machines = Object.values(state.active).filter((m) => m.kind === 'machine').map((m) => m.pub).sort()
const turn = machines.indexOf(selfPub)
if (turn < 0) return
this.lastSweep = now
const got = await seen()
// Not asked: try again on the next offer rather than read every key as never used.
if (!got) { this.lastSweep = null; return }
const cutoff = now - STALE_AFTER_MS - turn * SWEEP_TURN_MS
const suspended = this.suspendedKeys()
// A key with no time is unused only when the record has run since before the cutoff.
const usedAt = (m: DevLogMember): number | null => {
const t = got.seen[m.pub]
return typeof t === 'number' && Number.isFinite(t) ? t : null
}
const unusedSinceCutoff = (m: DevLogMember): boolean => {
const t = usedAt(m)
return t !== null ? t < cutoff : got.since !== null && got.since < cutoff
}
const stale = Object.values(state.active)
.filter((m) => m.kind === 'viewer' && m.pub !== selfPub && !suspended.includes(m.pub) && m.addedAt < cutoff && unusedSinceCutoff(m))
.sort((a, b) => a.seq - b.seq)
.slice(0, SWEEP_MAX)
for (const [i, m] of stale.entries()) {
if (i) await this.sleep(SWEEP_GAP_MS)
const r = await this.remove(m.pub)
// Already out of the log (another machine's sweep, a person's own removal): nothing to do.
if (!r.ok && r.error === 'NOT_IN_LOG') continue
if (!r.ok) { this.deps.log?.(`[devlog] could not remove unused device ${m.label || '(no name)'} (${fp(m.pub)}): ${r.detail ?? r.error}`); return }
const t = usedAt(m)
const when = t !== null ? `last used ${day(t)}` : `not used since ${day(got.since!)}`
this.deps.log?.(`[devlog] removed unused device ${m.label || '(no name)'} (${fp(m.pub)}), ${when}`)
}
} catch (err) {
this.deps.log?.(`[devlog] sweep failed: ${err instanceof Error ? err.message : String(err)}`)
}
}
/**
* What trusting the backend's log again would change; with `confirm`, do it. `expected` is the head
* the person was shown in the preview: if the backend's log is not that one any more, nothing is
* done (`LOG_CHANGED`) — what gets trusted is what was reviewed.
*/
async rebaseline(confirm: boolean, expected?: DevLogHead): Promise<DeviceLogRebaseline | DeviceLogRebaselineChanged | null> {
const entries: unknown[] = []
let acct = ''
let head: DevLogHead = emptyDevLogState('').head
// A review reads the whole list, so a log past PAGES' worth can still be reviewed.
for (let page = 0; page < JOIN_PAGES; page++) {
const got = await this.deps.fetch(entries.length)
if (!got) return null
if (!Number.isSafeInteger(got.head.seq) || got.head.seq < 0) return null
acct = got.acct
head = got.head
entries.push(...got.entries)
if (!got.entries.length || entries.length >= got.head.seq) break
}
let next: DevLogState
try {
next = applyDevLogEntries(emptyDevLogState(acct), entries).state
} catch { return null }
if (next.head.seq !== head.seq || next.head.hash !== head.hash) return null
const file = this.marks()
const same = !!file.state && file.state.acct === next.acct
// Another account's list while the live log is the one of the sign-in this machine is under: the
// backend switched accounts on its own. A review must not move this machine there (the account it
// is signed in to, and every mark on it, would go out of sight): only a sign-in switches accounts.
// Only a sign-in by hand the file is not stamped with is that switch: none recorded, an adopted one
// (a session this machine took over — whatever stamp the file has, or lacks, from an older version),
// or the sign-in the file is stamped with is not.
const local = this.deps.signIn()
if (file.state && !same && (local === null || local.adopted || file.owner === local.epoch)) return { error: 'OTHER_ACCOUNT' }
if (confirm && expected && (expected.seq !== next.head.seq || expected.hash !== next.head.hash)) return { error: 'LOG_CHANGED' }
// The list under review is judged against this account's own log as this machine verified it:
// the live file, or — for another account — the one kept when this machine left it (its marks go
// on), or else nothing (every key on it is new here). Never against the account being left.
const kept = same ? null : this.deps.store.archivedFile(next.acct)
const base: DevLogFile = same ? file : kept ?? {
state: null, recent: [], frozen: null, notifiedUpTo: 0, joinedSeq: 0, preLog: file.preLog ?? [],
pending: [], announced: [], suspended: [], baselineSeen: true,
}
const before = base.state?.active ?? {}
const added = Object.values(next.active).filter((m) => !before[m.pub])
const removed = Object.values(before).filter((m) => !next.active[m.pub])
if (confirm) {
const parsed = entries.map((e) => parseDevLogEntry(e)).filter((e): e is DevLogEntry => e !== null)
const selfPub = this.deps.identity().pub
const signIn = this.deps.signIn()
const preLog = new Set(base.preLog ?? [])
const announced = base.announced ?? []
// Every key the review let in is new here — however the preview and this read differ — unless
// this machine knew it already or its user unpaired it.
const news = added.filter((m) => m.pub !== selfPub && !preLog.has(m.pub) && !this.deps.blocked(m.pub))
const toAnnounce = news.filter((m) => !announced.includes(m.pub))
// The joined point never moves up past the reviewed head: a shorter list (rolled back, or
// another account's) must leave every key added to it from here on news.
const joinedSeq = Math.min(base.joinedSeq ?? base.notifiedUpTo, next.head.seq)
// The reviewed list is another account's: the departing log follows the same policy as a sign-in
// (and what a fork suspended in it stays suspended here) — and a kept one of the reviewed account
// goes on from where it was.
if (file.state && !same) {
this.deps.switchAccount?.(file.state.acct, next.acct)
this.archiveDeparting(file)
}
const { joining: _j, ...rest } = base
const reviewed: DevLogFile = this.carrySuspensions({
...rest,
state: next, recent: parsed.slice(-DEVLOG_RECENT), frozen: null, notifiedUpTo: next.head.seq, joinedSeq,
firstSeen: this.stamp(base.firstSeen, added, next),
pending: this.prune([...(base.pending ?? []), ...news.map((m) => m.pub)], next),
announced: this.prune([...announced, ...toAnnounce.map((m) => m.pub)], next),
// A review lifts what a fork suspended in this list; a kept list's suspensions were never in
// the preview, so they stay.
suspended: same ? [] : this.prune(base.suspended, next),
looseRemoved: [], reviewedSeq: next.head.seq,
...this.withDeparted(base.departed, this.reviewDeparted(base, next, parsed, removed, selfPub, preLog)),
...(signIn ? { owner: signIn.epoch } : {}),
})
if (!kept || !this.deps.store.restore(next.acct, () => reviewed)) this.deps.store.write(reviewed)
this.trustState(next, Object.values(next.active))
for (const m of removed) this.deps.drop(m.pub)
// The review is done: what a fork suspended is trusted again, along with the rest of the log —
// after the drops, so a key the reviewed log removed is not pinned again on the way out.
this.deps.resume?.()
for (const m of toAnnounce) this.deps.announce(m)
this.deps.changed?.()
}
return { head: next.head, added, removed }
}
/** What rides this machine's side of a `group_sync`. */
gossip(): Record<string, unknown> | undefined {
const file = this.deps.store.read()
// Not this sign-in's log yet (it may be the account this machine just left): nothing to say.
if (!file.state || !this.ownsFile(file)) return undefined
// The newest hashes let a peer that finds the logs forked say where they split.
const hashes = file.state.hashes.slice(-GOSSIP_HASHES).map((hash, i, all) => ({ seq: file.state!.head.seq - (all.length - 1 - i), hash }))
// The account rides along: a device still signed in to the one this machine left must not have its
// log taken for a fork of this one.
return { acct: file.state.acct, head: file.state.head, frozen: file.frozen !== null, hashes }
}
/**
* A peer's side of a `group_sync`. Returns what to answer (a responder hands back its own head, and
* the entries the peer is missing if it is behind).
*/
heard(peerPub: string, raw: unknown): Record<string, unknown> | undefined {
const file = this.marks()
const state = file.state
// A sign-in waiting for its first read: the file may be the account left behind, and a peer of the
// new one would freeze it as a fork. Nothing is judged until the log is this sign-in's.
if (!this.ownsFile(file)) return undefined
const mine = this.gossip()
if (!state || !raw || typeof raw !== 'object') return mine
const p = raw as { acct?: unknown; head?: unknown; frozen?: unknown; tail?: unknown }
// Another account's log says nothing about this one. A peer from before the account rode along
// sends none, and is judged as before.
if (p.acct !== undefined && p.acct !== state.acct) return undefined
this.frozenPeers.set(peerPub, p.frozen === true)
const head = p.head as { seq?: unknown; hash?: unknown } | undefined
if (!head || typeof head.seq !== 'number' || !Number.isSafeInteger(head.seq) || head.seq < 0 || typeof head.hash !== 'string') return mine
const theirs: DevLogHead = { seq: head.seq, hash: head.hash }
const relation = compareDevLogHead(state, theirs)
if (relation === 'fork') { this.freeze('fork'); this.suspendAfterFork(state, raw); return this.gossip() }
if (relation === 'behind') {
const tail = Array.isArray(p.tail) ? p.tail.filter((e) => (parseDevLogEntry(e)?.seq ?? 0) > state.head.seq) : []
// A tail that does not continue this log is a fork; and a log already frozen on one can still
// learn from this peer's hashes where it split.
if (file.frozen || (tail.length && !this.accept(tail, false))) this.suspendAfterFork(state, raw)
// Either way ask the backend too: if it will not serve what a peer already verified, that is a
// rollback, and the next refresh freezes on it.
void this.refresh()
return this.gossip()
}
if (relation === 'ahead') {
const tail = file.recent.filter((e) => e.seq > theirs.seq)
if (tail.length && tail[0].seq === theirs.seq + 1) return { ...mine, tail }
}
return mine
}
/**
* A fork a peer proved with its hashes: the keys added at or after the split — and new here — are
* not trusted until the list is reviewed (rebaseline). Only locally: nothing is tombstoned or
* written to the log. Without usable hashes (an older peer, a split outside the window, a rollback)
* the freeze alone stands.
*/
private suspendAfterFork(state: DevLogState, theirs: unknown): void {
const file = this.deps.store.read()
if (file.frozen?.reason !== 'fork') return
const split = devLogDivergence(state, theirs)
if (split === null) return
const selfPub = this.deps.identity().pub
const pending = file.pending ?? []
// Only keys nobody here has marked as seen — and not one a review (`rebaseline --yes`) already let
// in: another device's old branch must not cost this one the devices its user just looked at.
const reviewed = file.reviewedSeq ?? -1
const keys = Object.values(state.active)
.filter((m) => m.seq >= split && m.pub !== selfPub && pending.includes(m.pub) && m.seq > reviewed)
.map((m) => m.pub)
const fresh = keys.filter((k) => !(file.suspended ?? []).includes(k))
if (!fresh.length) return
this.deps.store.write({ ...file, suspended: uniq([...(file.suspended ?? []), ...fresh]) })
this.deps.suspend?.(fresh)
this.deps.log?.(`[devlog] this computer's and another device's lists split at entry ${split}: not trusting ${fresh.length} key(s) added after it until you review the list (harness devices rebaseline)`)
this.deps.changed?.()
}
/** Keys not trusted here after a fork, until `rebaseline` — and every key a fork suspended in the
* kept log of another account, which no other account's log can bring back in. */
suspendedKeys(): string[] {
return [...new Set([...(this.deps.store.read().suspended ?? []), ...this.deps.store.archivedSuspended()])]
}
/**
* Mark new devices as seen: the ones in `pubs` (what a window displayed), one (`pub`), every one
* (nothing named — only the explicit `harness devices dismiss`), and/or the "already on your account"
* list (`baseline`). Persisted, so it holds across restarts. A key a fork suspended stays flagged
* when it is only part of a list that was looked at; `pub` — "It's mine" on that very device — is the
* person vouching for it, and lifts its suspension here (and in every kept account's log). A key that
* joined and left before anyone looked (`departed`) is cleared the same way: named, or every one.
*
* `confirm` — "It's mine", pressed for ONE device (`pub`, or `pubs` naming only it) — also tells the
* account's other devices, with an acknowledgement this machine signs (deviceAck.ts): they stop showing
* it as New too. Never for a list that was only looked at, every device at once, or the baseline: only
* an explicit "It's mine" vouches. Marking it seen here is done before this returns; the promise says
* whether the other devices were told (false: the backend did not take it, or there was nothing to tell).
*/
dismiss(opts: { pub?: string; pubs?: string[]; baseline?: boolean; confirm?: boolean } = {}): Promise<boolean> {
const one = opts.pub ?? (opts.pubs?.length === 1 ? opts.pubs[0] : undefined)
const wasNew = one !== undefined && (this.marks().pending ?? []).includes(one)
this.markSeen(opts)
// Only a key that was new here, and that this machine trusts now: one a fork suspended here (and
// "It's mine" did not lift) is not this machine's to vouch for.
if (!opts.confirm || opts.baseline || one === undefined || !wasNew || this.suspendedKeys().includes(one)) return Promise.resolve(false)
return this.shareAck(one)
}
private markSeen(opts: { pub?: string; pubs?: string[]; baseline?: boolean }): void {
const file = this.marks()
if (!file.state) return
const suspended = file.suspended ?? []
const named = opts.pub !== undefined || opts.pubs !== undefined
const gone = new Set([...(opts.pubs ?? []), ...(opts.pub !== undefined ? [opts.pub] : [])])
const keep = (k: string): boolean => (named ? !gone.has(k) : !!opts.baseline) || (suspended.includes(k) && k !== opts.pub)
const pending = (file.pending ?? []).filter(keep)
const departed = (file.departed ?? []).filter((d) => (named ? !gone.has(d.pub) : !!opts.baseline))
const lift = opts.pub !== undefined && suspended.includes(opts.pub)
// The "already on your account" list was looked at: the first read is over, whatever comes after is
// news — or a backend that stalls that read could add a key to a list nobody will look at again.
const { joining: _j, ...rest } = file
this.deps.store.write({
...(opts.baseline ? { ...rest, baselineSeen: true } : file), pending,
...(file.departed ? { departed } : {}),
...(lift ? { suspended: suspended.filter((k) => k !== opts.pub) } : {}),
})
if (lift) {
this.deps.store.unsuspendArchived([opts.pub!])
const member = file.state.active[opts.pub!]
if (member) this.trustState(file.state, [member])
this.deps.resume?.()
}
this.deps.changed?.()
}
/** Sign "It's mine" for `pub` and hand it to the backend for the account's other devices. Only from a
* log this machine verified, is on, and that is not frozen (a frozen list is not one to vouch from),
* about a key on it that is not this machine. Never throws. */
private async shareAck(pub: string): Promise<boolean> {
const post = this.deps.postAck
if (!post) return false
try {
const file = this.deps.store.read()
const state = file.state
const { pub: selfPub, priv } = this.deps.identity()
if (!state || file.frozen || !this.ownsFile(file) || pub === selfPub || !state.active[selfPub]) return false
const member = state.active[pub]
if (!member) return false
const ack = signDevAck({ v: DEVACK_VERSION, acct: state.acct, pub, addSeq: member.seq, signer: selfPub, at: this.now() }, priv)
const kept = await post(ack)
if (!kept) this.deps.log?.(`[devlog] could not tell your other devices that ${member.label || '(no name)'} (${fp(pub)}) is yours: they still show it as new`)
return kept
} catch (err) {
this.deps.log?.(`[devlog] could not share "It's mine": ${err instanceof Error ? err.message : String(err)}`)
return false
}
}
/**
* Every add and remove in the log, newest first, as this machine verified it: the entries come from
* the backend but each must hash to what this machine already verified, or the log freezes. Offline,
* what is kept locally (`complete: false`).
*/
history(): Promise<DeviceLogHistory> {
// One walk at a time: two interleaved on the same cache would each read the other's entries as a
// gap in the log and freeze it.
this.historying ??= this.historyOnce().finally(() => { this.historying = null })
return this.historying
}
private async historyOnce(): Promise<DeviceLogHistory> {
await this.refresh()
const file = this.marks()
const state = file.state
if (!state) return { rows: [], complete: false, frozen: file.frozen }
const cache = this.histCache && this.histCache.acct === state.acct ? this.histCache : { acct: state.acct, entries: [] as DevLogEntry[] }
const last = cache.entries.at(-1)
if (last && (last.seq > state.head.seq || devLogHash(last) !== state.hashes[last.seq - 1])) cache.entries = []
this.histCache = cache
for (let page = 0; page < PAGES && cache.entries.length < state.head.seq; page++) {
const since = cache.entries.length
const got = await this.deps.fetch(since)
if (!got || got.acct !== state.acct) break
let progressed = false
for (const raw of got.entries) {
const e = parseDevLogEntry(raw)
const rawSeq = (raw as { seq?: unknown } | null)?.seq
const seq = e?.seq ?? (typeof rawSeq === 'number' ? rawSeq : 0)
if (seq <= cache.entries.length || seq > state.head.seq) continue
// At a position this machine verified, anything unreadable or off-hash means the backend is
// lying about the past: freeze, and show only what was already checked.
if (!e || e.seq !== cache.entries.length + 1 || devLogHash(e) !== state.hashes[e.seq - 1]) {
// Only against the log this walk started from: if the file was rebaselined (or moved to
// another account) while the pages were on their way, the mismatch is with a log that is
// gone, and says nothing about the backend.
const now = this.deps.store.read().state
if (!now || now.acct !== state.acct || now.head.seq !== state.head.seq || now.head.hash !== state.head.hash) {
this.histCache = null
return this.historyOf([], false)
}
this.freeze('fork')
return this.historyOf(cache.entries, false)
}
cache.entries.push(e)
progressed = true
}
if (!progressed) break
}
return this.historyOf(cache.entries, cache.entries.length >= state.head.seq)
}
private historyOf(fetched: readonly DevLogEntry[], complete: boolean): DeviceLogHistory {
const file = this.deps.store.read()
const state = file.state
if (!state) return { rows: [], complete: false, frozen: file.frozen }
// Offline, the newest entries kept locally fill in what could not be fetched.
const entries = complete ? fetched : [...fetched, ...file.recent.filter((e) => e.seq > (fetched.at(-1)?.seq ?? 0))]
const rows = devLogHistory(entries, {
// A key that joined and left before anyone looked is still new, in its rows too.
selfPub: this.deps.identity().pub, joinedSeq: file.joinedSeq, active: state.active, loose: file.looseRemoved,
pending: [...(file.pending ?? []), ...(file.departed ?? []).map((d) => d.pub)],
})
return { rows, complete, frozen: file.frozen }
}
/** The account's devices as this machine's log has them, for the Devices list. */
list(): DeviceLogListing {
const file = this.marks()
const selfPub = this.deps.identity().pub
const pending = file.pending ?? []
const suspended = file.suspended ?? []
const members = Object.values(file.state?.active ?? {})
.sort((a, b) => a.seq - b.seq)
.map((m) => {
const row = { ...m, fingerprint: fp(m.pub), self: m.pub === selfPub, pending: pending.includes(m.pub), suspended: suspended.includes(m.pub) }
const confirmed = file.confirmed?.[m.pub]
return confirmed ? { ...row, confirmed } : row
})
const labels = new Map(members.map((m) => [m.pub, m.label]))
const frozenPeers = [...this.frozenPeers].filter(([, frozen]) => frozen).map(([pub]) => labels.get(pub) ?? fp(pub))
// Each row carries when this machine first applied it (never the entry's self-chosen `at`).
const withSeen = members.map((m) => (file.firstSeen?.[m.pub] === undefined ? m : { ...m, firstSeen: file.firstSeen[m.pub] }))
const joinedSeq = file.joinedSeq ?? 0
const preLog = new Set(file.preLog ?? [])
const baseline = withSeen.filter((m) => !m.self && (m.seq <= joinedSeq || preLog.has(m.pub))).map((m) => m.pub)
const holder = file.conflict
const conflict = holder && file.state?.active[holder.pub] && !file.state.active[selfPub] ? holder : null
return {
head: file.state?.head ?? null, frozen: file.frozen, self: selfPub, members: withSeen, frozenPeers,
pending, suspended, joinedSeq, baseline, baselineSeen: file.baselineSeen ?? true, conflict, departed: file.departed ?? [],
...(this.registerError ? { registerError: this.registerError } : {}),
}
}
}