rename the pairing surface to say what it is: code-pairing modules, PairDevice view, PairingBirds, PAIR_WITH_CODE/CODE_PAIR_* messages (v4.0.31)

@@ -0,0 +1,135 @@1+// Background wiring for code pairing.2+//3+// Keeps `code-pairing.ts` a PURE, dependency-injected client (so its unit tests4+// run without chrome / vault / WebSocket). This module supplies the production5+// `CodePairingDeps` and the single-flight SAS/confirm round-trip that bridges6+// the blocking `confirm(sas)` callback to the popup via runtime messages:7+//8+//   PAIR_WITH_CODE    → startCodePairing()            (popup → bg, messages.ts)9+//   CODE_PAIR_SAS     ← push when onSasReady fires    (bg → popup)10+//   CODE_PAIR_CONFIRM → resolveCodePairingConfirm()   (popup → bg, messages.ts)11+//   CODE_PAIR_RESULT  ← push on complete/error        (bg → popup)12+13+import {14+  pairWithCode,15+  type CodePairingDeps,16+  type CodePairingCallbacks,17+} from "./code-pairing";18+import { openPairingSocket } from "../shared/pairing-dial";19+import { upsertPairedDevice, setLastKnownIp } from "./paired-devices";20+import { buildLocalIdentity } from "./chirp-identity";21+import { computeVaultId } from "../shared/sync-identity";22+import { isUnlocked, getRootKeyHex } from "./vault";23+import { probeSubnetForPort, wsPortOpen } from "./desktop-pairing-probe";24+import { discoverPeachSync } from "./desktop-pairing-mdns";25+import { getLocalSubnet } from "../shared/local-network";26+import type { LocalIdentity } from "../shared/chirp-handshake";27+28+function hexToBytesLocal(hex: string): Uint8Array {29+  const out = new Uint8Array(hex.length / 2);30+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);31+  return out;32+}33+34+/** Best-effort push to the popup. The popup may be closed — pushes are advisory. */35+function push(type: string, payload: unknown): void {36+  try {37+    const maybe = chrome.runtime.sendMessage({ type, payload }) as unknown;38+    if (maybe && typeof (maybe as Promise<unknown>).catch === "function") {39+      (maybe as Promise<unknown>).catch(() => undefined);40+    }41+  } catch {42+    // Popup closed / no receiver — fine.43+  }44+}45+46+/** Production dependency set — real probe, WebSocket, identity, and storage. */47+export function productionCodePairingDeps(): CodePairingDeps {48+  return {49+    async findHost(port) {50+      // Localhost first: peach-sync runs on the same machine as the extension.51+      // This works in every browser without mDNS or WebRTC, and is the fastest52+      // path. The daemon binds 0.0.0.0 so 127.0.0.1 is always reachable.53+      if (await wsPortOpen("127.0.0.1", port, 800)) return "127.0.0.1";54+      // mDNS next — instant when chrome.mdns is available (Chrome/Chromium).55+      const discovered = await discoverPeachSync();56+      if (discovered && (await wsPortOpen(discovered.ip, port, 800))) return discovered.ip;57+      // Fallback: /24 subnet probe (Firefox, Chrome without mDNS, or a stale hit).58+      const subnet = await getLocalSubnet();59+      if (!subnet) return null;60+      return probeSubnetForPort(subnet, port);61+    },62+    openSocket: (ip, port) => openPairingSocket(ip, port),63+    async getLocalIdentity(): Promise<LocalIdentity> {64+      if (!isUnlocked()) throw new Error("vault_locked");65+      const masterKeyHex = getRootKeyHex();66+      if (!masterKeyHex) throw new Error("vault_locked");67+      // SEV-2-B: derive from the stable ROOT key so pairing survives a68+      // master-password change. Zero the copy when done.69+      const masterKey = hexToBytesLocal(masterKeyHex);70+      try {71+        const base = await buildLocalIdentity(masterKey);72+        const vaultId = await computeVaultId(masterKey);73+        return { ...base, vaultId };74+      } finally {75+        masterKey.fill(0);76+      }77+    },78+    persistDevice: (d) => upsertPairedDevice(d),79+    cacheLastKnownIp: (pubkeyHex, ip) => setLastKnownIp(pubkeyHex, ip),80+  };81+}82+83+// ── Single in-flight pairing per worker ──────────────────────────────────────84+// One pairing at a time. The blocking confirm() resolver is parked here while85+// the popup shows the SAS; CODE_PAIR_CONFIRM resolves it.86+let pendingConfirm: ((confirmed: boolean) => void) | null = null;87+let inFlight = false;88+89+function clearPairingState(): void {90+  pendingConfirm = null;91+  inFlight = false;92+}93+94+export function isCodePairingInFlight(): boolean {95+  return inFlight;96+}97+98+/**99+ * Kick off a code pairing. Returns immediately; the SAS and the terminal100+ * result are delivered to the popup as CODE_PAIR_SAS / CODE_PAIR_RESULT101+ * pushes. `deps` is injectable for tests.102+ */103+export function startCodePairing(104+  code: string,105+  deps: CodePairingDeps = productionCodePairingDeps(),106+): void {107+  inFlight = true;108+  const cb: CodePairingCallbacks = {109+    onSasReady: (sas) => push("CODE_PAIR_SAS", { sas }),110+    onComplete: (device) => {111+      push("CODE_PAIR_RESULT", { status: "complete", device });112+      clearPairingState();113+    },114+    onError: (error) => {115+      push("CODE_PAIR_RESULT", { status: "error", error });116+      clearPairingState();117+    },118+  };119+  // The confirm callback blocks on the popup's CODE_PAIR_CONFIRM reply.120+  const confirm = (_sas: string): Promise<boolean> =>121+    new Promise<boolean>((resolve) => { pendingConfirm = resolve; });122+123+  void pairWithCode(code, cb, deps, confirm).finally(() => {124+    // onComplete/onError already cleared state; this is the backstop for an125+    // unexpected throw that skipped the callbacks.126+    if (inFlight) clearPairingState();127+  });128+}129+130+/** Resolve the parked confirm() with the user's decision from the popup. */131+export function resolveCodePairingConfirm(confirmed: boolean): void {132+  const resolve = pendingConfirm;133+  pendingConfirm = null;134+  if (resolve) resolve(confirmed);135+}

@@ -0,0 +1,384 @@1+// Code pairing — the PAIR_IDENTITY half, over both code forms.2+//3+// Driven entirely through the dependency-injection seam (CodePairingDeps and a4+// fake PairingSocket), so no real WebSocket or Noise crypto runs — except the5+// SAS KAT, which calls the REAL `derivePairingSAS` to pin cross-implementation6+// agreement with the peer.7+8+import { beforeEach, describe, expect, it, vi } from "vitest";9+10+import {11+  pairWithCode,12+  type CodePairingDeps,13+  type CodePairingCallbacks,14+} from "./code-pairing";15+import { PAIRING_PORT, type PairingSocket } from "../shared/pairing-dial";16+17+// REAL SAS implementation — reused, not re-derived (ground truth §5).18+import { derivePairingSAS } from "../shared/chirp-handshake";19+import { encodePairingCode } from "../shared/pairing-code";20+import type { LocalIdentity } from "../shared/chirp-handshake";21+import type { PairedDevice } from "../shared/sync-types";22+23+// ── helpers ────────────────────────────────────────────────────────────────24+25+const enc = (o: unknown) => new TextEncoder().encode(JSON.stringify(o));26+const dec = (b: Uint8Array) => JSON.parse(new TextDecoder().decode(b));27+28+const HELPER_EPHEMERAL_HEX = "a".repeat(64);29+const HELPER_LONGTERM_HEX = "b".repeat(64);30+31+const OUR_IDENTITY: LocalIdentity = {32+  deviceId: "ext-local-001",33+  deviceName: "Firefox on MacBook",34+  deviceType: "extension",35+  longTermPublicKeyHex: "c".repeat(64),36+  signingPublicKeyHex: "d".repeat(64),37+  vaultId: "e".repeat(64),38+};39+40+/**41+ * Scripted fake socket. Captures everything sent, and replays a queued list42+ * of inbound frames. A frame of `null` means "the socket closes here with no43+ * data" — the peach-sync wrong-code behaviour (no error frame).44+ */45+function makeFakeSocket(inbound: Array<Uint8Array | null>) {46+  const sent: Uint8Array[] = [];47+  let closed = false;48+  let lastWasClose = false;49+  const queue = [...inbound];50+  const sock: PairingSocket = {51+    send(bytes) { sent.push(bytes); },52+    async receive() {53+      const next = queue.shift();54+      if (next === undefined || next === null) {55+        closed = true;56+        lastWasClose = true;57+        throw new Error("socket closed");58+      }59+      lastWasClose = false;60+      return next;61+    },62+    close() { closed = true; },63+    closedBeforeFrame() { return lastWasClose; },64+  };65+  return { sock, sent, isClosed: () => closed };66+}67+68+/**69+ * A fake Noise session that no-ops encrypt/decrypt (identity transform) so we70+ * can drive the PAIR_IDENTITY exchange without real crypto. We stub71+ * `noiseNKInitiator` via vi.mock below; this is the shape it returns.72+ */73+const FAKE_HANDSHAKE_HASH = Uint8Array.from([74+  0x0f, 0xba, 0xb8, 0xcd, ...new Array(28).fill(0),75+]);76+77+// Mock the NK initiator: skip the two handshake messages, hand back a session78+// whose encrypt/decrypt are identity transforms and whose handshakeHash is the79+// peach-sync KAT prefix (so the SAS test below is end-to-end through the flow).80+vi.mock("../shared/noise-js", async (orig) => {81+  const actual = await orig<typeof import("../shared/noise-js")>();82+  return {83+    ...actual,84+    noiseNKInitiator: vi.fn(async (_responderStatic, _send, _receive) => ({85+      encrypt: (pt: Uint8Array) => pt,86+      decrypt: (ct: Uint8Array) => ct,87+      handshakeHash: FAKE_HANDSHAKE_HASH,88+    })),89+  };90+});91+92+function makeDeps(overrides: Partial<CodePairingDeps> = {}): {93+  deps: CodePairingDeps;94+  persisted: PairedDevice[];95+  sockets: ReturnType<typeof makeFakeSocket>[];96+} {97+  const persisted: PairedDevice[] = [];98+  const sockets: ReturnType<typeof makeFakeSocket>[] = [];99+  const deps: CodePairingDeps = {100+    findHost: vi.fn(async () => "192.168.1.50"),101+    openSocket: vi.fn(async () => {102+      // default: ACK then a PAIR_IDENTITY response103+      const s = makeFakeSocket([104+        enc({ type: "PEACH_HELLO_ACK", ephemeralPublicKeyHex: HELPER_EPHEMERAL_HEX }),105+        enc({106+          type: "PAIR_IDENTITY",107+          device_id: "desktop-001",108+          device_name: "June's iMac",109+          device_type: "desktop",110+          long_term_public_key_hex: HELPER_LONGTERM_HEX,111+          ws_port: 8765,112+        }),113+      ]);114+      sockets.push(s);115+      return s.sock;116+    }),117+    getLocalIdentity: vi.fn(async () => OUR_IDENTITY),118+    persistDevice: vi.fn(async (d: PairedDevice) => { persisted.push(d); }),119+    ...overrides,120+  };121+  return { deps, persisted, sockets };122+}123+124+function makeCallbacks(): {125+  cb: CodePairingCallbacks;126+  sas: { value?: string };127+  errors: string[];128+  completed: PairedDevice[];129+} {130+  const sas: { value?: string } = {};131+  const errors: string[] = [];132+  const completed: PairedDevice[] = [];133+  const cb: CodePairingCallbacks = {134+    onSasReady: (s) => { sas.value = s; },135+    onError: (e) => { errors.push(e); },136+    onComplete: (d) => { completed.push(d); },137+  };138+  return { cb, sas, errors, completed };139+}140+141+beforeEach(() => {142+  vi.clearAllMocks();143+});144+145+// ── specs ────────────────────────────────────────────────────────────────146+147+describe("pairWithCode", () => {148+  it("sends PEACH_HELLO with a 6-digit zero-padded code to port 49142", async () => {149+    const { deps, sockets } = makeDeps();150+    const { cb } = makeCallbacks();151+152+    await pairWithCode("123", cb, deps, async () => true);153+154+    expect(deps.openSocket).toHaveBeenCalledWith("192.168.1.50", PAIRING_PORT);155+    const firstFrame = dec(sockets[0].sent[0]);156+    expect(firstFrame.type).toBe("PEACH_HELLO");157+    // "123" must be normalised to exactly 6 ASCII digits, zero-padded.158+    expect(firstFrame.code).toBe("000123");159+    expect(firstFrame.code).toMatch(/^\d{6}$/);160+  });161+162+  it("treats a socket close without PEACH_HELLO_ACK as invalid_code", async () => {163+    // peach-sync sends NO error frame on a wrong/expired code — it SILENTLY164+    // CLOSES the socket and rotates the code (pairing.zig:117,119-125). So the165+    // absence of a PEACH_HELLO_ACK *is* the wrong-code signal. (This replaces166+    // the original brief's bogus PEACH_HELLO_ERROR test — no such frame exists.)167+    const closeImmediately = makeFakeSocket([null]); // close, no data168+    const { deps } = makeDeps({169+      openSocket: vi.fn(async () => closeImmediately.sock),170+    });171+    const { cb, errors, completed } = makeCallbacks();172+173+    await pairWithCode("654321", cb, deps, async () => true);174+175+    expect(errors).toEqual(["invalid_code"]);176+    expect(completed).toHaveLength(0);177+    expect(deps.persistDevice).not.toHaveBeenCalled();178+  });179+180+  it("derives the SAS via the real derivePairingSAS — KAT 0fbab8cd… → 895245", () => {181+    // Cross-impl KAT pinned in peach-sync (pairing.zig:275-279): the handshake182+    // hash beginning 0f ba b8 cd yields SAS "895245". 0x0fbab8cd = 263895245;183+    // 263895245 mod 1_000_000 = 895245.184+    const hash = Uint8Array.from([185+      0x0f, 0xba, 0xb8, 0xcd, ...new Array(28).fill(0),186+    ]);187+    expect(derivePairingSAS(hash)).toBe("895245");188+  });189+190+  it("surfaces that same SAS through the pairing flow", async () => {191+    // FAKE_HANDSHAKE_HASH starts 0fbab8cd, so onSasReady must report 895245.192+    const { deps } = makeDeps();193+    const { cb, sas } = makeCallbacks();194+195+    await pairWithCode("000123", cb, deps, async () => true);196+197+    expect(sas.value).toBe("895245");198+  });199+200+  it("persists the device with deviceType 'desktop' on SAS confirm", async () => {201+    const { deps, persisted } = makeDeps();202+    const { cb, completed, errors } = makeCallbacks();203+204+    await pairWithCode("000123", cb, deps, async () => true);205+206+    expect(errors).toHaveLength(0);207+    expect(persisted).toHaveLength(1);208+    expect(persisted[0].deviceType).toBe("desktop");209+    expect(persisted[0].deviceId).toBe("desktop-001");210+    expect(persisted[0].longTermPublicKeyHex).toBe(HELPER_LONGTERM_HEX);211+    expect(persisted[0].trustSource).toBe("direct");212+    expect(persisted[0].wsPort).toBe(8765);213+    expect(completed).toHaveLength(1);214+  });215+216+  it("aborts with sas_mismatch and persists nothing when the user rejects", async () => {217+    const { deps, persisted } = makeDeps();218+    const { cb, errors } = makeCallbacks();219+220+    await pairWithCode("000123", cb, deps, async () => false);221+222+    expect(errors).toEqual(["sas_mismatch"]);223+    expect(persisted).toHaveLength(0);224+    expect(deps.persistDevice).not.toHaveBeenCalled();225+  });226+227+  it("includes vault_id in the outbound PAIR_IDENTITY (Change 1)", async () => {228+    const { deps, sockets } = makeDeps();229+    const { cb } = makeCallbacks();230+231+    await pairWithCode("000123", cb, deps, async () => true);232+233+    // sent[0] = PEACH_HELLO (plaintext); sent[1] = our PAIR_IDENTITY234+    // (encrypt is identity in the mock, so it decodes directly).235+    const ourPairIdentity = dec(sockets[0].sent[1]);236+    expect(ourPairIdentity.type).toBe("PAIR_IDENTITY");237+    expect(ourPairIdentity.vault_id).toBe(OUR_IDENTITY.vaultId);238+  });239+240+  it("reports no_host_found when the probe returns null", async () => {241+    const { deps } = makeDeps({ findHost: vi.fn(async () => null) });242+    const { cb, errors } = makeCallbacks();243+244+    await pairWithCode("000123", cb, deps, async () => true);245+246+    expect(errors).toEqual(["no_host_found"]);247+    expect(deps.openSocket).not.toHaveBeenCalled();248+  });249+250+  it("reports vault_locked when local identity is unavailable", async () => {251+    const { deps } = makeDeps({252+      getLocalIdentity: vi.fn(async () => { throw new Error("vault_locked"); }),253+    });254+    const { cb, errors } = makeCallbacks();255+256+    await pairWithCode("000123", cb, deps, async () => true);257+258+    expect(errors).toEqual(["vault_locked"]);259+    expect(deps.findHost).not.toHaveBeenCalled();260+  });261+});262+263+// ── pairing-code path (the phone is the listener) ──────────────────────────264+265+const PHONE_TOKEN = Uint8Array.of(0xde, 0xad, 0xbe, 0xef);266+const PHONE_CODE = encodePairingCode("192.168.4.77", 51555, PHONE_TOKEN);267+const PHONE_LONGTERM_HEX = "f".repeat(64);268+269+/** Deps whose socket replays an Android peer's ACK + PAIR_IDENTITY. */270+function makePhoneDeps(deviceType: string | undefined = "android") {271+  const identity: Record<string, unknown> = {272+    type: "PAIR_IDENTITY",273+    device_id: "android-001",274+    device_name: "Pixel 8",275+    long_term_public_key_hex: PHONE_LONGTERM_HEX,276+    ws_port: 8765,277+  };278+  identity.device_type = deviceType;279+  return makeDeps({280+    openSocket: vi.fn(async () => makeFakeSocket([281+      enc({ type: "PEACH_HELLO_ACK", ephemeralPublicKeyHex: HELPER_EPHEMERAL_HEX }),282+      enc(identity),283+    ]).sock),284+  });285+}286+287+describe("pairWithCode — pairing code", () => {288+  it("dials the address in the code instead of probing for a host", async () => {289+    const { deps } = makePhoneDeps();290+    const { cb, errors } = makeCallbacks();291+292+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);293+294+    expect(errors).toHaveLength(0);295+    expect(deps.findHost).not.toHaveBeenCalled();296+    expect(deps.openSocket).toHaveBeenCalledWith("192.168.4.77", 51555);297+  });298+299+  it("presents the token as hex in the plaintext hello, not a 6-digit code", async () => {300+    const sockets: ReturnType<typeof makeFakeSocket>[] = [];301+    const { deps } = makeDeps({302+      openSocket: vi.fn(async () => {303+        const s = makeFakeSocket([304+          enc({ type: "PEACH_HELLO_ACK", ephemeralPublicKeyHex: HELPER_EPHEMERAL_HEX }),305+          enc({306+            type: "PAIR_IDENTITY",307+            device_id: "android-001",308+            device_name: "Pixel 8",309+            device_type: "android",310+            long_term_public_key_hex: PHONE_LONGTERM_HEX,311+            ws_port: 8765,312+          }),313+        ]);314+        sockets.push(s);315+        return s.sock;316+      }),317+    });318+    const { cb } = makeCallbacks();319+320+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);321+322+    const hello = dec(sockets[0].sent[0]);323+    expect(hello.type).toBe("PEACH_HELLO");324+    expect(hello.token).toBe("deadbeef");325+    expect(hello.code).toBeUndefined();326+  });327+328+  it("persists the phone with the device type it announced", async () => {329+    const { deps, persisted } = makePhoneDeps();330+    const { cb, completed } = makeCallbacks();331+332+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);333+334+    expect(persisted).toHaveLength(1);335+    expect(persisted[0].deviceType).toBe("android");336+    expect(persisted[0].deviceId).toBe("android-001");337+    expect(persisted[0].longTermPublicKeyHex).toBe(PHONE_LONGTERM_HEX);338+    expect(persisted[0].trustSource).toBe("direct");339+    expect(persisted[0].wsPort).toBe(8765);340+    expect(completed).toHaveLength(1);341+  });342+343+  it("falls back to 'android', never 'desktop', when the peer omits its type", async () => {344+    const { deps, persisted } = makePhoneDeps("");345+    const { cb } = makeCallbacks();346+347+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);348+349+    expect(persisted[0].deviceType).toBe("android");350+  });351+352+  it("caches the coded IP for the next sync round", async () => {353+    const cacheLastKnownIp = vi.fn(async () => undefined);354+    const { deps } = makePhoneDeps();355+    deps.cacheLastKnownIp = cacheLastKnownIp;356+    const { cb } = makeCallbacks();357+358+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);359+360+    expect(cacheLastKnownIp).toHaveBeenCalledWith(PHONE_LONGTERM_HEX, "192.168.4.77");361+  });362+363+  it("reports no_host_found when the coded endpoint refuses the connection", async () => {364+    const { deps } = makeDeps({365+      openSocket: vi.fn(async () => { throw new Error("ECONNREFUSED"); }),366+    });367+    const { cb, errors } = makeCallbacks();368+369+    await pairWithCode(PHONE_CODE, cb, deps, async () => true);370+371+    expect(errors).toEqual(["no_host_found"]);372+    expect(deps.persistDevice).not.toHaveBeenCalled();373+  });374+375+  it("still aborts on SAS rejection — the token is not the security boundary", async () => {376+    const { deps, persisted } = makePhoneDeps();377+    const { cb, errors } = makeCallbacks();378+379+    await pairWithCode(PHONE_CODE, cb, deps, async () => false);380+381+    expect(errors).toEqual(["sas_mismatch"]);382+    expect(persisted).toHaveLength(0);383+  });384+});

@@ -0,0 +1,157 @@1+// Device pairing over a code — the PAIR_IDENTITY half.2+//3+// The dialling half (decode the code, connect, plaintext hello, Noise NK) lives4+// in `shared/pairing-dial.ts` and is shared with vault adoption, which speaks5+// ADOPT_* frames over the same channel instead. This module is only what6+// happens once that channel is open:7+//8+//   1. exchange PAIR_IDENTITY (send ours incl. vault_id, then read theirs)9+//   2. derive the SAS, surface it for user confirmation10+//   3. on confirm -> persist the PairedDevice; on reject -> abort without11+//      persisting12+//13+// Two code forms reach here. A pairing code (`A74H-48J3-KI32-OEP4`) is the14+// primary path: the phone listens and the code carries its address. A legacy15+// 6-digit helper code has no address, so the host is probed for.16+17+import { dialPairingChannel, type PairingDialDeps } from "../shared/pairing-dial";18+import type { LocalIdentity } from "../shared/chirp-handshake";19+import { parsePairingCode } from "../shared/pairing-code";20+import type { DeviceType, PairedDevice } from "../shared/sync-types";21+22+/** Default sync port a peer announces; used when ws_port is absent. */23+const DEFAULT_SYNC_PORT = 8765;24+25+export type CodePairingError =26+  | "invalid_code"      // socket closed before PEACH_HELLO_ACK (wrong/expired)27+  | "no_host_found"     // nothing answered at the endpoint28+  | "handshake_failed"  // Noise NK / PAIR_IDENTITY decode failed29+  | "sas_mismatch"      // user rejected the SAS30+  | "vault_locked";     // no master key available31+32+export interface CodePairingDeps extends PairingDialDeps {33+  /** Public identity for our outbound PAIR_IDENTITY (incl. vaultId). */34+  getLocalIdentity(): Promise<LocalIdentity>;35+  /** Persist on user confirm. */36+  persistDevice(device: PairedDevice): Promise<void>;37+  /** Optional fast-path cache for the next sync round. */38+  cacheLastKnownIp?(pubkeyHex: string, ip: string): Promise<void>;39+}40+41+export interface CodePairingCallbacks {42+  /** Show the 6-digit SAS; the popup must compare it against the peer's. */43+  onSasReady(sas: string): void;44+  /** Pairing succeeded and the device was persisted. */45+  onComplete(device: PairedDevice): void;46+  /** Pairing failed at some stage. */47+  onError(error: CodePairingError): void;48+}49+50+interface PairingFrame {51+  type: "PAIR_IDENTITY";52+  device_id: string;53+  device_name: string;54+  device_type: DeviceType;55+  long_term_public_key_hex: string;56+  signing_public_key_hex?: string;57+  ws_port?: number;58+  vault_id?: string; // Change 1 — additive, optional59+}60+61+function encodeJson(obj: unknown): Uint8Array {62+  return new TextEncoder().encode(JSON.stringify(obj));63+}64+65+function decodePairIdentity(bytes: Uint8Array): PairingFrame {66+  const p = JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;67+  if (p?.type !== "PAIR_IDENTITY") throw new Error("expected PAIR_IDENTITY");68+  if (typeof p.device_id !== "string" || !p.device_id) throw new Error("device_id missing");69+  if (typeof p.device_name !== "string") throw new Error("device_name missing");70+  if (typeof p.device_type !== "string") throw new Error("device_type missing");71+  if (typeof p.long_term_public_key_hex !== "string" ||72+      !/^[0-9a-f]{64}$/.test(p.long_term_public_key_hex)) {73+    throw new Error("long_term_public_key_hex is not 32-byte hex");74+  }75+  return p as unknown as PairingFrame;76+}77+78+/**79+ * Drive a complete code pairing.80+ *81+ * `confirm` is a function the caller resolves AFTER the user has compared the82+ * SAS shown here against the SAS the peer displays. Resolving false (or83+ * rejecting) aborts before any device is persisted — this is the out-of-band84+ * MITM defence (see the SECURITY note in chirp-handshake.ts), and it, not the85+ * pairing token, is what actually authenticates the peer.86+ */87+export async function pairWithCode(88+  code: string,89+  cb: CodePairingCallbacks,90+  deps: CodePairingDeps,91+  confirm: (sas: string) => Promise<boolean>,92+): Promise<void> {93+  let identity: LocalIdentity;94+  try {95+    identity = await deps.getLocalIdentity();96+  } catch {97+    cb.onError("vault_locked");98+    return;99+  }100+101+  const dial = await dialPairingChannel(code, deps);102+  if (!dial.ok) {103+    cb.onError(dial.error);104+    return;105+  }106+  const { channel, sas, host, socket } = dial.dialled;107+108+  try {109+    // Initiator (browser) sends its identity FIRST, then reads the peer's.110+    const ourFrame: PairingFrame = {111+      type: "PAIR_IDENTITY",112+      device_id: identity.deviceId,113+      device_name: identity.deviceName,114+      device_type: identity.deviceType,115+      long_term_public_key_hex: identity.longTermPublicKeyHex,116+      signing_public_key_hex: identity.signingPublicKeyHex,117+      ws_port: identity.wsPort,118+      vault_id: identity.vaultId, // Change 1119+    };120+    await channel.send(encodeJson(ourFrame));121+122+    const theirFrame = decodePairIdentity(await channel.receive());123+124+    cb.onSasReady(sas);125+    const confirmed = await confirm(sas);126+    if (!confirmed) {127+      cb.onError("sas_mismatch");128+      return;129+    }130+131+    // ws_port comes from the peer frame, defaulting to 8765 (both peers132+    // announce it, but guard it). The device-type fallback follows the code133+    // form so a phone never lands in the registry labelled "desktop".134+    const device: PairedDevice = {135+      deviceId: theirFrame.device_id,136+      deviceName: theirFrame.device_name,137+      deviceType:138+        (theirFrame.device_type as DeviceType) ||139+        (parsePairingCode(code) ? "android" : "desktop"),140+      longTermPublicKeyHex: theirFrame.long_term_public_key_hex,141+      signingPublicKeyHex: theirFrame.signing_public_key_hex,142+      trustSource: "direct",143+      wsPort: typeof theirFrame.ws_port === "number" ? theirFrame.ws_port : DEFAULT_SYNC_PORT,144+      pairedAt: Date.now(),145+    };146+    await deps.persistDevice(device);147+    if (deps.cacheLastKnownIp && device.longTermPublicKeyHex) {148+      await deps.cacheLastKnownIp(device.longTermPublicKeyHex, host).catch(() => undefined);149+    }150+    cb.onComplete(device);151+  } catch (err) {152+    if (typeof console !== "undefined") console.error("[desktop-pairing] handshake failed:", err);153+    cb.onError("handshake_failed");154+  } finally {155+    socket.close();156+  }157+}