pairing-handshake.ts

1// Pairing handshake — Noise NK, the SAS, and the PAIR_IDENTITY frame.2//3// STATUS: the audio-pairing flow this module was written for is gone. What production still4// uses from here is `derivePairingSAS` and the `LocalIdentity` /5// `PairingTransport` types; the live dial-and-handshake path is6// `shared/pairing-dial.ts`, and the live PAIR_IDENTITY exchange is7// `background/code-pairing.ts`.8//9// The `runPairing*` helpers below are exercised only by this module's own10// specs. Do NOT reach for the RESPONDER ones in new code: they assume this11// device can accept an inbound connection, which a browser extension cannot12// do. The browser is always the dialler, always the NK initiator.13//14// The shape of the exchange, which the live path still follows:15//16//   1. Both sides instantiate Noise NK over a caller-supplied transport. The17//      responder's "static" is an ephemeral it published out of band — today18//      that is the `ephemeralPublicKeyHex` it returns in PEACH_HELLO_ACK,19//      which is why the SAS below carries the real authentication weight.20//21//   2. Over the resulting Noise transport, each side sends ONE JSON frame with22//      its `device_id`, `device_name`, `device_type`,23//      `long_term_public_key_hex`, and device-manifest signing key. Both sides24//      persist the counterpart in the paired-device registry.25//26//   3. The Noise NK session and the ephemerals are discarded — future27//      WebSocket sessions use Noise XX with the long-term static keys28//      exchanged in step 2.2930import { noiseNKInitiator, noiseNKResponder } from "./noise-js";31import type { DeviceType, PairedDevice } from "./sync-types";3233export interface PairingTransport {34  send(msg: Uint8Array): Promise<void>;35  receive(): Promise<Uint8Array>;36}3738/** Result of a pairing handshake: the peer's identity plus the SAS the user39 *  must confirm matches the peer device before the pair is persisted. */40export interface PairingHandshakeResult {41  device: PairedDevice;42  sas: string;43  /**44   * The peer's signed Pro license blob, if it advertised one. The caller45   * activates it (signature-verified) AFTER the SAS is confirmed, so one Pro46   * device can grant Pro to the other when pairing. Never persisted as-is.47   */48  peerLicense?: string;49}5051export interface LocalIdentity {52  deviceId: string;53  deviceName: string;54  deviceType: DeviceType;55  longTermPublicKeyHex: string;56  signingPublicKeyHex?: string;57  /** Server-only field — Android/iOS/desktop sync hosts announce their port. */58  wsPort?: number;59  /**60   * Stable per-vault id (`computeVaultId`, sync-identity.ts). Sent in the61   * outbound PAIR_IDENTITY so a desktop helper can record which vault it62   * paired to. Optional: the caller omits it when the vault is locked (no63   * master key). Privacy: this is the LAN-linkable id — see the PRIVACY NOTE64   * at sync-identity.ts:62 (PCH-02-006).65   */66  vaultId?: string;67  /**68   * This device's signed Pro license blob (`PPK-…`), included only when this69   * device is Pro. The peer activates it (signature-verified) after the SAS is70   * confirmed, so pairing carries Pro to a free device. Either direction.71   */72  license?: string;73}7475interface PairingFrame {76  type: "PAIR_IDENTITY";77  device_id: string;78  device_name: string;79  device_type: DeviceType;80  long_term_public_key_hex: string;81  signing_public_key_hex?: string;82  ws_port?: number;83  // Optional: present only when the sender knows its vault id. peach-sync84  // treats this as optional (pairing.zig:54); mobile peers may omit it.85  vault_id?: string;86  // Optional signed Pro license blob — additive; peers that don't understand87  // it ignore it. Activated by the receiver only after SAS confirmation.88  license?: string;89}9091export interface PostNoiseFrame {92  sas: string;93  frame: unknown;94  channel: PairingTransport;95}9697export interface PostNoiseChannel {98  sas: string;99  channel: PairingTransport;100}101102function encodeFrame(frame: PairingFrame): Uint8Array {103  return new TextEncoder().encode(JSON.stringify(frame));104}105106function decodeParsedFrame(parsed: unknown): PairingFrame {107  const value = parsed as Record<string, unknown> | null;108  if (value?.type !== "PAIR_IDENTITY") throw new Error("expected PAIR_IDENTITY frame");109  if (typeof value.device_id !== "string" || !value.device_id) throw new Error("device_id missing");110  if (typeof value.device_name !== "string") throw new Error("device_name missing");111  if (typeof value.device_type !== "string") throw new Error("device_type missing");112  if (typeof value.long_term_public_key_hex !== "string") throw new Error("long_term_public_key_hex missing");113  // Long-term pubkey is a hex-encoded 32-byte X25519 key.114  if (!/^[0-9a-f]{64}$/.test(value.long_term_public_key_hex)) {115    throw new Error("long_term_public_key_hex is not 32-byte hex");116  }117  if (118    value.signing_public_key_hex !== undefined &&119    (typeof value.signing_public_key_hex !== "string" || !/^[0-9a-f]{64}$/.test(value.signing_public_key_hex))120  ) {121    throw new Error("signing_public_key_hex is not 32-byte hex");122  }123  return value as unknown as PairingFrame;124}125126/**127 * Run the pairing handshake from the INITIATOR side.128 *129 * `remoteEphemeralPublicKey` is the responder's ephemeral pubkey, learned out130 * of band. The Noise NK transport message 1 encrypts to that key; the131 * responder must hold the matching private key.132 */133export async function runPairingInitiator(134  remoteEphemeralPublicKey: Uint8Array,135  ourIdentity: LocalIdentity,136  transport: PairingTransport,137): Promise<PairingHandshakeResult> {138  const postNoise = await runPairingInitiatorOpenChannel(remoteEphemeralPublicKey, transport);139140  // Send our identity, then receive theirs.141  await postNoise.channel.send(encodeFrame({142    type: "PAIR_IDENTITY",143    device_id: ourIdentity.deviceId,144    device_name: ourIdentity.deviceName,145    device_type: ourIdentity.deviceType,146    long_term_public_key_hex: ourIdentity.longTermPublicKeyHex,147    signing_public_key_hex: ourIdentity.signingPublicKeyHex,148    ws_port: ourIdentity.wsPort,149    vault_id: ourIdentity.vaultId,150    license: ourIdentity.license,151  }));152153  const theirFrame = decodeParsedFrame(JSON.parse(new TextDecoder().decode(await postNoise.channel.receive())));154  // The SAS is derived from the shared Noise handshake hash; the caller MUST155  // have the user confirm it matches the peer's before persisting the device.156  return {157    device: frameToPairedDevice(theirFrame),158    sas: postNoise.sas,159    peerLicense: peerLicenseOf(theirFrame),160  };161}162163export async function runPairingInitiatorOpenChannel(164  remoteEphemeralPublicKey: Uint8Array,165  transport: PairingTransport,166): Promise<PostNoiseChannel> {167  const session = await noiseNKInitiator(168    remoteEphemeralPublicKey,169    transport.send,170    transport.receive,171  );172173  const channel: PairingTransport = {174    async send(msg) {175      await transport.send(session.encrypt(msg));176    },177    async receive() {178      return session.decrypt(await transport.receive());179    },180  };181  return {182    sas: derivePairingSAS(session.handshakeHash),183    channel,184  };185}186187// ───────────────────────────────────────────────────────────────────────────188// SECURITY — TRUST MODEL (PCH-02-003): the pairing handshake does NOT cryptographically189// authenticate the initiator. Noise NK authenticates only the RESPONDER (it190// proves the initiator encrypted to the responder's "static" key — here the191// ephemeral the responder published in the clear out of band). On its own192// it gives the extension (always the responder) zero assurance about *who*193// completed the handshake, and there is no proof-of-possession over the194// long_term_public_key_hex a peer advertises in its PAIR_IDENTITY frame.195//196// COMPENSATING CONTROL (IMPLEMENTED, MANDATORY on the extension side): a197// user-verified Short Authentication String. Both peers derive the SAME 6-digit198// SAS via `derivePairingSAS(session.handshakeHash)` (below) — identical on both199// ends because the Noise handshake hash is shared — and DISPLAY it. The200// extension pairing flow gates persistence on the user confirming the codes201// match: the SAS gate in `background/code-pairing.ts` runs BEFORE any device is202// written to the registry and ABORTS pairing on mismatch/rejection. This is the203// Bluetooth-numeric-comparison / Signal-safety-number model and detects a204// MITM/relay despite the lack of full mutual auth. Residual risk is the standard205// 6-digit SAS bound: a MITM survives with probability 1e-6 per attempt, and the206// guarantee depends on the user actually comparing the codes.207//208// OPEN ITEM (NOT verifiable from this repository): the Android/native client209// MUST surface and enforce the identical SAS gate before it persists the peer.210// If the app skips or auto-confirms the SAS, the channel is only as strong as211// the app's weakest end — confirm the app-side gate against the Android source212// at kepr.uk/peach-android before any release that touches pairing. A MITM who213// intercepts the out-of-band ephemeral and completes the handshake against a non-214// enforcing peer can pair without user awareness.215// A future hardening step (coordinated wire change with the app) could add216// proof-of-possession via `performInitiatorAuth`/`performResponderAuth`217// (noise-js) so each side proves possession of the key it advertises, making218// authentication structural rather than dependent on the user's SAS comparison.219//220// This is documented residual risk in the cross-repo trust model, not a bug in221// this codebase: the extension-side gateOnSAS is enforced here and regression-222// tested (PCH-01-024); the peer-side gate lives in Android and must be re-223// verified there on every pairing-touching Android release.224// ───────────────────────────────────────────────────────────────────────────225226/**227 * Derive a 6-digit Short Authentication String from a Noise handshake hash.228 * Both pairing peers compute the SAME value because the Noise `handshakeHash`229 * is shared after the handshake. Showing it on both devices and having the230 * user confirm they match authenticates the channel out-of-band, detecting a231 * man-in-the-middle the NK handshake alone cannot (see SECURITY note above).232 */233export function derivePairingSAS(handshakeHash: Uint8Array): string {234  // Fold the first 4 bytes into an unsigned int, mod 1e6, zero-padded. Uniform235  // enough for a 6-digit comparison code; the handshake hash is already a PRF236  // output so no further mixing is needed.237  if (handshakeHash.length < 4) return "000000";238  const n =239    ((handshakeHash[0] << 24) >>> 0) +240    (handshakeHash[1] << 16) +241    (handshakeHash[2] << 8) +242    handshakeHash[3];243  return String((n >>> 0) % 1_000_000).padStart(6, "0");244}245246/**247 * Run the pairing handshake from the RESPONDER side.248 *249 * NOT REACHABLE FROM A BROWSER — responding means accepting an inbound250 * connection. Retained for the protocol definition and its specs only.251 */252export async function runPairingResponder(253  ourEphemeralPrivateKey: Uint8Array,254  ourEphemeralPublicKey: Uint8Array,255  ourIdentity: LocalIdentity,256  transport: PairingTransport,257): Promise<PairingHandshakeResult> {258  const postNoise = await runPairingResponderOpenFrame(259    ourEphemeralPrivateKey,260    ourEphemeralPublicKey,261    transport,262  );263  return handlePairIdentityFrame(postNoise.frame, postNoise.channel, ourIdentity, postNoise.sas);264}265266export async function runPairingResponderOpenFrame(267  ourEphemeralPrivateKey: Uint8Array,268  ourEphemeralPublicKey: Uint8Array,269  transport: PairingTransport,270): Promise<PostNoiseFrame> {271  const session = await noiseNKResponder(272    ourEphemeralPrivateKey,273    ourEphemeralPublicKey,274    transport.send,275    transport.receive,276  );277278  const channel: PairingTransport = {279    async send(msg) {280      await transport.send(session.encrypt(msg));281    },282    async receive() {283      return session.decrypt(await transport.receive());284    },285  };286  const theirFrame = JSON.parse(new TextDecoder().decode(await channel.receive()));287  return {288    sas: derivePairingSAS(session.handshakeHash),289    frame: theirFrame,290    channel,291  };292}293294export async function handlePairIdentityFrame(295  frame: unknown,296  channel: PairingTransport,297  ourIdentity: LocalIdentity,298  sas: string,299): Promise<PairingHandshakeResult> {300  const theirFrame = decodeParsedFrame(frame);301  const ourFrame = encodeFrame({302    type: "PAIR_IDENTITY",303    device_id: ourIdentity.deviceId,304    device_name: ourIdentity.deviceName,305    device_type: ourIdentity.deviceType,306    long_term_public_key_hex: ourIdentity.longTermPublicKeyHex,307    signing_public_key_hex: ourIdentity.signingPublicKeyHex,308    ws_port: ourIdentity.wsPort,309    vault_id: ourIdentity.vaultId,310    license: ourIdentity.license,311  });312  await channel.send(ourFrame);313314  // SAS derived from the shared handshake hash — caller must have the user315  // confirm it matches the peer's code before persisting (defeats the316  // initiator-impersonation / MITM attack the NK handshake alone allows).317  return {318    device: frameToPairedDevice(theirFrame),319    sas,320    peerLicense: peerLicenseOf(theirFrame),321  };322}323324/** Pull a plausible license string off a peer frame (signature is verified325 *  later, on activation). Anything non-string is ignored. */326function peerLicenseOf(frame: PairingFrame): string | undefined {327  return typeof frame.license === "string" && frame.license.length > 0 ? frame.license : undefined;328}329330function frameToPairedDevice(frame: PairingFrame): PairedDevice {331  return {332    deviceId: frame.device_id,333    deviceName: frame.device_name,334    deviceType: frame.device_type,335    longTermPublicKeyHex: frame.long_term_public_key_hex,336    signingPublicKeyHex: frame.signing_public_key_hex,337    trustSource: "direct",338    wsPort: typeof frame.ws_port === "number" ? frame.ws_port : undefined,339    pairedAt: Date.now(),340  };341}342343/**344 * Test-helper: an in-memory pair of transports that connect to each other.345 * Use one half for the initiator and the other for the responder.346 */347export function memoryTransportPair(): [PairingTransport, PairingTransport] {348  const a: Uint8Array[] = [];349  const b: Uint8Array[] = [];350  const aReaders: Array<(b: Uint8Array) => void> = [];351  const bReaders: Array<(b: Uint8Array) => void> = [];352353  function makeTransport(354    inbox: Uint8Array[],355    outbox: Uint8Array[],356    inboxReaders: Array<(b: Uint8Array) => void>,357    outboxReaders: Array<(b: Uint8Array) => void>,358  ): PairingTransport {359    return {360      async send(msg: Uint8Array) {361        const r = outboxReaders.shift();362        if (r) r(msg);363        else outbox.push(msg);364      },365      receive() {366        const msg = inbox.shift();367        if (msg) return Promise.resolve(msg);368        return new Promise<Uint8Array>((resolve) => inboxReaders.push(resolve));369      },370    };371  }372  return [makeTransport(a, b, aReaders, bReaders), makeTransport(b, a, bReaders, aReaders)];373}