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.

13.7 KB
Raw Blame
/**
 * E2EE persistence for the adapter: the computer's long-term identity keypair and the set of pinned
 * (paired) browser identities. Both live under ${ADAPTER_DATA_DIR}/e2e/, written immediately with
 * mode 0600 (pairs are rare — no debounce needed). The identity key is the root of trust; losing it
 * forces every browser to re-pair.
 */
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
import { join } from 'path'
import { env } from '../../config/env.js'
import { newIdentity, newPairId, b64e, b64d, fingerprint, type Identity, type PairRole } from './core.js'
import { stretchPassword } from './passwordPake.js'

const DIR = join(env.ADAPTER_DATA_DIR, 'e2e')
const IDENTITY_FILE = join(DIR, 'identity.json')
const PAIRED_FILE = join(DIR, 'paired.json')

/** This computer's identity public key (base64) as already on disk, or null. Unlike `E2eeStore.init()`
 *  it never creates a key and writes nothing, so a read-only command can show the fingerprint without
 *  minting an identity as a side effect. */
export function peekIdentityPub(): string | null {
  try {
    const raw = JSON.parse(readFileSync(IDENTITY_FILE, 'utf-8')) as { pub?: unknown }
    return typeof raw.pub === 'string' && raw.pub ? raw.pub : null
  } catch { return null }
}

/** This computer's identity keypair as already on disk, or null. Like `peekIdentityPub` it never creates one: a key
 *  made by a command that only needs to sign with the existing one would be on no device key log. */
export function peekIdentity(): Identity | null {
  try {
    const raw = JSON.parse(readFileSync(IDENTITY_FILE, 'utf-8')) as { priv?: unknown; pub?: unknown }
    if (typeof raw.priv !== 'string' || typeof raw.pub !== 'string' || !raw.priv || !raw.pub) return null
    const identity = { priv: b64d(raw.priv), pub: b64d(raw.pub) }
    return identity.priv.length === 32 && identity.pub.length === 32 ? identity : null
  } catch { return null }
}

/** Whether an identity was retired here (`identity.json.removed-*`, left by signing this device out of
 *  the account), so "no identity" can be told apart from "never had one". */
export function identitySpent(): boolean {
  try { return readdirSync(DIR).some((f) => f.startsWith('identity.json.removed-')) } catch { return false }
}
const REMOTE_PASSWORD_FILE = join(DIR, 'remotePassword.json')

// Remote-password lockout tuning (anti online-guessing for a reusable, human-memorable secret — see
// notePwFailure()/pwLockedUntil()). Distinct regime from the live pairing code's RATE_MAX=3/5min in
// manager.ts: that code is disposable and expires in 60s, so a handful of tries exhausts it quickly;
// this password is long-lived, so failures need a real, growing lockout instead.
const PW_FAIL_WINDOW_MS = 30 * 60 * 1000
const PW_FAIL_THRESHOLD = 5
const PW_LOCKOUT_BASE_MS = 5 * 60 * 1000 // 5 min
const PW_LOCKOUT_MAX_MS = 24 * 60 * 60 * 1000 // 24h, cap for the exponential backoff

interface RemotePasswordRecord {
  v: 1
  stretched: string // base64 — the 32-byte scrypt output, not the raw password
  setAt: number
  recentFailures: number[] // ms-epoch timestamps of recent failed attempts, trimmed to PW_FAIL_WINDOW_MS
  lockedUntil?: number
  lockoutCount?: number // consecutive lockouts since the password was last set — drives the backoff
}

export interface PairedClient {
  identityPub: string // base64 Ed25519 pubkey — the pin
  label: string       // UA-derived, for display
  pairedAt: number
  role: PairRole      // old records without this field are treated as web
  /** Set for a peer that joined over the remote password (or was learned from a trust-group sync): the
   *  joining machine's id when `kind` is 'machine', absent for a viewer app. Absent on older records. */
  machineId?: string
  kind?: PeerKind
  /** A machine of another account this machine is shared with (gateway/sharedTrust.ts): trusted like the
   *  account's own, but never a member of the trust group, and taken back when the sharing ends. */
  shared?: true
  /** With `shared`: the account (email) the machine is shared with. Its sessions are that account's guest
   *  (docs/plans/2026-10-19-guest-machine-sharing-plan.md). */
  sharedWith?: string
}

/** What a password-linked peer is: another harness machine (which also serves, so it can be dialed back)
 *  or a viewer app (mobile / viewer desktop — dial-out only). */
export type PeerKind = 'machine' | 'viewer'
/** How long `init()` waits for another process's just-created identity file to be written (10 × 20 ms). */
const IDENTITY_READ_RETRIES = 10
const IDENTITY_READ_RETRY_MS = 20
const sleepSync = (ms: number): void => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) }

function writeSecure(file: string, data: unknown, flag: 'w' | 'wx' = 'w'): void {
  mkdirSync(DIR, { recursive: true, mode: 0o700 })
  writeFileSync(file, JSON.stringify(data, null, 2), { mode: 0o600, flag })
}

export class E2eeStore {
  private identity: Identity | null = null
  private paired = new Map<string, PairedClient>() // key = identityPub (base64)
  private remotePassword: RemotePasswordRecord | null = null

  /** Load or create the computer identity keypair; load the paired set + remote-password state.
   *  Idempotent. */
  init(): Identity {
    if (this.identity) return this.identity
    const readIdentity = (): Identity => {
      const raw = JSON.parse(readFileSync(IDENTITY_FILE, 'utf-8')) as { priv: string; pub: string }
      return { priv: b64d(raw.priv), pub: b64d(raw.pub) }
    }
    // `harness login` and a booting daemon can both get here: exclusive create so exactly one key is
    // ever minted, and the loser adopts the winner's instead of overwriting it. The create makes the
    // file before its bytes land, so a loser that reads it empty waits a moment and reads again; only
    // a file still unreadable after that is taken as broken and replaced, as before.
    for (let attempt = 0; !this.identity; attempt++) {
      try { this.identity = readIdentity(); break } catch { /* missing, half-written or broken */ }
      const id = newIdentity()
      try {
        writeSecure(IDENTITY_FILE, { priv: b64e(id.priv), pub: b64e(id.pub) }, 'wx')
        this.identity = id
      } catch (err) {
        if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
        if (attempt < IDENTITY_READ_RETRIES) { sleepSync(IDENTITY_READ_RETRY_MS); continue }
        writeSecure(IDENTITY_FILE, { priv: b64e(id.priv), pub: b64e(id.pub) })
        this.identity = id
      }
    }
    this.reloadPaired()
    try {
      const raw = JSON.parse(readFileSync(REMOTE_PASSWORD_FILE, 'utf-8')) as Partial<RemotePasswordRecord>
      if (raw?.v === 1 && typeof raw.stretched === 'string' && typeof raw.setAt === 'number') {
        this.remotePassword = {
          v: 1,
          stretched: raw.stretched,
          setAt: raw.setAt,
          recentFailures: Array.isArray(raw.recentFailures) ? raw.recentFailures.filter((n) => typeof n === 'number') : [],
          lockedUntil: typeof raw.lockedUntil === 'number' ? raw.lockedUntil : undefined,
          lockoutCount: typeof raw.lockoutCount === 'number' ? raw.lockoutCount : undefined,
        }
      }
    } catch { /* none yet */ }
    return this.identity
  }

  /** Read paired.json again, as it is on disk now (accountTrust.ts swaps it when the account changes). */
  reloadPaired(): void {
    this.paired.clear()
    try {
      const arr = JSON.parse(readFileSync(PAIRED_FILE, 'utf-8')) as Array<PairedClient & { role?: PairRole }>
      for (const p of arr) {
        if (p?.identityPub) this.paired.set(p.identityPub, { ...p, role: p.role === 'device' ? 'device' : 'web' })
      }
    } catch { /* none yet */ }
  }

  getIdentity(): Identity {
    return this.identity ?? this.init()
  }

  /** The computer identity's human fingerprint (shown on both CLI and browser to compare). */
  fingerprint(): string {
    return fingerprint(this.getIdentity().pub)
  }

  isPaired(identityPubB64: string): boolean {
    return this.paired.has(identityPubB64)
  }

  pairedRole(identityPubB64: string): PairRole | null {
    return this.paired.get(identityPubB64)?.role ?? null
  }

  pairedLabel(identityPubB64: string): string | null {
    return this.paired.get(identityPubB64)?.label ?? null
  }

  pairedPeer(identityPubB64: string): PairedClient | null {
    return this.paired.get(identityPubB64) ?? null
  }

  addPaired(identityPubB64: string, label: string, at: number, role: PairRole = 'web', peer?: { machineId?: string; kind?: PeerKind; shared?: boolean; sharedWith?: string }): void {
    this.paired.set(identityPubB64, {
      identityPub: identityPubB64, label, pairedAt: at, role,
      ...(peer?.machineId ? { machineId: peer.machineId } : {}),
      ...(peer?.kind ? { kind: peer.kind } : {}),
      ...(peer?.shared ? { shared: true as const } : {}),
      ...(peer?.shared && peer.sharedWith ? { sharedWith: peer.sharedWith } : {}),
    })
    writeSecure(PAIRED_FILE, [...this.paired.values()])
  }

  removePaired(identityPubB64: string): void {
    if (this.paired.delete(identityPubB64)) writeSecure(PAIRED_FILE, [...this.paired.values()])
  }

  /** Revoke ALL paired browsers. Returns the number removed. */
  clear(): number {
    const n = this.paired.size
    if (n) { this.paired.clear(); writeSecure(PAIRED_FILE, []) }
    return n
  }

  list(): PairedClient[] {
    return [...this.paired.values()]
  }
  count(): number {
    return this.paired.size
  }

  // ── persistent remote password (machine-to-machine `harness link connect`) ───────────────────────
  // A separate trust primitive from the ones above: not a pairing (paired.json) and not the live 6-char
  // CPace code — see passwordPake.ts for why this needs its own domain-separated CPace generator, and
  // manager.ts's onPwPairIntent/onPwPake for the state machine that consumes remotePasswordVerifier()/
  // notePwFailure()/notePwSuccess() below.

  /** Stretch + persist a new remote password (0600, same convention as identity.json/paired.json).
   *  Rotating the password always clears any existing lockout — a fresh secret invalidates whatever
   *  guessing history applied to the old one. */
  async setRemotePassword(machineId: string, password: string): Promise<{ fingerprint: string }> {
    const stretched = await stretchPassword(password, machineId)
    const record: RemotePasswordRecord = { v: 1, stretched: b64e(stretched), setAt: Date.now(), recentFailures: [] }
    this.remotePassword = record
    writeSecure(REMOTE_PASSWORD_FILE, record)
    return { fingerprint: fingerprint(stretched) }
  }

  /** Remove the remote password. Until a new one is set, `harness link connect` against this machine
   *  always fails with NO_REMOTE_PASSWORD (checked before any crypto runs). */
  clearRemotePassword(): void {
    this.remotePassword = null
    try { rmSync(REMOTE_PASSWORD_FILE, { force: true }) } catch { /* already gone */ }
  }

  hasRemotePassword(): boolean {
    return this.remotePassword !== null
  }

  /** The raw stretched verifier bytes, fed into passwordPake.ts's pwCpaceGenerator(); null if unset. */
  remotePasswordVerifier(): Uint8Array | null {
    return this.remotePassword ? b64d(this.remotePassword.stretched) : null
  }

  remotePasswordFingerprint(): string | null {
    return this.remotePassword ? fingerprint(b64d(this.remotePassword.stretched)) : null
  }

  remotePasswordSetAt(): number | null {
    return this.remotePassword ? this.remotePassword.setAt : null
  }

  /** Record a failed password-PAKE attempt (anti online-guessing — the password is reusable and
   *  human-memorable, unlike the disposable high-entropy live pairing code, so it needs a real,
   *  growing lockout rather than the code's fixed RATE_MAX/RATE_WINDOW). Failures older than
   *  PW_FAIL_WINDOW_MS don't count. Crossing PW_FAIL_THRESHOLD within the window locks out for an
   *  exponentially growing period (5m, 10m, 20m, ... capped at 24h), tracked by `lockoutCount` so
   *  repeated lockouts (not just repeated failures) escalate the wait. No-op if no password is set —
   *  there is nothing to guess. */
  notePwFailure(): { lockedUntil: number | null } {
    const record = this.remotePassword
    if (!record) return { lockedUntil: null }
    const now = Date.now()
    // The backoff escalates across lockouts only while they keep coming: a quiet day since the last one
    // ended starts it over, so no one is held at the 24h ceiling for good.
    if (record.lockedUntil && now - record.lockedUntil > PW_LOCKOUT_MAX_MS) record.lockoutCount = 0
    record.recentFailures = [...record.recentFailures.filter((t) => now - t < PW_FAIL_WINDOW_MS), now]
    if (record.recentFailures.length >= PW_FAIL_THRESHOLD) {
      const count = (record.lockoutCount ?? 0) + 1
      record.lockoutCount = count
      record.lockedUntil = now + Math.min(PW_LOCKOUT_BASE_MS * 2 ** (count - 1), PW_LOCKOUT_MAX_MS)
      record.recentFailures = [] // fresh window once locked — it takes another full THRESHOLD after unlock
    }
    writeSecure(REMOTE_PASSWORD_FILE, record)
    return { lockedUntil: record.lockedUntil ?? null }
  }

  /** A successful pairing proves the password is known to its owner's machines: the failures and the
   *  lockout escalation that came before it no longer describe anyone's guessing, so both start over. */
  notePwSuccess(): void {
    const record = this.remotePassword
    if (!record || (record.recentFailures.length === 0 && !record.lockoutCount)) return
    record.recentFailures = []
    record.lockoutCount = 0
    writeSecure(REMOTE_PASSWORD_FILE, record)
  }

  /** Current lockout, or null if unset/expired. An expired `lockedUntil` is treated as not-locked
   *  without rewriting the file — the next real failure (if any) will naturally recompute it. */
  pwLockedUntil(): number | null {
    const until = this.remotePassword?.lockedUntil
    if (!until || until <= Date.now()) return null
    return until
  }
}