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
import type { Prisma } from '@prisma/client'
import { prisma } from './prisma.js'
import { pub, publishDeviceKeysChanged, publishDown } from './bus.js'
import { logger } from '../utils/logger.js'
import { revokeHarnessSessionById } from './harnessSession.js'
import {
applyDevLogEntries, DevLogError, emptyDevLogState, parseDevLogEntry,
type DevLogEntry, type DevLogHead, type DevLogMember, type DevLogState,
} from './deviceLogCore.js'
import { checkDevAck } from './deviceAckCore.js'
/**
* The account's device key log, as the backend keeps it (the format and every rule are
* lib/deviceLogCore.ts). This side stores and serves it, and refuses an entry that breaks a rule, so a
* device never has to throw a bad one away — but no device takes the backend's word for anything: each
* verifies the whole chain itself, and gossips the head with the others.
*
* Who may append what is decided by the CHANNEL, on top of the signatures:
* - a machine appends over its own adapter socket, and only about ITSELF (`kind: 'machine'`, its own
* machineId) — so no device can register a key under another machine's id; a team machine
* (lib/teamSession.ts) also removes only its own key, never another device of the account;
* - a viewer app appends over REST, only `kind: 'viewer'` entries, and signs removals with a viewer key.
*/
/** A page is enough for any real account (256 active keys at most); a device asks again from its head. */
const PAGE = 500
export type DeviceKeyAppendError =
| { status: 409; code: 'STALE_HEAD'; head: DevLogHead }
| { status: 400; code: string }
| { status: 403; code: 'WRONG_CHANNEL' }
export type DeviceKeyAppendResult = { ok: true; head: DevLogHead } | ({ ok: false } & DeviceKeyAppendError)
/** Who is appending: a machine over its adapter socket, or a viewer over REST. */
export type DeviceKeyChannel =
| { kind: 'machine'; machineId: string; harnessSessionId?: string; team?: boolean }
| { kind: 'viewer'; harnessSessionId?: string }
/**
* The entries after `since`, up to the head they are read with. The head comes first and the entries stop
* at it: read side by side, an append landing between the two reads gave a head past the entries the page
* carried, and a device reads that as a list held back and freezes it (a Harness OS box registering its
* key as it signed in from a phone, 2026-10-22).
*/
export async function readDeviceKeyLog(userId: string, since: number): Promise<{ acct: string; head: DevLogHead; entries: unknown[] }> {
const head = await logHead(userId)
const rows = head.seq > since
? await prisma.deviceKeyLogEntry.findMany({ where: { userId, seq: { gt: since, lte: head.seq } }, orderBy: { seq: 'asc' }, take: PAGE })
: []
return { acct: userId, head, entries: rows.map(r => JSON.parse(r.entry) as unknown) }
}
async function logHead(userId: string): Promise<DevLogHead> {
const last = await prisma.deviceKeyLogEntry.findFirst({ where: { userId }, orderBy: { seq: 'desc' }, select: { seq: true, hash: true } })
return last ? { seq: last.seq, hash: last.hash } : emptyDevLogState(userId).head
}
/** pub → the Harness session that added that key, for the active keys that carried one. */
type Sessions = Map<string, string>
/** Keep [sessions] in step with one more entry, and the session its row recorded. */
function trackSession(sessions: Sessions, entry: DevLogEntry, sessionId: string | null | undefined): void {
if (entry.op === 'remove') sessions.delete(entry.pub)
else if (sessionId) sessions.set(entry.pub, sessionId)
}
/** [rows] verified on top of [base], every rule checked again; [sessions] follows them. */
function replay(base: DevLogState, sessions: Sessions, rows: Array<{ entry: string; sessionId: string | null }>): DevLogState {
const entries = rows.map(r => JSON.parse(r.entry) as DevLogEntry)
const { state } = applyDevLogEntries(base, entries)
entries.forEach((e, i) => trackSession(sessions, e, rows[i].sessionId))
return state
}
/**
* The log as of its head, verified. Verifying it whole costs about a millisecond an entry, too much on
* every append once a log grows, so it starts from the snapshot (DeviceKeyLogState) and verifies only
* what came after it. The snapshot is checked against the real head each time, never trusted to be
* current — any pod may have appended since. One that does not fit the log is replayed over from the
* start. `hashes` holds only what was replayed: nothing here looks an older entry up.
*/
async function currentState(userId: string): Promise<{ state: DevLogState; sessions: Sessions }> {
const [snap, head] = await Promise.all([
prisma.deviceKeyLogState.findUnique({ where: { userId } }),
logHead(userId),
])
if (snap) {
try {
const state: DevLogState = {
acct: userId, head: { seq: snap.seq, hash: snap.hash }, hashes: [],
active: snap.active as unknown as DevLogState['active'], removed: snap.removed as string[],
}
const sessions: Sessions = new Map(Object.entries(snap.sessions as Record<string, string>))
if (snap.seq === head.seq && snap.hash === head.hash) return { state, sessions }
if (snap.seq >= head.seq) throw new Error('snapshot is not on the way to the head')
const rows = await prisma.deviceKeyLogEntry.findMany({ where: { userId, seq: { gt: snap.seq } }, orderBy: { seq: 'asc' } })
const next = replay(state, sessions, rows)
await saveSnapshot(userId, next, sessions)
return { state: next, sessions }
} catch (err) {
logger.warn('device key log snapshot does not fit the log; replaying the whole log', { userId, seq: snap.seq, error: String(err) })
}
}
const rows = await prisma.deviceKeyLogEntry.findMany({ where: { userId }, orderBy: { seq: 'asc' } })
const sessions: Sessions = new Map()
const state = replay(emptyDevLogState(userId), sessions, rows)
if (rows.length || snap) await saveSnapshot(userId, state, sessions, snap ?? undefined)
return { state, sessions }
}
/**
* The machine keys the account's log leaves active, by machine: what a machine shared with this account
* trusts it under (lib/machineAccess.ts), and the key another account's daemon pins to reach a machine
* shared with it. The newest key wins when one machine has two.
*/
export async function activeMachineKeys(userId: string): Promise<DevLogMember[]> {
return machineKeys((await currentState(userId)).state.active)
}
/**
* [activeMachineKeys] of many accounts, by account: every member of a machine shared with a domain, on each read or save
* of its policy. One log replay each made a 200-person domain 400+ parallel queries (Diego's issue file, 2026-10-27), so the
* snapshots and the entries from each one on are read for all of them at once. A snapshot fits its head when the only
* entry from its sequence on is its own; an account with neither has no keys. Any other account is verified alone, as
* [currentState] does.
*/
export async function activeMachineKeysOf(userIds: string[]): Promise<Map<string, DevLogMember[]>> {
if (!userIds.length) return new Map()
const snaps = new Map((await prisma.deviceKeyLogState.findMany({ where: { userId: { in: userIds } } })).map(s => [s.userId, s]))
const rows = await prisma.deviceKeyLogEntry.findMany({ where: { OR: userIds.map(userId => ({ userId, seq: { gte: snaps.get(userId)?.seq ?? 0 } })) },
select: { userId: true, seq: true, hash: true } })
const since = new Map<string, Array<{ seq: number; hash: string }>>()
for (const row of rows) {
const list = since.get(row.userId)
if (list) list.push(row)
else since.set(row.userId, [row])
}
return new Map(await Promise.all(userIds.map(async (userId): Promise<[string, DevLogMember[]]> => {
const snap = snaps.get(userId), after = since.get(userId) ?? []
if (!snap && !after.length) return [userId, []]
if (snap && after.length === 1 && after[0]!.seq === snap.seq && after[0]!.hash === snap.hash) {
return [userId, machineKeys(snap.active as unknown as DevLogState['active'])]
}
return [userId, await activeMachineKeys(userId)]
})))
}
/** The active machine keys by machine; the newest key wins when one machine has two. */
function machineKeys(active: DevLogState['active']): DevLogMember[] {
const byMachine = new Map<string, DevLogMember>()
for (const member of Object.values(active)) {
if (member.kind !== 'machine' || !member.machineId) continue
const held = byMachine.get(member.machineId)
if (!held || held.seq < member.seq) byMachine.set(member.machineId, member)
}
return [...byMachine.values()]
}
/**
* Keep the snapshot at [state]. It only moves forward, so a slower append cannot put an older one back
* — except over [replacing], a snapshot found not to fit the log, which is overwritten only if it is
* still the one that was read. Best effort: without it the next append replays from where it stands.
*/
async function saveSnapshot(userId: string, state: DevLogState, sessions: Sessions, replacing?: DevLogHead): Promise<void> {
const data = {
seq: state.head.seq, hash: state.head.hash, active: state.active as unknown as Prisma.InputJsonObject,
removed: state.removed, sessions: Object.fromEntries(sessions),
}
try {
const { count } = await prisma.deviceKeyLogState.updateMany({
where: replacing ? { userId, seq: replacing.seq, hash: replacing.hash } : { userId, seq: { lt: data.seq } },
data,
})
if (count === 0 && !replacing) await prisma.deviceKeyLogState.create({ data: { userId, ...data } })
} catch (err) {
// A unique violation is a snapshot already there, at this head or past it: nothing to save.
if (!isUniqueViolation(err)) logger.warn('device key log snapshot not saved', { userId, seq: data.seq, error: String(err) })
}
}
function channelAllows(entry: DevLogEntry, state: DevLogState, channel: DeviceKeyChannel): boolean {
const signer = state.active[entry.signer]
if (channel.kind === 'machine') {
// A machine speaks only as itself: its own key, under its own id.
if (entry.op === 'add') return entry.kind === 'machine' && entry.machineId === channel.machineId
// A team machine may leave, but never take another device off the account (and so sign it out).
const removed = state.active[entry.pub]
if (channel.team && !(removed?.kind === 'machine' && removed.machineId === channel.machineId)) return false
return signer?.kind === 'machine' && signer.machineId === channel.machineId
}
if (entry.op === 'add') return entry.kind === 'viewer'
return signer?.kind === 'viewer'
}
function isUniqueViolation(err: unknown): boolean {
return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'P2002'
}
export async function appendDeviceKey(userId: string, raw: unknown, channel: DeviceKeyChannel): Promise<DeviceKeyAppendResult> {
const entry = parseDevLogEntry(raw)
if (!entry) return { ok: false, status: 400, code: 'BAD_ENTRY' }
if (entry.acct !== userId) return { ok: false, status: 400, code: 'WRONG_ACCOUNT' }
const { state, sessions } = await currentState(userId)
if (entry.seq !== state.head.seq + 1 || entry.prev !== state.head.hash) {
return { ok: false, status: 409, code: 'STALE_HEAD', head: state.head }
}
if (!channelAllows(entry, state, channel)) return { ok: false, status: 403, code: 'WRONG_CHANNEL' }
let applied
try {
applied = applyDevLogEntries(state, [entry])
} catch (err) {
if (err instanceof DevLogError) return { ok: false, status: 400, code: err.code }
throw err
}
const head = applied.state.head
// The Harness session that added this key (a phone signed in by QR, or a computer a phone signed
// in), so removing the key signs that session out too.
const sessionId = entry.op === 'add' ? channel.harnessSessionId ?? null : null
try {
await prisma.deviceKeyLogEntry.create({ data: { userId, seq: entry.seq, hash: head.hash, entry: JSON.stringify(entry), sessionId } })
} catch (err) {
// Another device appended at this head first.
if (isUniqueViolation(err)) return { ok: false, status: 409, code: 'STALE_HEAD', head: await logHead(userId) }
throw err
}
const nextSessions = new Map(sessions)
trackSession(nextSessions, entry, sessionId)
await saveSnapshot(userId, applied.state, nextSessions)
await publishDeviceKeysChanged(userId, head).catch(() => { /* best effort: devices also re-read on their own */ })
touchDeviceKey(userId, entry.signer)
for (const gone of applied.removed) await signOut(userId, gone.kind, gone.machineId, gone.pub, sessions.get(gone.pub))
logger.info('device key log appended', { userId, seq: entry.seq, op: entry.op, kind: entry.kind })
return { ok: true, head }
}
// ── "It's mine", once for the account ─────────────────────────────────────────────────────────────
// A device that confirms a new one signs an acknowledgement (lib/deviceAckCore.ts), and the account's
// other devices stop showing that key as New. Kept beside the log, never in its chain, so an older
// client never sees one. Checked here against the log as it stands — a bad one is refused rather than
// kept for every device to throw away — but no device takes this side's word for it: each checks the
// signature and the signer against its own verified log, and its own marks on both keys.
/** The acknowledgements one read returns. Each key has at most one per signer, and a device asks only
* from just below the oldest key it still shows as New, so a page holds what any real account has. */
const ACK_PAGE = 500
export type DeviceAckAppendResult = { ok: true; created: boolean } | { ok: false; status: 400; code: string }
export async function appendDeviceAck(userId: string, raw: unknown): Promise<DeviceAckAppendResult> {
const { state } = await currentState(userId)
const checked = checkDevAck(state, raw)
if (!checked.ok) return { ok: false, status: 400, code: checked.code }
const { ack } = checked
try {
await prisma.deviceKeyAck.create({ data: { userId, pub: ack.pub, addSeq: ack.addSeq, signer: ack.signer, ack: JSON.stringify(ack) } })
} catch (err) {
// This signer already said so for this key: the first one stands, and saying it again is no error
// (a device that retries, or two of its windows).
if (isUniqueViolation(err)) return { ok: true, created: false }
throw err
}
// The head did not move; the push only tells every device to read again, which reads acknowledgements.
await publishDeviceKeysChanged(userId, state.head).catch(() => { /* best effort: devices also re-read on their own */ })
touchDeviceKey(userId, ack.signer)
logger.info('device key acknowledged', { userId, addSeq: ack.addSeq })
return { ok: true, created: true }
}
/** The acknowledgements of keys added after entry [since], oldest key first, as the devices sent them. */
export async function readDeviceAcks(userId: string, since: number): Promise<{ acks: unknown[] }> {
const rows = await prisma.deviceKeyAck.findMany({
where: { userId, addSeq: { gt: since } }, orderBy: [{ addSeq: 'asc' }, { createdAt: 'asc' }], take: ACK_PAGE,
})
return { acks: rows.map(r => JSON.parse(r.ack) as unknown) }
}
/**
* A removed key is banned from the log for good, which is what keeps it out. Signing the device out is
* on top of that, where the backend can: a machine is told to drop its sign-in (the same frame a deleted
* machine gets), a phone signed in by a QR loses its session. An Autonomous sign-in is not ours to end.
*/
async function signOut(userId: string, kind: string, machineId: string, pubKey: string, sessionId: string | undefined): Promise<void> {
try {
if (kind === 'machine' && machineId) {
// Named, so the machine knows its KEY is gone (not just its sign-in) and signs in again with a new
// one; a daemon that predates the log reads only the type, as for a deleted machine.
await publishDown(machineId, { connId: '', frame: { type: 'machine_revoked', payload: { reason: 'device_removed', pub: pubKey } } })
}
// A Harness session (a phone, or a computer a phone signed in by QR) ends here too — a machine
// that ignores `machine_revoked` must not keep a session it could sign a new key in with.
if (sessionId) {
await revokeHarnessSessionById(sessionId, userId)
}
} catch (err) {
logger.warn('device key removal sign-out failed', { userId, kind, error: String(err) })
}
}
// ── when each key was last seen ────────────────────────────────────────────────────────────────────
// A viewer app whose browser data was cleared never signs its own removal: its key stays active in
// the log, unused, forever. The Devices list offers to remove the ones not seen in a long while, and
// this is what "seen" means: the key opened an E2EE session (`e2e_hello` carries it in the clear, on
// its way to a machine). Only a hint for that list — nothing trusts or distrusts a key by it — so a
// client claiming someone else's key here can at most keep that one off the suggestion.
//
// `_since` (in the same hash, so it goes when the hash goes — a TTL, an eviction, a Redis that comes
// back empty) is when this record began: a key with no time here is unused only if the record is
// older than the question. Without it, a Redis that lost its data read as "no app used in months",
// and a machine's sweep (cli deviceLogSyncer `sweepStale`) would have removed every old app key.
const SEEN_TTL_SEC = 400 * 24 * 60 * 60
/** One write per key per this long, per process: a phone opens a session per machine it shows. */
const SEEN_WRITE_EVERY_MS = 60 * 60 * 1000
const SEEN_MEMORY_MAX = 10_000
const seenWritten = new Map<string, number>()
const seenKey = (userId: string): string => `devkeys:seen:${userId}`
const PUB_RE = /^[A-Za-z0-9+/]{43}=$/
const SINCE = '_since'
export function touchDeviceKey(userId: string, pubKey: unknown, now = Date.now()): void {
if (typeof pubKey !== 'string' || !PUB_RE.test(pubKey)) return
const memo = `${userId}:${pubKey}`
const last = seenWritten.get(memo)
if (last !== undefined && now - last < SEEN_WRITE_EVERY_MS) return
if (seenWritten.size >= SEEN_MEMORY_MAX) seenWritten.clear()
seenWritten.set(memo, now)
void pub.multi().hsetnx(seenKey(userId), SINCE, String(now)).hset(seenKey(userId), pubKey, String(now))
.expire(seenKey(userId), SEEN_TTL_SEC).exec()
.catch(() => { seenWritten.delete(memo) })
}
/**
* When each of the account's keys was last seen, by pub (ms), and since when that record runs (null when
* there is none). Throws when Redis cannot be read: "could not ask" must never read as "nothing seen".
*/
export async function deviceKeysSeen(userId: string): Promise<{ seen: Record<string, number>; since: number | null }> {
const raw = await pub.hgetall(seenKey(userId))
const seen: Record<string, number> = {}
let since: number | null = null
for (const [k, v] of Object.entries(raw ?? {})) {
const n = Number(v)
if (!Number.isSafeInteger(n) || n <= 0) continue
if (k === SINCE) since = n
else if (PUB_RE.test(k)) seen[k] = n
}
return { seen, since }
}