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.

53.0 KB
Raw Blame
/**
 * E2eeManager — the adapter side of web↔adapter E2EE .
 *
 * Responsibilities:
 *  - always-on group key (per process, epoch id) that encrypts 1→many `up` user events (wrapUp);
 *  - the CPace pairing state machine (single slot): browser sends e2e_pair_intent → user runs
 *    `harness pair <code>` → onPair() runs CPace toward that connId → pin the browser identity;
 *  - the SEPARATE persistent remote-password CPace state machine (multi-slot, keyed by connId):
 *    another machine sends e2e_pw_pair_intent → onPwPairIntent()/onPwPake() run CPace against
 *    store.remotePasswordVerifier() with no local "arm" step → pin that machine's identity, exactly
 *    as if it were a paired browser session — see passwordPake.ts for why it's a fully separate
 *    generator/context from the live-code flow above;
 *  - a per-connection session table (X25519 → pairwise keys) established by a signed e2e_hello,
 *    used to decrypt the down `message` frame and to encrypt targeted RPC replies + the group key.
 *
 * The relay never sees plaintext user content: only ciphertext envelopes + public PAKE messages.
 */
import * as C from './core.js'
import { parseTerminalBinaryEnvelope, type TerminalBinaryClear } from '../terminalBinary.js'
import { deriveTerminalBinaryKey, openTerminalBinary, sealTerminalBinary } from './terminalSeal.js'
import { E2eeStore, type PeerKind } from './store.js'
import { pwCpaceGenerator, pwContext } from './passwordPake.js'
import { ReplayWindow } from './replayWindow.js'

type Frame = Record<string, unknown>

/**
 * `up` frames the web audience is sent sealed although core.ts's `ENCRYPTED_UP_TYPES` does not name them.
 * `commander_question` carries the question and its option labels — user content, as a recap is — and since
 * 2026-10-21 it goes to the owner's apps over the relay too (core/questions.ts), so a phone hears an agent
 * waiting on it. Kept here rather than in core.ts, as `wrapCommander` keeps it for the devices: core.ts is
 * hashed and pinned, while every reader opens by the envelope (any `payload.__e2e`: the phone's and the
 * desktop's relay_session_crypto.dart `unwrapIncoming`), so none of them changes. Its close carries only a
 * request id, and goes as the devices are sent it: in the clear.
 */
const SEALED_FOR_WEB: ReadonlySet<string> = new Set(['commander_question'])
const sealsForWeb = (type: string | undefined): type is string => !!type && (C.isEncryptedUpType(type) || SEALED_FOR_WEB.has(type))

export type PairResult =
  | { ok: true; label: string; fingerprint: string }
  | { ok: false; error: 'NO_INTENT' | 'EXPIRED' | 'CODE_MISMATCH' | 'BACKEND_DOWN' | 'RATE_LIMITED' | 'BUSY' | 'TIMEOUT' | 'CANCELLED' }

interface PairSlot {
  connId: string
  pairId: Uint8Array
  pairIdB64: string
  label: string
  role: C.PairRole   // 'web' (browser) or 'device' (hardware device) — bound into the CPace channel-binding string
  expiresAt: number
  ttlTimer: ReturnType<typeof setTimeout>
  // set once `harness pair <code>` starts CPace:
  active?: {
    y: bigint
    Ya: Uint8Array
    isk?: Uint8Array
    th?: Uint8Array
    resolve: (r: PairResult) => void
    roundTimer?: ReturnType<typeof setTimeout>
  }
}

export interface PendingPairInfo {
  label: string
  expiresAt: number
  active: boolean
  role: C.PairRole
  pairId: string
}

interface Session {
  webIdentityPub: string // base64 — the pinned pin used for this session
  role: C.PairRole
  c2s: Uint8Array        // web → adapter (down message)
  s2c: Uint8Array        // adapter → web (welcome + targeted RPC replies)
  s2cCounter: number     // next send counter (0 was the welcome)
  c2sRecv: ReplayWindow  // bounded replay guard; permits cross-transport reordering
  terminalC2s: Uint8Array
  terminalS2c: Uint8Array
  terminalS2cCounter: number
  terminalC2sRecv: ReplayWindow
}

/** A client told its session is gone is told again no sooner than this, and only so many are
 *  remembered: a relay injecting sealed frames for made-up connections gets a bounded echo. */
const SESSION_GONE_EVERY_MS = 1_000
const SESSION_GONE_REMEMBERED = 256
const PAIR_TTL_MS = 60_000
const ROUND_TIMEOUT_MS = 15_000
const RATE_WINDOW_MS = 5 * 60_000
const RATE_MAX = 3
const MAX_SESSIONS = 64
/** How long a hello from a key not paired here waits for `onUnknownHello` (a re-read of the account's
 *  device key log) before it is denied: one backend round trip, with room, and the client waiting on its
 *  hello is answered either way. */
const UNKNOWN_HELLO_WAIT_MS = 4_000

// Persistent remote-password linking (`harness remote-password set` + `harness link connect`) — a
// SEPARATE state machine from PairSlot above: no human "arm" step (a correct password is the only
// gate), and it must track multiple concurrent connIds since any other account machine could dial in
// at any time, not just the one browser/device the user is actively pairing. Round timeout is longer
// than the live-code flow's (30s vs 15s) since this crosses a machine-to-machine relay hop instead of
// a browser tab that's already open and watching.
const PW_ROUND_TIMEOUT_MS = 30_000
/** Password-PAKE attempts in flight at once, across every connection. The lockout counts failures as
 *  they are judged, so it bounds guesses only if attempts cannot pile up ahead of it. */
const MAX_PW_SLOTS = 2

interface PwPairSlot {
  connId: string
  sid: Uint8Array
  sidB64: string
  y: bigint
  Ya: Uint8Array
  isk?: Uint8Array
  th?: Uint8Array
  roundTimer: ReturnType<typeof setTimeout>
}

export interface E2eeManagerDeps {
  machineId: string
  /** Send a frame targeted at ONE web connection (adapter→web, sets targetConnId on the wire). */
  sendTo: (connId: string, frame: Frame) => void
  /** Send a user-level notification to every logged-in browser for this machine owner. */
  sendUser?: (frame: Frame) => void
  /** Is the backend link up right now (for onPair BACKEND_DOWN)? */
  isConnected: () => boolean
  isConnectionAvailable?: (connId: string) => boolean
  onIdentityPaired?: (connId: string, identityPub: string) => void
  onIdentityRevoked?: (identityPub: string) => void
  /** Release connection-scoped resources on revoke, eviction, replacement and disconnect. */
  onSessionDropped?: (connId: string) => void
  /** A connection proved a paired identity with its hello: its session is open, under that identity's
   *  role. The gateway registers it with the core from this (gateway/gateway.ts). */
  onSessionOpened?: (connId: string, role: C.PairRole, identityPub: string) => void
  /** A peer just proved this machine's remote password (it is already trusted here as a client). A
   *  machine joiner carries its machineId so the caller can pin it back and sync the trust group. */
  onPeerLinked?: (peer: LinkedPeer) => void
  /** A person unpaired `identityPub` (`harness unpair`, or a trusted client's unpair RPC) — not called
   *  for the trust group's own removals, so the group can keep an unpairing from being undone. */
  onUnpaired?: (identityPub: string) => void
  /** A hello signed by a key not paired here. The account's device key log may name it already and this
   *  machine has not adopted it yet (a browser that signed in before this machine did): the caller reads
   *  the log and trusts it if so. The hello waits for it, at most UNKNOWN_HELLO_WAIT_MS, then is answered
   *  as the key stands. Absent, such a hello is denied at once. */
  onUnknownHello?: (identityPub: string) => Promise<void>
}

export interface LinkedPeer {
  pub: string          // base64 Ed25519 identity
  machineId?: string   // set when kind is 'machine'
  kind?: PeerKind      // absent for an older joiner that did not say
  label: string
  shared?: boolean     // another account's machine this one is shared with (gateway/sharedTrust.ts)
  sharedWith?: string  // with `shared`: the account (email) it is shared with — whose guest its sessions are
}

const MACHINE_ID_RE = /^[a-f0-9]{32}$/

/** The optional fields a newer joiner seals into round 4. Anything malformed is dropped rather than
 *  failing the link — an older joiner sends none of them and still links one-way, as it always did. */
function parseJoiner(p: { machineId?: unknown; kind?: unknown; label?: unknown }): Omit<LinkedPeer, 'pub'> {
  const kind = p.kind === 'machine' || p.kind === 'viewer' ? p.kind : undefined
  const machineId = kind === 'machine' && typeof p.machineId === 'string' && MACHINE_ID_RE.test(p.machineId) ? p.machineId : undefined
  const label = pairedLabel(p.label) ?? 'harness link'
  return { kind: kind === 'machine' && !machineId ? undefined : kind, machineId, label }
}

export class E2eeManager {
  private store = new E2eeStore()
  private groupKey: Uint8Array
  private epoch: string
  private groupCounter = 0
  private slot: PairSlot | null = null
  private sessions = new Map<string, Session>()
  private attempts: number[] = [] // timestamps of FAILED pairings — anti online-guessing rate limit
  private pwSlots = new Map<string, PwPairSlot>() // connId -> in-progress password-PAKE attempt
  private sessionGoneTold = new Map<string, number>() // connId -> when it was last told its session is gone
  /** connId -> the hello waiting on `onUnknownHello` there. A newer hello, or the connection going, ends
   *  the wait: the reply to the older one would open a session the client has moved on from. */
  private helloWaits = new Map<string, number>()
  private helloSeq = 0
  private now: () => number
  constructor(private deps: E2eeManagerDeps, now: () => number = () => Date.now()) {
    this.store.init()
    this.groupKey = crypto32()
    this.epoch = hex8()
    this.now = now
  }

  fingerprint(): string { return this.store.fingerprint() }

  // ── persistent remote password (`harness remote-password set|clear|status`) ──────────────────────
  setRemotePassword(password: string): Promise<{ fingerprint: string }> {
    return this.store.setRemotePassword(this.deps.machineId, password)
  }
  clearRemotePassword(): void {
    this.store.clearRemotePassword()
  }
  remotePasswordStatus(): { hasPassword: boolean; fingerprint: string | null; setAt: number | null } {
    return {
      hasPassword: this.store.hasRemotePassword(),
      fingerprint: this.store.remotePasswordFingerprint(),
      setAt: this.store.remotePasswordSetAt(),
    }
  }
  /** Trust `pub` as a client of this machine (idempotent; keeps the original pairedAt). Used for the
   *  mutual half of a password link — the machine whose password the joiner proved is trusted back — and
   *  for members learned from a trust-group sync. */
  trustPeer(peer: LinkedPeer, at = this.now()): void {
    const existing = this.store.pairedPeer(peer.pub)
    if (existing && existing.label === peer.label && existing.machineId === peer.machineId && existing.kind === peer.kind
      && !!existing.shared === !!peer.shared && existing.sharedWith === peer.sharedWith) return
    this.store.addPaired(peer.pub, peer.label, existing?.pairedAt ?? at, existing?.role ?? 'web', { machineId: peer.machineId, kind: peer.kind, shared: peer.shared, sharedWith: peer.sharedWith })
  }
  /** Stop trusting `pub` (a no-op when it is not paired): the same path as `harness unpair`. */
  untrustPeer(pub: string): boolean {
    if (!this.store.isPaired(pub)) return false
    this.revokeIdentity(pub)
    return true
  }
  pairedPeers(): ReturnType<E2eeStore['list']> { return this.store.list() }
  /** paired.json changed under this manager (accountTrust.ts moved another account's keys in): read it
   *  again, and close every session of a key no longer paired, as an unpair would — a browser of the
   *  account this machine left must not keep its session, nor the group key. */
  reloadPaired(): void {
    const before = this.store.list().map((p) => p.identityPub)
    this.store.reloadPaired()
    const gone = before.filter((pub) => !this.store.isPaired(pub))
    for (const pub of gone) this.denyAndDropSessionsFor(pub)
    if (gone.length) this.rotateGroupKey()
  }
  hasSession(connId: string): boolean { return this.sessions.has(connId) }
  sessionIdentity(connId: string): string | null { return this.sessions.get(connId)?.webIdentityPub ?? null }
  sessionRole(connId: string): C.PairRole | null { return this.sessions.get(connId)?.role ?? null }
  /** The label this connection's identity was paired under, or null for a session with none on file. */
  sessionLabel(connId: string): string | null {
    const pub = this.sessions.get(connId)?.webIdentityPub
    return pub ? this.store.pairedLabel(pub) : null
  }
  deviceConnected(): boolean { return [...this.sessions.values()].some((s) => s.role === 'device') }
  dropSessionsByRole(role: C.PairRole, preserve: (connId: string) => boolean = () => false): void {
    for (const [connId, s] of [...this.sessions.entries()]) {
      if (s.role === role && !preserve(connId)) this.dropSession(connId)
    }
  }

  /** A browser currently waiting to pair (for `/api/status`), or null. `active` = CPace running. */
  pendingConnection(): string | null { return this.slot?.connId ?? null }
  pendingPair(): PendingPairInfo | null {
    if (!this.slot) return null
    return {
      label: this.slot.label,
      expiresAt: this.slot.expiresAt,
      active: !!this.slot.active,
      role: this.slot.role,
      pairId: this.slot.pairIdB64,
    }
  }

  // ── pair management (list / revoke) ──────────────────────────────────────────────────────────────

  /** Paired clients, most recent first, with a comparable fingerprint. */
  listPaired(currentConnId?: string): Array<{ fingerprint: string; label: string; pairedAt: number; online: boolean; role: C.PairRole; current: boolean }> {
    const onlinePubs = new Set([...this.sessions.values()].map((s) => s.webIdentityPub))
    const currentPub = currentConnId ? this.sessions.get(currentConnId)?.webIdentityPub : undefined
    return this.store.list()
      .map((p) => ({ fingerprint: C.fingerprint(C.b64d(p.identityPub)), label: p.label, pairedAt: p.pairedAt, online: onlinePubs.has(p.identityPub), role: p.role, current: p.identityPub === currentPub }))
      .sort((a, b) => b.pairedAt - a.pairedAt)
  }

  private findPaired(selector: string): { ok: true; identityPub: string; label: string; fingerprint: string } | { ok: false; error: 'NOT_FOUND' | 'AMBIGUOUS' } {
    const paired = this.store.list()
    const norm = (s: string): string => s.toUpperCase().replace(/[·\s-]/g, '')
    const sel = norm(selector)
    const idx = /^\d+$/.test(selector) ? Number(selector) - 1 : -1
    const byIndex = idx >= 0 ? this.listPaired()[idx] : undefined
    let target = byIndex ? paired.find((p) => C.fingerprint(C.b64d(p.identityPub)) === byIndex.fingerprint) : undefined
    if (!target) {
      const matches = paired.filter((p) => norm(C.fingerprint(C.b64d(p.identityPub))).startsWith(sel))
      if (matches.length > 1) return { ok: false, error: 'AMBIGUOUS' }
      target = matches[0]
    }
    if (!target) return { ok: false, error: 'NOT_FOUND' }
    return { ok: true, identityPub: target.identityPub, label: target.label, fingerprint: C.fingerprint(C.b64d(target.identityPub)) }
  }

  private revokeIdentity(identityPub: string): void {
    this.store.removePaired(identityPub)
    try { this.deps.onIdentityRevoked?.(identityPub) } catch { /* Optional device cleanup must not interrupt trust revocation. */ }
    this.denyAndDropSessionsFor(identityPub)
    this.rotateGroupKey()
  }

  /** Revoke ONE paired browser, selected by fingerprint (full or unique prefix, case/·-insensitive) or
   *  by 1-based index into listPaired(). Signals any online session to re-pair + rotates the group key. */
  revoke(selector: string): { ok: true; label: string; fingerprint: string } | { ok: false; error: 'NOT_FOUND' | 'AMBIGUOUS' } {
    const found = this.findPaired(selector)
    if (!found.ok) return found
    this.revokeIdentity(found.identityPub)
    this.noteUnpaired(found.identityPub)
    return { ok: true, label: found.label, fingerprint: found.fingerprint }
  }

  revokeFromTrustedWeb(connId: string, p: Record<string, unknown>): void {
    const requestId = p.requestId
    const selector = typeof p.selector === 'string' ? p.selector : ''
    const payload = selector ? this.findPaired(selector) : { ok: false as const, error: 'MISSING_SELECTOR' }
    if (payload.ok) {
      const reply = this.wrapRpcReply(connId, 'e2ee_pairing_unpair_result', requestId, { ok: true, label: payload.label, fingerprint: payload.fingerprint })
      if (reply) this.deps.sendTo(connId, reply)
      this.revokeIdentity(payload.identityPub)
      this.noteUnpaired(payload.identityPub)
      return
    }
    const reply = this.wrapRpcReply(connId, 'e2ee_pairing_unpair_result', requestId, { error: payload.error })
    if (reply) this.deps.sendTo(connId, reply)
  }

  /** Revoke every paired browser. Signals all online sessions to re-pair + rotates the group key. */
  revokeAll(): { count: number } {
    const count = this.store.count()
    const unpaired = this.store.list().map((p) => p.identityPub)
    // Device cleanup first: it needs the live session to seal a pair.revoke frame before deny drops it.
    for (const paired of this.store.list()) { try { this.deps.onIdentityRevoked?.(paired.identityPub) } catch { /* Continue revoking every stored identity. */ } }
    for (const s of [...this.sessions.entries()]) { this.deny(s[0]); this.dropSession(s[0]) }
    this.store.clear()
    this.rotateGroupKey()
    for (const pub of unpaired) this.noteUnpaired(pub)
    return { count }
  }

  private noteUnpaired(identityPub: string): void {
    try { this.deps.onUnpaired?.(identityPub) } catch { /* the unpairing itself stands */ }
  }

  revokeAllFromTrustedWeb(connId: string, requestId: unknown): void {
    const count = this.store.count()
    const reply = this.wrapRpcReply(connId, 'e2ee_pairings_unpair_all_result', requestId, { count })
    if (reply) this.deps.sendTo(connId, reply)
    this.revokeAll()
  }

  private deny(connId: string): void {
    this.deps.sendTo(connId, { type: 'e2e_denied', payload: { reason: 'revoked' } })
  }
  private denyAndDropSessionsFor(identityPubB64: string): void {
    for (const [connId, s] of [...this.sessions.entries()]) {
      if (s.webIdentityPub === identityPubB64) { this.deny(connId); this.dropSession(connId) }
    }
  }
  /** New group key + epoch; re-deliver to the REMAINING (still-paired) sessions so a revoked browser
   *  (which still holds the old key) can no longer decrypt subsequent events. */
  private rotateGroupKey(): void {
    this.groupKey = crypto32()
    this.epoch = hex8()
    this.groupCounter = 0
    for (const [connId, s] of this.sessions.entries()) {
      const enc = C.aeadSeal(s.s2c, s.s2cCounter++, C.utf8('e2e-rekey'), C.utf8(JSON.stringify({ groupKey: C.b64e(this.groupKeyFor(s.webIdentityPub)), epoch: this.epoch })))
      this.deps.sendTo(connId, { type: 'e2e_rekey', payload: { enc: C.b64e(enc), n: s.s2cCounter - 1 } })
    }
  }

  /** The group key a session is handed: the machine's, except for a GUEST (a key trusted only because the
   *  machine is shared, gateway/sharedTrust.ts), which gets a throwaway one. A guest must not open the
   *  owner's broadcasts; what concerns its own harnesses is sealed for its session alone (`wrapFor`),
   *  and the backend sends it nothing else (backend/src/lib/hub.ts). */
  private groupKeyFor(identityPub: string): Uint8Array {
    return this.store.pairedPeer(identityPub)?.shared ? crypto32() : this.groupKey
  }

  /** The sessions of the guest `email` (docs/plans/2026-10-19-guest-machine-sharing-plan.md). */
  guestSessions(email: string): string[] {
    if (!email) return []
    const out: string[] = []
    for (const [connId, s] of this.sessions.entries()) {
      const peer = this.store.pairedPeer(s.webIdentityPub)
      if (peer?.shared && peer.sharedWith === email) out.push(connId)
    }
    return out
  }

  /** An `up` event sealed for ONE session: its content under that session's key, as a reply is. Null
   *  without a session. A frame that carries no content passes through as `wrapUp` passes it. */
  wrapFor(connId: string, frame: Frame): Frame | null {
    const s = this.sessions.get(connId)
    if (!s) return null
    const type = frame.type as string | undefined
    if (!sealsForWeb(type)) return frame
    return { ...frame, payload: C.wrapPayload(s.s2c, 'p', s.s2cCounter++, type, frame.dbSessionId as string | undefined, frame.payload) }
  }

  // ── outbound wrapping ──────────────────────────────────────────────────────────────────────────

  /** Encrypt a broadcast `up` event under the group key if it carries user content; else pass through. */
  wrapUp(frame: Frame): Frame {
    const type = frame.type as string | undefined
    if (!sealsForWeb(type)) return frame
    const wrapped = C.wrapPayload(this.groupKey, 'g', this.groupCounter++, type, frame.dbSessionId as string | undefined, frame.payload, this.epoch)
    return { ...frame, payload: wrapped }
  }

  /** Encrypt DEVICE-audience user/data frames under the group key. Same group key/epoch/counter space as
   *  wrapUp: one monotonic counter → unique nonces. A paired device holds the group key (delivered in
   *  e2e_welcome); an UNPAIRED device can't decrypt → mandatory pairing. */
  wrapCommander(frame: Frame): Frame {
    const type = frame.type as string | undefined
    // `commander_question` carries the question + its option labels — user content, same as a recap, so it
    // rides ciphertext too. The device's decrypt is envelope-driven (any `payload.__e2e`), so existing
    // firmware handles it with no change.
    if (!type || (type !== 'commander_event' && type !== 'commander_question' && !C.isEncryptedUpType(type))) return frame
    const wrapped = C.wrapPayload(this.groupKey, 'g', this.groupCounter++, type, frame.dbSessionId as string | undefined, frame.payload, this.epoch)
    return { ...frame, payload: wrapped }
  }

  /** Build an encrypted, connection-targeted RPC reply, or null if this conn has no session. */
  wrapRpcReply(connId: string, resultType: string, requestId: unknown, payload: Record<string, unknown>): Frame | null {
    const s = this.sessions.get(connId)
    if (!s) return null
    const full = { requestId, ...payload }
    const wrapped = C.wrapPayload(s.s2c, 'p', s.s2cCounter++, resultType, undefined, full)
    return { type: resultType, payload: wrapped }
  }

  /** Measure the exact encrypted targeted RPC frame without consuming the send counter. */
  rpcReplyFrameBytes(connId: string, resultType: string, requestId: unknown, payload: Record<string, unknown>): number | null {
    const s = this.sessions.get(connId)
    if (!s) return null
    const full = { requestId, ...payload }
    const wrapped = C.wrapPayload(s.s2c, 'p', s.s2cCounter, resultType, undefined, full)
    return Buffer.byteLength(JSON.stringify({ type: resultType, payload: wrapped }), 'utf8')
  }

  /** Pairwise-encrypt a connection-targeted non-RPC frame (terminal ready/output/keyframe/error). */
  wrapTarget(connId: string, type: string, payload: Record<string, unknown>): Frame | null {
    const s = this.sessions.get(connId)
    if (!s) return null
    const wrapped = C.wrapPayload(s.s2c, 'p', s.s2cCounter++, type, undefined, payload)
    return { type, payload: wrapped }
  }

  /** Pairwise-encrypt binary terminal data in a domain-separated counter space. */
  wrapTerminalBinary(connId: string, clear: TerminalBinaryClear): Uint8Array | null {
    const session = this.sessions.get(connId)
    if (!session) return null
    const sealed = sealTerminalBinary(session.terminalS2c, session.terminalS2cCounter, clear)
    if (!sealed) return null
    session.terminalS2cCounter++
    return sealed
  }

  /** Open one client→adapter binary terminal frame with the existing pairwise
   * replay guard. Authenticated but stale/reordered frames are dropped. */
  unwrapTerminalBinary(connId: string, raw: Uint8Array): TerminalBinaryClear | null {
    const session = this.sessions.get(connId)
    if (!session) return null
    const envelope = parseTerminalBinaryEnvelope(raw)
    if (!envelope || !session.terminalC2sRecv.allows(envelope.counter)) return null
    const opened = openTerminalBinary(session.terminalC2s, raw)
    if (!opened) return null
    session.terminalC2sRecv.commit(opened.counter)
    return opened.frame
  }

  // ── inbound down `message` decryption ────────────────────────────────────────────────────────────

  /** Decrypt a sealed down-frame. Plaintext or undecryptable → null (drop): a frame that reaches here
   *  came from the relay, and the relay is not trusted to speak for any client. */
  unwrapDown(connId: string, frame: Frame): Frame | null {
    const payload = frame.payload as Record<string, unknown> | undefined
    if (!payload || !C.isWrapped(payload)) return null
    const s = this.sessions.get(connId)
    if (!s) return null
    const env = (payload as C.WrappedPayload).__e2e
    // The relay is NOT trusted, and a client can be buggy/hostile: a structurally malformed envelope
    // (__e2e null, missing/non-string ct, non-number n) would make the deref / b64d below throw and
    // crash the daemon. Anything that isn't the expected shape is dropped like an undecryptable frame.
    if (!env || typeof env !== 'object' || typeof env.n !== 'number' || typeof env.ct !== 'string') return null
    if (!s.c2sRecv.allows(env.n)) return null
    const plain = C.unwrapPayload(s.c2s, env, frame.type as string, frame.dbSessionId as string | undefined)
    if (plain === null) return null
    s.c2sRecv.commit(env.n)
    return { ...frame, payload: plain }
  }

  /**
   * What to tell a client whose sealed frame found no session here, or null when it has one (a frame
   * that does not open on a live session is the relay's or a replay, and is dropped without a word).
   *
   * No session most often means this machine's daemon restarted since the client's hello while the relay
   * kept the client's socket: the phone app keeps it through `node_status` offline (mobile
   * app_state.dart `_applyNodeStatus`). Its frames then reached a daemon that could not open them, and
   * were dropped silently: a message vanished, and a request waited out its timeout before the app
   * dialled again (round 34, `e2e/relay.e2e.ts`). Told, the client opens a new session at once and
   * knows the frame was not taken. The frame is named by its outer type and envelope counter, which the
   * relay already sees; nothing sealed is echoed. At most once a second per connection.
   */
  sessionGone(connId: string, frame: Frame): Frame | null {
    const counter = (frame.payload as { __e2e?: { n?: unknown } } | undefined)?.__e2e?.n
    return this.tellSessionGone(connId, { type: frame.type, ...(typeof counter === 'number' ? { n: counter } : {}) })
  }

  /** The same, for binary terminal bytes (keystrokes, a paste) sealed for a session this process never
   *  had: those vanished silently too. Named by the frame's clear header, its kind and counter, which
   *  the relay already reads; the same once-a-second allowance per connection as a sealed frame. */
  terminalSessionGone(connId: string, raw: Uint8Array): Frame | null {
    const envelope = parseTerminalBinaryEnvelope(raw)
    return this.tellSessionGone(connId, { type: 'terminal_binary', ...(envelope ? { kind: envelope.kind, n: envelope.counter } : {}) })
  }

  private tellSessionGone(connId: string, refused: Record<string, unknown>): Frame | null {
    if (this.sessions.has(connId)) return null
    const now = this.now()
    const last = this.sessionGoneTold.get(connId)
    if (last !== undefined && now - last < SESSION_GONE_EVERY_MS) return null
    this.sessionGoneTold.delete(connId)
    this.sessionGoneTold.set(connId, now)
    if (this.sessionGoneTold.size > SESSION_GONE_REMEMBERED) this.sessionGoneTold.delete(this.sessionGoneTold.keys().next().value!)
    return { type: 'e2e_session_unknown', payload: { refused } }
  }

  // ── e2e_* frame handling (returns true if consumed) ──────────────────────────────────────────────

  handleFrame(connId: string, frame: Frame): boolean {
    const type = frame.type as string
    const payload = (frame.payload ?? {}) as Record<string, unknown>
    switch (type) {
      case 'e2e_status': return this.onStatus(connId, payload)
      case 'e2e_pair_intent': return this.onPairIntent(connId, payload)
      case 'e2e_pair_cancel': return this.onPairCancel(connId, payload)
      case 'e2e_pake': return this.onPake(connId, payload)
      case 'e2e_pw_pair_intent': return this.onPwPairIntent(connId, payload)
      case 'e2e_pw_pake': return this.onPwPake(connId, payload)
      case 'e2e_hello': return this.onHello(connId, payload)
      default: return type.startsWith('e2e_') // consume unknown e2e_* silently
    }
  }

  private onStatus(connId: string, p: Record<string, unknown>): boolean {
    const identityPub = typeof p.identityPub === 'string' ? p.identityPub : ''
    this.deps.sendTo(connId, {
      type: 'e2e_status_result',
      payload: {
        requestId: p.requestId,
        supported: true,
        enabled: true, // mandatory: user events are always group-encrypted
        paired: identityPub ? this.store.isPaired(identityPub) : false,
        fingerprint: this.fingerprint(),
      },
    })
    return true
  }

  private onPairIntent(connId: string, p: Record<string, unknown>): boolean {
    if (this.slot?.active) {
      this.deps.sendTo(connId, { type: 'e2e_pair_intent_result', payload: { requestId: p.requestId, error: 'PAIRING_BUSY' } })
      return true
    }
    if (this.slot) clearTimeout(this.slot.ttlTimer)
    const pairIdB64 = typeof p.pairId === 'string' ? p.pairId : ''
    const label = typeof p.label === 'string' ? p.label.slice(0, 60) : 'browser'
    const role: C.PairRole = p.role === 'device' ? 'device' : 'web'  // the client declares its class
    if (!pairIdB64) { this.deps.sendTo(connId, { type: 'e2e_pair_intent_result', payload: { requestId: p.requestId, error: 'BAD_INTENT' } }); return true }
    const ttlTimer = setTimeout(() => { if (this.slot && !this.slot.active) this.slot = null }, PAIR_TTL_MS)
    this.slot = { connId, pairId: C.b64d(pairIdB64), pairIdB64, label, role, expiresAt: this.now() + PAIR_TTL_MS, ttlTimer }
    this.deps.sendTo(connId, { type: 'e2e_pair_intent_result', payload: { requestId: p.requestId, accepted: true, ttl: PAIR_TTL_MS / 1000 } })
    if (role === 'device') this.notifyTrustedWebDevicePair(this.slot)
    return true
  }

  private notifyTrustedWebDevicePair(slot: PairSlot): void {
    const payload = {
      machineId: this.deps.machineId,
      label: slot.label,
      pairId: slot.pairIdB64,
      expiresAt: slot.expiresAt,
      computerFingerprint: this.fingerprint(),
    }
    this.deps.sendUser?.({ type: 'device_e2ee_pair_pending', payload })
    for (const [connId, session] of this.sessions.entries()) {
      if (session.role !== 'web') continue
      const wrapped = this.wrapTarget(connId, 'device_e2ee_pair_pending', payload)
      if (wrapped) this.deps.sendTo(connId, wrapped)
    }
  }

  private notifyTrustedWebDevicePairCleared(slot: PairSlot, result: 'paired' | 'failed' | 'cancelled'): void {
    if (slot.role !== 'device') return
    const payload = {
      machineId: this.deps.machineId,
      pairId: slot.pairIdB64,
      result,
      computerFingerprint: this.fingerprint(),
    }
    this.deps.sendUser?.({ type: 'device_e2ee_pair_cleared', payload })
    for (const [connId, session] of this.sessions.entries()) {
      if (session.role !== 'web') continue
      const wrapped = this.wrapTarget(connId, 'device_e2ee_pair_cleared', payload)
      if (wrapped) this.deps.sendTo(connId, wrapped)
    }
  }

  private onPairCancel(connId: string, p: Record<string, unknown>): boolean {
    const pairId = typeof p.pairId === 'string' ? p.pairId : ''
    const slot = this.slot
    if (!slot || slot.role !== 'device' || slot.connId !== connId || slot.pairIdB64 !== pairId) return true
    this.notifyTrustedWebDevicePairCleared(slot, 'cancelled')
    const resolve = slot.active?.resolve
    this.clearSlot()
    resolve?.({ ok: false, error: 'CANCELLED' })
    return true
  }

  async pairDeviceFromTrustedWeb(connId: string, p: Record<string, unknown>): Promise<void> {
    const requestId = p.requestId
    const session = this.sessions.get(connId)
    if (!session || session.role !== 'web') {
      this.deps.sendTo(connId, { type: 'device_e2ee_pair_result', payload: { requestId, error: 'UNTRUSTED_WEB' } })
      return
    }
    const slot = this.slot
    const pairId = typeof p.pairId === 'string' ? p.pairId : ''
    if (!slot || slot.role !== 'device') {
      const reply = this.wrapRpcReply(connId, 'device_e2ee_pair_result', requestId, { error: 'NO_DEVICE_INTENT' })
      if (reply) this.deps.sendTo(connId, reply)
      return
    }
    if (!pairId || pairId !== slot.pairIdB64) {
      const reply = this.wrapRpcReply(connId, 'device_e2ee_pair_result', requestId, { error: 'STALE_PAIR' })
      if (reply) this.deps.sendTo(connId, reply)
      return
    }
    const code = C.normalizeCode(String(p.code ?? ''))
    if (!code) {
      const reply = this.wrapRpcReply(connId, 'device_e2ee_pair_result', requestId, { error: 'BAD_CODE' })
      if (reply) this.deps.sendTo(connId, reply)
      return
    }
    const result = await this.onPair(code)
    const payload = result.ok
      ? { ok: true, label: result.label, fingerprint: result.fingerprint }
      : { error: result.error }
    const reply = this.wrapRpcReply(connId, 'device_e2ee_pair_result', requestId, payload)
    if (reply) this.deps.sendTo(connId, reply)
  }

  /** A linked browser can arm phone pairing on its own machine, just as the local desktop can.
   * The code travels only inside the existing encrypted session. Possessing an account token or
   * an observer link is not enough; the caller must already hold a paired web identity. */
  async pairPhoneFromTrustedWeb(connId: string, p: Record<string, unknown>): Promise<void> {
    if (this.sessions.get(connId)?.role !== 'web') return
    const reply = (payload: Record<string, unknown>): void => {
      const frame = this.wrapRpcReply(connId, 'phone_pair_result', p.requestId, payload)
      if (frame) this.deps.sendTo(connId, frame)
    }
    const code = C.normalizeCode(typeof p.code === 'string' ? p.code : '')
    if (!/^[A-Z2-9]{16}$/.test(code)) { reply({ error: 'BAD_CODE' }); return }
    // A phone uses the web role. Never consume a hardware pairing or the caller's own intent.
    if (!this.slot || this.slot.role !== 'web' || this.slot.connId === connId) {
      reply({ error: 'NO_INTENT' }); return
    }
    const result = await this.onPair(code)
    reply(result.ok ? { ok: true, label: result.label, fingerprint: result.fingerprint } : { error: result.error })
  }

  /** Called by the hook server when the user runs `harness pair <code>`. Resolves when done/failed. */
  onPair(code: string): Promise<PairResult> {
    return new Promise<PairResult>((resolve) => {
      // rate limit
      // Rate-limit only recent FAILED attempts (anti online-guessing) — successful pairings don't
      // count, so a user can legitimately pair several browsers in a row.
      const t = this.now()
      this.attempts = this.attempts.filter((a) => t - a < RATE_WINDOW_MS)
      if (this.attempts.length >= RATE_MAX) { resolve({ ok: false, error: 'RATE_LIMITED' }); return }
      const slot = this.slot
      if (!slot) { resolve({ ok: false, error: 'NO_INTENT' }); return }
      if (slot.active) { resolve({ ok: false, error: 'BUSY' }); return }
      if (this.now() > slot.expiresAt) { this.slot = null; resolve({ ok: false, error: 'EXPIRED' }); return }
      if (!(this.deps.isConnectionAvailable?.(slot.connId) ?? this.deps.isConnected())) { resolve({ ok: false, error: 'BACKEND_DOWN' }); return }
      clearTimeout(slot.ttlTimer)

      const ci = C.pairContext(this.deps.machineId, slot.role)
      const g = C.cpaceGenerator(code, slot.pairId, ci)
      const { y, Y } = C.cpaceStart(g)
      const roundTimer = setTimeout(() => this.failPair('TIMEOUT'), ROUND_TIMEOUT_MS)
      slot.active = { y, Ya: Y, resolve, roundTimer }
      // round 1 → web (targeted)
      this.deps.sendTo(slot.connId, { type: 'e2e_pake', payload: { pairId: slot.pairIdB64, round: 1, ya: C.b64e(Y) } })
    })
  }

  private onPake(connId: string, p: Record<string, unknown>): boolean {
    const slot = this.slot
    if (!slot?.active) return true
    if (typeof p.pairId !== 'string' || p.pairId !== slot.pairIdB64) return true // not our session
    const round = Number(p.round)
    const ci = C.pairContext(this.deps.machineId, slot.role)
    try {
      if (round === 2) {
        const Yb = C.b64d(String(p.yb))
        const K = C.cpaceShared(Yb, slot.active.y)
        const isk = C.cpaceISK(slot.pairId, K, slot.active.Ya, Yb)
        const th = C.transcriptHash(slot.pairId, ci, slot.active.Ya, Yb)
        const kc = C.kcKeys(isk, ci)
        if (!C.macVerify(kc.web, th, C.b64d(String(p.mac)))) { this.failPair('CODE_MISMATCH'); return true }
        slot.active.isk = isk
        slot.active.th = th
        // round 3 → adapter MAC + sealed identity (proof of possession)
        const id = this.store.getIdentity()
        const sealed = C.aeadSeal(C.pairKey(isk, ci), 3, C.utf8('e2e-id'), C.utf8(JSON.stringify({ id: C.b64e(id.pub), sig: C.b64e(C.pairBindSig(id.priv, th)) })))
        this.resetRoundTimer(slot)
        this.deps.sendTo(connId, { type: 'e2e_pake', payload: { pairId: slot.pairIdB64, round: 3, mac: C.b64e(C.macTag(kc.adapter, th)), enc: C.b64e(sealed) } })
        return true
      }
      if (round === 4) {
        if (!slot.active.isk || !slot.active.th) { this.failPair('TIMEOUT'); return true }
        const opened = C.aeadOpen(C.pairKey(slot.active.isk, ci), 4, C.utf8('e2e-id'), C.b64d(String(p.enc)))
        if (!opened) { this.failPair('CODE_MISMATCH'); return true }
        const webId = JSON.parse(new TextDecoder().decode(opened)) as { id: string; sig: string }
        if (!C.pairBindVerify(C.b64d(webId.id), slot.active.th, C.b64d(webId.sig))) { this.failPair('CODE_MISMATCH'); return true }
        // pin the paired client identity
        this.store.addPaired(webId.id, slot.label, this.now(), slot.role)
        this.deps.onIdentityPaired?.(connId, webId.id)
        const fp = this.fingerprint()
        this.deps.sendTo(connId, { type: 'e2e_pake', payload: { pairId: slot.pairIdB64, round: 5, ok: true, fingerprint: fp } })
        const resolve = slot.active.resolve
        this.notifyTrustedWebDevicePairCleared(slot, 'paired')
        this.clearSlot()
        resolve({ ok: true, label: slot.label, fingerprint: fp })
        return true
      }
    } catch {
      this.failPair('CODE_MISMATCH')
    }
    return true
  }

  // ── persistent remote-password pairing (`e2e_pw_pair_intent` / `e2e_pw_pake`) ────────────────────
  // Structurally the same 5-round CPace dance as onPairIntent/onPake above, but driven by
  // store.remotePasswordVerifier() instead of a live human-armed code, keyed by connId (pwSlots) so
  // any number of joiner machines can be mid-handshake at once, with no local "arm" step at all.

  private onPwPairIntent(connId: string, p: Record<string, unknown>): boolean {
    const requestId = p.requestId
    const fail = (error: string, extra?: Record<string, unknown>): void => {
      this.deps.sendTo(connId, { type: 'e2e_pw_pair_result', payload: { requestId, ok: false, error, ...extra } })
    }
    if (!this.store.hasRemotePassword()) { fail('NO_REMOTE_PASSWORD'); return true }
    // Rejected BEFORE any crypto runs — a locked-out caller gets no oracle at all, not even the cost
    // of one CPace round, while it waits out the lockout.
    const lockedUntil = this.store.pwLockedUntil()
    if (lockedUntil) { fail('RATE_LIMITED', { retryAt: lockedUntil }); return true }
    const sidB64 = typeof p.sid === 'string' ? p.sid : ''
    if (!sidB64) { fail('BAD_INTENT'); return true }
    if (this.pwSlots.has(connId)) this.clearPwSlot(connId) // a retry on the same conn replaces the old attempt
    if (this.pwSlots.size >= MAX_PW_SLOTS) { fail('BUSY'); return true }
    const verifier = this.store.remotePasswordVerifier()
    if (!verifier) { fail('NO_REMOTE_PASSWORD'); return true } // race: cleared between the two checks above
    const sid = C.b64d(sidB64)
    const ci = pwContext(this.deps.machineId)
    const g = pwCpaceGenerator(verifier, sid, ci)
    const { y, Y } = C.cpaceStart(g)
    const roundTimer = setTimeout(() => this.failPwPair(connId, 'TIMEOUT'), PW_ROUND_TIMEOUT_MS)
    this.pwSlots.set(connId, { connId, sid, sidB64, y, Ya: Y, roundTimer })
    // round 1 → the joiner (targeted), no human interaction required on this side
    this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: sidB64, round: 1, ya: C.b64e(Y) } })
    return true
  }

  private onPwPake(connId: string, p: Record<string, unknown>): boolean {
    const slot = this.pwSlots.get(connId)
    if (!slot) return true
    if (typeof p.sid !== 'string' || p.sid !== slot.sidB64) return true // not our attempt
    const round = Number(p.round)
    const ci = pwContext(this.deps.machineId)
    try {
      if (round === 2) {
        // Judged against the lockout as it stands NOW, not as it stood at the intent: a lockout that
        // began meanwhile covers this attempt too, and a refused attempt is not counted or evaluated.
        const lockedUntil = this.store.pwLockedUntil()
        if (lockedUntil) { this.failPwPair(connId, 'RATE_LIMITED', false, { retryAt: lockedUntil }); return true }
        const Yb = C.b64d(String(p.yb))
        const K = C.cpaceShared(Yb, slot.y)
        const isk = C.cpaceISK(slot.sid, K, slot.Ya, Yb)
        const th = C.transcriptHash(slot.sid, ci, slot.Ya, Yb)
        const kc = C.kcKeys(isk, ci)
        // Wrong password → wrong generator → this MAC can never verify. Counts toward the lockout;
        // the error told to the caller never says more than "wrong password".
        if (!C.macVerify(kc.web, th, C.b64d(String(p.mac)))) { this.failPwPair(connId, 'WRONG_PASSWORD', true); return true }
        slot.isk = isk
        slot.th = th
        const id = this.store.getIdentity()
        const sealed = C.aeadSeal(C.pairKey(isk, ci), 3, C.utf8('e2e-id'), C.utf8(JSON.stringify({ id: C.b64e(id.pub), sig: C.b64e(C.pairBindSig(id.priv, th)) })))
        this.resetPwRoundTimer(slot)
        this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: slot.sidB64, round: 3, mac: C.b64e(C.macTag(kc.adapter, th)), enc: C.b64e(sealed) } })
        return true
      }
      if (round === 4) {
        if (!slot.isk || !slot.th) { this.failPwPair(connId, 'TIMEOUT'); return true }
        const opened = C.aeadOpen(C.pairKey(slot.isk, ci), 4, C.utf8('e2e-id'), C.b64d(String(p.enc)))
        if (!opened) { this.failPwPair(connId, 'WRONG_PASSWORD', true); return true }
        const joinerId = JSON.parse(new TextDecoder().decode(opened)) as { id: string; sig: string; machineId?: unknown; kind?: unknown; label?: unknown }
        if (!C.pairBindVerify(C.b64d(joinerId.id), slot.th, C.b64d(joinerId.sig))) { this.failPwPair(connId, 'WRONG_PASSWORD', true); return true }
        // Full success: trust the joiner exactly as if it were a paired browser session (same call/role
        // onSetupClaim uses) — this is what lets it relay through this machine's data plane.
        //
        // Named by the joiner when it says who it is ("Dee's iPhone"), inside the sealed identity, so the
        // name is as authenticated as the key — and so the Mac's list of paired devices reads as devices.
        // A joiner that predates the field (`harness link connect`, an older phone) stays "harness link".
        // A newer joiner also says what it is: a machine gets pinned back (mutual link — it can be dialed
        // from here without its own password).
        const joiner = parseJoiner(joinerId)
        this.store.addPaired(joinerId.id, joiner.label, this.now(), 'web', { machineId: joiner.machineId, kind: joiner.kind })
        this.store.notePwSuccess()
        try { this.deps.onPeerLinked?.({ pub: joinerId.id, ...joiner }) } catch { /* the link itself stands */ }
        const fp = this.fingerprint()
        this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: slot.sidB64, round: 5, ok: true, fingerprint: fp, mutual: 1 } })
        this.clearPwSlot(connId)
        return true
      }
    } catch {
      this.failPwPair(connId, 'WRONG_PASSWORD', true)
    }
    return true
  }

  private resetPwRoundTimer(slot: PwPairSlot): void {
    clearTimeout(slot.roundTimer)
    slot.roundTimer = setTimeout(() => this.failPwPair(slot.connId, 'TIMEOUT'), PW_ROUND_TIMEOUT_MS)
  }

  /** `countsAsFailure` is true only for an actual wrong-password verification failure — a timeout or
   *  protocol hiccup (dropped connection, stale round) doesn't prove anything about a guessing
   *  attempt and shouldn't cost the caller part of their lockout budget. */
  private failPwPair(connId: string, error: string, countsAsFailure = false, extra?: Record<string, unknown>): void {
    const slot = this.pwSlots.get(connId)
    if (!slot) return
    this.clearPwSlot(connId)
    this.deps.sendTo(connId, { type: 'e2e_pw_pake', payload: { sid: slot.sidB64, round: 5, error, ...extra } })
    if (countsAsFailure) {
      const { lockedUntil } = this.store.notePwFailure()
      if (lockedUntil) this.notifyRemotePasswordLocked(lockedUntil) // fresh lockout — pwLockedUntil() was
      // null before this call (onPwPairIntent already rejects while locked), so any non-null result
      // here is a NOT-locked → locked transition, never a re-notify of an existing one.
    }
  }

  private clearPwSlot(connId: string): void {
    const slot = this.pwSlots.get(connId)
    if (slot) clearTimeout(slot.roundTimer)
    this.pwSlots.delete(connId)
  }

  private notifyRemotePasswordLocked(lockedUntil: number): void {
    const payload = { machineId: this.deps.machineId, lockedUntil }
    this.deps.sendUser?.({ type: 'remote_password_locked', payload })
    for (const [connId, session] of this.sessions.entries()) {
      if (session.role !== 'web') continue
      const wrapped = this.wrapTarget(connId, 'remote_password_locked', payload)
      if (wrapped) this.deps.sendTo(connId, wrapped)
    }
  }

  private onHello(connId: string, p: Record<string, unknown>): boolean {
    const identityPub = String(p.identityPub ?? '')
    const ephPubB64 = String(p.ephPub ?? '')
    const sigB64 = String(p.sig ?? '')
    if (!identityPub || !ephPubB64 || !sigB64) return true
    const webEphPub = C.b64d(ephPubB64)
    // The signature first: only a hello the key's holder signed may make this machine re-read the log, and
    // a forged one must not end the wait of a real one on the same connection.
    if (!C.helloVerify(C.b64d(identityPub), this.deps.machineId, webEphPub, C.b64d(sigB64))) {
      this.deps.sendTo(connId, { type: 'e2e_denied', payload: { webEphPub: ephPubB64, reason: 'bad_sig' } })
      return true
    }
    this.helloWaits.delete(connId)
    const role = this.store.pairedRole(identityPub)
    const unknownHello = this.deps.onUnknownHello
    if (role || !unknownHello) {
      this.answerHello(connId, identityPub, ephPubB64, webEphPub, role)
      return true
    }
    void this.answerUnknownHello(connId, identityPub, ephPubB64, webEphPub, unknownHello)
    return true
  }

  /** A browser that signed in before this machine did is in the account's device key log, and the first
   *  hello it sent here was denied as unpaired: the log is read only on its own schedule, so the browser
   *  showed "Link required" until it was. Its hello now waits for that read. */
  private async answerUnknownHello(connId: string, identityPub: string, ephPubB64: string, webEphPub: Uint8Array, unknownHello: (identityPub: string) => Promise<void>): Promise<void> {
    const seq = ++this.helloSeq
    this.helloWaits.set(connId, seq)
    let timer: ReturnType<typeof setTimeout> | undefined
    await Promise.race([
      Promise.resolve().then(() => unknownHello(identityPub)).catch(() => { /* answered as the key stands */ }),
      new Promise<void>((resolve) => { timer = setTimeout(resolve, UNKNOWN_HELLO_WAIT_MS) }),
    ])
    clearTimeout(timer)
    if (this.helloWaits.get(connId) !== seq) return
    this.helloWaits.delete(connId)
    this.answerHello(connId, identityPub, ephPubB64, webEphPub, this.store.pairedRole(identityPub))
  }

  /** A verified hello, answered under the role its key is paired with: a session and its welcome, or
   *  `unpaired` with none. */
  private answerHello(connId: string, identityPub: string, ephPubB64: string, webEphPub: Uint8Array, role: C.PairRole | null): void {
    if (!role) {
      this.deps.sendTo(connId, { type: 'e2e_denied', payload: { webEphPub: ephPubB64, reason: 'unpaired' } })
      return
    }
    const eph = C.newEphemeral()
    // webEphPub is attacker-controlled: a wrong-length or low-order / invalid curve point makes
    // x25519.getSharedSecret throw. Refuse such a hello instead of letting the throw crash the daemon.
    let keys: { c2s: Uint8Array; s2c: Uint8Array }
    try {
      keys = C.sessionKeys(eph.priv, webEphPub, this.deps.machineId, webEphPub, eph.pub)
    } catch {
      this.deps.sendTo(connId, { type: 'e2e_denied', payload: { webEphPub: ephPubB64, reason: 'bad_key' } })
      return
    }
    this.evictIfFull()
    this.dropSession(connId)
    this.sessions.set(connId, {
      webIdentityPub: identityPub,
      role,
      c2s: keys.c2s,
      s2c: keys.s2c,
      s2cCounter: 1,
      c2sRecv: new ReplayWindow(),
      terminalC2s: deriveTerminalBinaryKey(keys.c2s),
      terminalS2c: deriveTerminalBinaryKey(keys.s2c),
      terminalS2cCounter: 0,
      terminalC2sRecv: new ReplayWindow(),
    })
    this.deps.onSessionOpened?.(connId, role, identityPub)
    const id = this.store.getIdentity()
    const enc = C.aeadSeal(keys.s2c, 0, C.utf8('e2e-welcome'), C.utf8(JSON.stringify({
      groupKey: C.b64e(this.groupKeyFor(identityPub)),
      epoch: this.epoch,
      // strictDown: this daemon opens a sealed frame of ANY type and refuses unsealed ones from the relay,
      // so a client may seal the types older daemons took in the clear (STRICT_DOWN_TYPES).
      features: { terminalP2p: 1, viewerForwarding: 1, strictDown: 1 },
    })))
    this.deps.sendTo(connId, {
      type: 'e2e_welcome',
      payload: {
        webEphPub: ephPubB64, // echo (self-addressing)
        ephPub: C.b64e(eph.pub),
        sig: C.b64e(C.welcomeSig(id.priv, this.deps.machineId, webEphPub, eph.pub)),
        enc: C.b64e(enc),
      },
    })
  }

  /** Drop a session when its web connection closes (called from backendSocket on down close is n/a —
   *  connections are relayed; sessions are pruned by LRU + overwrite-on-new-hello). Also cleans up any
   *  in-progress password-PAKE attempt on this connId — the joiner may have disconnected mid-round — and
   *  a hello waiting on the device key log there, which would open a session for a connection gone. */
  dropSession(connId: string): void {
    this.helloWaits.delete(connId)
    if (this.sessions.delete(connId)) this.deps.onSessionDropped?.(connId)
    this.clearPwSlot(connId)
  }

  // ── helpers ──────────────────────────────────────────────────────────────────────────────────

  private resetRoundTimer(slot: PairSlot): void {
    if (slot.active?.roundTimer) clearTimeout(slot.active.roundTimer)
    if (slot.active) slot.active.roundTimer = setTimeout(() => this.failPair('TIMEOUT'), ROUND_TIMEOUT_MS)
  }
  private failPair(error: Extract<PairResult, { ok: false }>['error']): void {
    const slot = this.slot
    if (!slot?.active) return
    this.attempts.push(this.now()) // a failed handshake counts toward the anti-guessing rate limit
    const resolve = slot.active.resolve
    if (error === 'CODE_MISMATCH') {
      this.deps.sendTo(slot.connId, { type: 'e2e_pake', payload: { pairId: slot.pairIdB64, round: 5, error } })
    }
    this.notifyTrustedWebDevicePairCleared(slot, 'failed')
    this.clearSlot()
    resolve({ ok: false, error })
  }
  private clearSlot(): void {
    if (this.slot?.active?.roundTimer) clearTimeout(this.slot.active.roundTimer)
    if (this.slot) clearTimeout(this.slot.ttlTimer)
    this.slot = null
  }
  private evictIfFull(): void {
    if (this.sessions.size < MAX_SESSIONS) return
    const oldest = this.sessions.keys().next().value
    if (oldest) this.dropSession(oldest)
  }
}

// Portable 32-byte random + 8-hex epoch (avoid importing extra symbols; reuse core's rng surface).
function crypto32(): Uint8Array {
  const a = C.newPairId(), b = C.newPairId()
  const out = new Uint8Array(32)
  out.set(a, 0); out.set(b, 16)
  return out
}
function hex8(): string {
  const b = C.newPairId().slice(0, 4)
  let s = ''
  for (let i = 0; i < 4; i++) s += b[i].toString(16).padStart(2, '0')
  return s
}

/** A joiner's name for itself, fit to show in a list: text only, one line, 60 characters at most. */
function pairedLabel(raw: unknown): string | null {
  if (typeof raw !== 'string') return null
  const label = raw.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 60)
  return label || null
}