Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

19.0 KB
Raw Blame
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 }
}