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
/**
* 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
}