dsh-cherry-bridge 0.1.10 → 0.2.0

package/src/pairing.ts

@@ -2,12 +2,15 @@ import { hostname } from 'node:os'
 import { WebSocket } from 'ws'
 import { connectSecureChannel, RemoteSocketStream } from '@cherrystudio/remote-transport'
 import type { ChannelOptions, SecureChannel } from '@cherrystudio/remote-transport'
-import { remoteConnectPath } from '@cherrystudio/remote-protocol'
+import { peerIdFromString } from '@libp2p/peer-id'
+import type { z } from 'zod'
+import { directEndpointUrl, pairingQrSchema } from '@cherrystudio/remote-protocol'
+import type { WsDialOptions } from './connection.js'
 import type { DeviceRecord } from './deviceStore.js'
 import type { DeviceStore } from './deviceStore.js'
 import { JsonRpcClient, JsonRpcRequestError } from './rpc/jsonRpcClient.js'
 import { toRemoteSocket } from './rpc/wsAdapter.js'
-import { urlHost } from './urlHost.js'
+import { boundedJoin, clipText } from './text.js'
 
 /**
  * The pairing half of the bridge (spec §3.3): turn the desktop's pairing
@@ -52,26 +55,75 @@ export interface PairWithPayloadOptions {
   pollTimeoutMs?: number
   /** Per-candidate dial+handshake timeout (default 10s). */
   connectTimeoutMs?: number
+  /**
+   * Aggregate budget for the candidate DIAL walk (default 30s). It bounds the
+   * SUM of dial attempts, never a single attempt (that is `connectTimeoutMs`),
+   * and it does not cover the claim/poll phase, which keeps its own fresh,
+   * claim-anchored race guard (`pollTimeoutMs`).
+   */
+  dialBudgetMs?: number
   /** Locally supported protocol versions (default [1]). */
   supportedProtocolVersions?: readonly number[]
+  /**
+   * The websocket options every dial uses — only TLS trust (`rejectUnauthorized`
+   * / `ca`) matters (issue #126: a TLS-proxied endpoint presents a certificate
+   * the client must be able to trust, e.g. a private CA; the nested
+   * `{ tls: {…} }` shape `https` accepts is NOT read by `ws`). Absent means
+   * Node's default trust store.
+   */
+  wsOptions?: WsDialOptions
 }
 
 // ---------------------------------------------------------------------------
-// Payload validation (spec §3.3 step 1, ruling 1).
+// Payload validation (spec §3.3 step 1, ruling 1; widened to the v3 custom-
+// address QR by issue #124 — upstream `bc570d2b9`, desktop 2.1.8).
 //
-// Field caps mirror the protocol package's `values.ts`: `opaqueId` is a
-// non-empty unicode string of at most 256 code units, and the claim's
-// `deviceName` is capped at 64. A payload field over its cap would be rejected
-// by the peer's strict schema anyway, so rejecting it here is the same verdict
-// one round-trip earlier, with a message the user can act on.
+// The FIELD CHECKS are the pinned protocol package's own `pairingQrSchema`: a
+// v2|v3 discriminated union whose v2 arm is `ips` (IP LITERALS only — the
+// package's fixture calls a hostname there "DNS masquerading as IP") + `port`,
+// and whose v3 arm is complete `endpoints` (`host`, `port`, `security`).
+// Hand-rolling the checks is what made a 2.1.8 invitation refuse
+// `invalid-payload` for the whole life of the 0.5.0 pin; consuming the schema
+// means the next widening ships with the pin, not with a parser edit. Four
+// local rules stay:
+//   - the raw size cap (an oversized blob must not be parsed at all),
+//   - v2's bracketed-IPv6 NORMALIZATION (ruling 2) — the published v2 arm
+//     validates BARE literals, so brackets are stripped before the parse and
+//     the archive keeps the bare form the connection layer re-brackets, and
+//   - the `unicodeText` (lone-surrogate) rule on `invitationId` /
+//     `invitationSecret` / `desktopIdentity`: the protocol values face
+//     enforces it, the pairing QR arm does not, and refusing here keeps the
+//     v2 error face identical one round trip earlier, and
+//   - the `desktopIdentity` PEER-ID DECODE (issue #153): the schema types the
+//     pin as a bounded string, while the transport only decodes it POST-OPEN,
+//     so a junk pin would otherwise cost a dial of every candidate and surface
+//     as a decoder message. `peerIdFromString` is that same decoder, run here.
+// The error face is `invalid-payload` naming the failing FIELD PATHS only:
+// zod issues carry the `input`, so values never enter the message — an
+// `invitationSecret` must not surface in a user-visible error.
 // ---------------------------------------------------------------------------
 
-const PAYLOAD_TYPE = 'cherry-studio-pair'
-const PAYLOAD_VERSION = 2
 /** Overall payload ceiling: a QR code never approaches this. */
 const MAX_PAYLOAD_BYTES = 10 * 1024
-/** `opaqueId` cap for invitationId/invitationSecret/desktopIdentity. */
-const OPAQUE_ID_MAX = 256
+/**
+ * Bounds the unknown-key WARNING (issue #155). The keys in that warning are
+ * payload-CONTROLLED NAMES, and `MAX_PAYLOAD_BYTES` is no bound at all on the
+ * line: a 10 KiB payload carrying 32 unknown keys of ~256 characters used to
+ * join into ~8.2 KB of attacker-chosen text (the measured fixture is 8,192
+ * characters of keys and an 8,312-character line) on the operator's log.
+ *
+ * `UNKNOWN_FIELDS_MAX` is the joined list's budget — the same 240-character
+ * working budget as `LOG_TEXT_MAX`, so "one bounded peer detail" means one
+ * number for one detail-sized face (pairing's `FAILURE_SEGMENT_MAX` is the
+ * same NUMBER bounding a different quantity: a whole `<label>: <detail>`).
+ * `UNKNOWN_FIELD_MAX` clips ONE
+ * key: 64 characters is longer than any field name the protocol defines, so a
+ * clipped key is always a malformed or hostile payload, never a real typo the
+ * operator needs whole. A list that stops early names the count (`(+K more)`);
+ * entries are never dropped silently.
+ */
+const UNKNOWN_FIELDS_MAX = 240
+const UNKNOWN_FIELD_MAX = 64
 /** The claim's deviceName cap; a hostname may reach 253, so it is truncated. */
 const DEVICE_NAME_MAX = 64
 /** Bounds a single candidate host string (IPv6 literals are ~45). */
@@ -79,21 +131,45 @@ const HOST_MAX = 256
 /** Matches the protocol's unicodeText: no lone UTF-16 surrogates. */
 const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/
 
-/** Fields the implementation consumes; everything else in the payload is ignored. */
-const KNOWN_FIELDS = new Set([
+/**
+ * The keys each QR ARM consumes (selected by `v`). A payload field outside
+ * the MATCHED arm's set is ignored with a warning — the desktop names hosts
+ * the design does not use. One union set would silently swallow a v2 payload
+ * carrying a spurious `endpoints` (or v3 carrying `ips`/`port`); the arm
+ * split keeps the pre-schema warning behavior.
+ */
+const V2_KEYS = new Set([
   'v',
   't',
-  'port',
+  'name',
   'ips',
+  'port',
+  'invitationId',
+  'invitationSecret',
+  'desktopIdentity',
+  'protocolVersions',
+])
+const V3_KEYS = new Set([
+  'v',
+  't',
+  'name',
+  'endpoints',
   'invitationId',
   'invitationSecret',
   'desktopIdentity',
   'protocolVersions',
 ])
 
-interface PairingPayload {
-  hosts: string[]
+/** One dial candidate; a v3 endpoint carries its OWN port and scheme. */
+interface PairCandidate {
+  host: string
   port: number
+  security: 'ws' | 'wss'
+}
+
+interface PairingPayload {
+  /** Ordered dial candidates — every entry is attempted before `unreachable`. */
+  candidates: PairCandidate[]
   invitationId: string
   invitationSecret: string
   desktopIdentity: string
@@ -119,12 +195,14 @@ function isUnicodeText(value: string): boolean {
   return !LONE_SURROGATE_RE.test(value)
 }
 
-function checkString(value: unknown, field: string, max: number): string {
-  if (typeof value !== 'string') invalid(`payload field "${field}" must be a string`)
-  if (value.length === 0) invalid(`payload field "${field}" must not be empty`)
-  if (value.length > max) invalid(`payload field "${field}" exceeds ${max} characters`)
-  if (!isUnicodeText(value)) invalid(`payload field "${field}" is not valid unicode text`)
-  return value
+/** Rejections quote issue PATHS (deduplicated, sorted). The "never inputs"
+ * promise is the CALL SITE's property — only `issue.path` is read here; an
+ * editor reaching for `issue.message` or `String(error)` must re-check what
+ * zod embeds there before keeping that promise. */
+function schemaIssuePaths(error: z.ZodError): string {
+  return [...new Set(error.issues.map((issue) => issue.path.join('.') || 'payload'))]
+    .sort()
+    .join(', ')
 }
 
 /**
@@ -152,9 +230,9 @@ function normalizeHost(raw: string): string {
 }
 
 /**
- * Parses and validates the pairing payload. Unknown fields are ignored (with a
- * warning) — the payload carries host naming the design does not consume — but
- * the fields on the manifest are judged against their protocol caps.
+ * Parses and validates the pairing payload against the published
+ * `pairingQrSchema` (v2 or v3). Unknown fields are ignored (with a warning);
+ * every field judgement is the schema's, capped by the local size rule.
  */
 function parsePayload(payload: string): PairingPayload {
   // Size is judged on the raw string first: an oversized blob must not be
@@ -174,47 +252,97 @@ function parsePayload(payload: string): PairingPayload {
   }
 
   const raw = parsed as Record<string, unknown>
-  if (raw['v'] !== PAYLOAD_VERSION) {
-    invalid(`payload version must be ${PAYLOAD_VERSION}`)
-  }
-  if (raw['t'] !== PAYLOAD_TYPE) {
-    invalid(`payload type must be "${PAYLOAD_TYPE}"`)
+
+  // Normalize v2 bracketed IPv6 entries BEFORE the schema sees them;
+  // non-string entries pass through for the schema to judge (the published
+  // arm rejects them with the same `invalid-payload` verdict).
+  const ips = raw['ips']
+  const input = Array.isArray(ips)
+    ? {
+        ...raw,
+        ips: ips.map((entry) => (typeof entry === 'string' ? normalizeHost(entry) : entry)),
+      }
+    : raw
+
+  const result = pairingQrSchema.safeParse(input)
+  if (!result.success) {
+    invalid(`payload rejected by the pairing QR schema (v2 or v3): ${schemaIssuePaths(result.error)}`)
   }
+  const qr = result.data
 
-  const ignored = Object.keys(raw).filter((key) => !KNOWN_FIELDS.has(key))
+  // Unknown-key warning, judged against the MATCHED arm's keys (see the
+  // V2_KEYS/V3_KEYS docblock): after the parse, so a payload that fails the
+  // schema is never warned-and-then-rejected — its verdict is the rejection.
+  const ignored = Object.keys(raw).filter((key) => !(qr.v === 2 ? V2_KEYS : V3_KEYS).has(key))
   if (ignored.length > 0) {
-    console.warn(`[cherry-remote] pairing payload ignored unknown field(s): ${ignored.join(', ')}`)
+    console.warn(
+      `[cherry-remote] pairing payload ignored unknown field(s): ${boundedJoin(ignored, {
+        max: UNKNOWN_FIELDS_MAX,
+        itemMax: UNKNOWN_FIELD_MAX,
+      })}`,
+    )
   }
 
-  const port = raw['port']
-  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) {
-    invalid('payload field "port" must be an integer in 1..65535')
+  const candidates: PairCandidate[] =
+    qr.v === 2
+      ? qr.ips.map((host) => ({ host, port: qr.port, security: 'ws' as const }))
+      : qr.endpoints.map((endpoint) => ({
+          host: endpoint.host,
+          port: endpoint.port,
+          security: endpoint.security,
+        }))
+
+  // ADDRESS rules the schema cannot express (issue #135 review). The pinned
+  // schema already constrains a v3 endpoint port, but that is the PIN's
+  // property, not ours — a widening must not reopen the hole — and it has no
+  // uniqueness rule at all. Judged HERE — for BOTH arms, after normalization,
+  // before any socket — because an invalid address must never consume the
+  // invitation, and must never reach `store.upsert` after an approval (where a
+  // validation failure would surface as `unreachable` about an invitation
+  // already spent).
+  const seenHosts = new Set<string>()
+  for (const candidate of candidates) {
+    if (!Number.isInteger(candidate.port) || candidate.port < 1 || candidate.port > 65_535) {
+      invalid(`payload endpoint "${candidate.host}": port must be an integer in 1..65535`)
+    }
+    if (seenHosts.has(candidate.host)) {
+      // One host, one port: `DeviceRecord` v4 stores `ports` per host, so a
+      // same-host/two-port invitation cannot be represented — refuse it by
+      // name instead of silently keeping one port. (The desktop's v2 builder
+      // publishes one shared port per address; a v3 builder emitting one host
+      // twice was not observed upstream, so this refusal is ours.)
+      invalid(`payload endpoints must not repeat host "${candidate.host}"`)
+    }
+    seenHosts.add(candidate.host)
   }
 
-  const ips = raw['ips']
-  if (!Array.isArray(ips) || ips.length === 0) {
-    invalid('payload field "ips" must be a non-empty array')
+  // The lone-surrogate rule is ours (see the header): the claim RPC would
+  // carry such a value to the peer's unicodeText params face and be refused
+  // there; naming the field now is the same verdict one round trip earlier.
+  for (const field of ['invitationId', 'invitationSecret', 'desktopIdentity'] as const) {
+    if (!isUnicodeText(qr[field])) invalid(`payload field "${field}" is not valid unicode text`)
   }
-  const hosts = ips.map((entry, index) =>
-    normalizeHost(checkString(entry, `ips[${index}]`, HOST_MAX)),
-  )
-
-  const invitationId = checkString(raw['invitationId'], 'invitationId', OPAQUE_ID_MAX)
-  const invitationSecret = checkString(raw['invitationSecret'], 'invitationSecret', OPAQUE_ID_MAX)
-  const desktopIdentity = checkString(raw['desktopIdentity'], 'desktopIdentity', OPAQUE_ID_MAX)
 
-  const versions = raw['protocolVersions']
-  if (!Array.isArray(versions) || versions.length === 0) {
-    invalid('payload field "protocolVersions" must be a non-empty array')
+  // The PIN must DECODE here (issue #153). The published schema types
+  // `desktopIdentity` as a 1..256-char string, so a junk pin passes it; the
+  // transport decodes it only POST-OPEN (`peerIdFromString` in the channel
+  // handshake), which cost a dial of every candidate and surfaced as
+  // `channel: Please pass a multibase decoder …` — a decoder message instead
+  // of the offending field. Use the transport's OWN decoder, at the same
+  // version, before any socket: name the FIELD, never the value.
+  try {
+    peerIdFromString(qr.desktopIdentity)
+  } catch {
+    invalid('payload field "desktopIdentity" is not a peer id')
   }
-  const protocolVersions = versions.map((version) => {
-    if (typeof version !== 'number' || !Number.isInteger(version)) {
-      invalid('payload field "protocolVersions" must contain integers')
-    }
-    return version
-  })
 
-  return { hosts, port, invitationId, invitationSecret, desktopIdentity, protocolVersions }
+  return {
+    candidates,
+    invitationId: qr.invitationId,
+    invitationSecret: qr.invitationSecret,
+    desktopIdentity: qr.desktopIdentity,
+    protocolVersions: qr.protocolVersions,
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -223,10 +351,52 @@ function parsePayload(payload: string): PairingPayload {
 
 const DEFAULT_SUPPORTED_PROTOCOL_VERSIONS: readonly number[] = [1]
 const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
+/**
+ * ONE aggregate budget for the candidate DIAL walk (issue #141). A v3 QR admits
+ * up to 32 endpoints, so 32 serial `connectTimeoutMs` dials could spend 320 s
+ * on an invitation that lives 120 s. It bounds the SUM, never one attempt.
+ */
+const DEFAULT_DIAL_BUDGET_MS = 30_000
 const DEFAULT_POLL_INTERVAL_MS = 1_000
 /** The protocol invitationMs: 120s of invitation, and our poll race guard. */
 const DEFAULT_POLL_TIMEOUT_MS = 120_000
 const VERIFICATION_CODE_RE = /^[0-9]{6}$/
+/** Bounds the close frame's reason text quoted into a candidate failure. */
+const CLOSE_REASON_MAX = 200
+/**
+ * Bounds ONE candidate failure segment of the joined `unreachable` verdict
+ * (issue #148). Unbounded, a v3 QR's 32 endpoints × a 253-char host — repeated
+ * again inside the dial error — reached ~17-18 KB in one tool result that
+ * `cherry_pair` passes through whole. The bound is per SEGMENT, never a
+ * "first N + and M more" cut: issue #141's contract is that every candidate,
+ * attempted or not, is NAMED.
+ *
+ * `FAILURE_LABEL_MAX` clips an over-long `host:port` in the HOST and keeps the
+ * PORT (`<host prefix>…:<port>`) — a prefix without its port names no address.
+ * `FAILURE_SEGMENT_MAX` bounds the whole `<label>: <detail>`: the detail is
+ * clipped to the room the label leaves, and the `… (+N chars)` marker's own
+ * length is charged to the bound. 32 candidates then join to at most
+ * 32 × 240 + 31 × 2 = 7,742 characters.
+ */
+const FAILURE_LABEL_MAX = 128
+const FAILURE_SEGMENT_MAX = 240
+/**
+ * Bounds the progress line's HOST TEXT (issue #152). `report()` runs once per
+ * stage transition and used to join every candidate host: a v3 QR admits 32
+ * endpoints and a host name may be 253 characters, so one stage wrote ~8 KB.
+ *
+ * The FIRST host is always shown — a line with no host at all would lose the
+ * run's identity — then further hosts are appended while the host NAMES fit
+ * this budget; a truncated list carries an explicit `(+K more)` marker that
+ * rides ON TOP of the budget (the marker is a COUNT, not a host name).
+ *
+ * Invariant: the host names consume ≤ `STAGE_HOSTS_CHARS`, with ONE exception
+ * — a FIRST host that alone exceeds it, still shown because the identity rule
+ * outranks the bound. A LATER over-long host can never enter the bounded
+ * section (`used` already holds the first host, so it fails the fit test) and
+ * is omitted into the marker.
+ */
+const STAGE_HOSTS_CHARS = 160
 
 const noop = (): void => {}
 
@@ -257,12 +427,81 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
-// urlHost() moved to its shared home (./urlHost): both dial sites — pairing's
-// candidate dial and DeviceConnection's per-device dial — bracket IPv6 the
-// same way. Re-exported here to keep this module's original public surface.
-export { urlHost } from './urlHost.js'
+/**
+ * Tags a PRE-OPEN `ws` error as a candidate-dial failure (issue #142). The
+ * `websocket:` prefix is the KIND: the operator's fix is this address or its
+ * TLS, not the network — the contrast with `timeout:` is the whole point of the
+ * prefix, and it is what the joined `unreachable` verdict shows. The `ws` error
+ * carries the discriminator a bare message drops — an OS `code`
+ * (`ECONNREFUSED`, `ENOTFOUND`, a TLS code) or a numeric ws code — so it is
+ * appended, and only when it is actually a string or a number (never
+ * `undefined`/`null`).
+ */
+function webSocketFailure(error: Error): Error {
+  const code = (error as { code?: unknown }).code
+  const suffix = typeof code === 'string' || typeof code === 'number' ? ` (code ${code})` : ''
+  return new Error(`websocket: ${error.message}${suffix}`)
+}
+
+/**
+ * Tags a POST-OPEN channel failure as a candidate-dial failure (issue #147).
+ * `channel:` is the THIRD kind, deliberately not `websocket:`: the upgrade
+ * completed, so the address works and only the channel's establishment failed
+ * (Noise handshake, remote identity proof, protocol offer). Blaming the
+ * address would send the operator to inspect something that demonstrably
+ * answered. No code suffix is appended: a Noise-stage error can carry its own
+ * string code (`ERR_INVALID_CRYPTO_EXCHANGE`), but that is an internal label
+ * rather than the ws/OS discriminator the other kinds keep, so it is
+ * deliberately dropped.
+ */
+function channelFailure(error: Error): Error {
+  return new Error(`channel: ${error.message}`)
+}
+
+/**
+ * The ONE text form of a candidate failure (issue #148). All three
+ * `failures.push` sites render through it, so the segment bound cannot hold on
+ * one arm (budget-exhausted, dial failure, claim fall-through) and fail on
+ * another. A short label and a short detail are returned BYTE FOR BYTE; the
+ * enforcement is never a rewrite of ordinary text.
+ *
+ * The detail goes through the SHARED {@link clipText} (issue #155), the same
+ * `… (+N chars)` form every other peer-controlled log detail uses; the clip
+ * point is no longer private to pairing.
+ */
+function failureSegment(label: string, detail: string): string {
+  const boundedLabel = clipFailureLabel(label)
+  const room = FAILURE_SEGMENT_MAX - boundedLabel.length - 2 // ': '
+  // Unreachable while the label cap holds (128 + 2 < 240). It is kept so the
+  // SEGMENT bound is independent of the label cap: a removed label cap cuts
+  // the label into the segment instead of letting the segment overflow.
+  if (room <= 0) return boundedLabel.slice(0, FAILURE_SEGMENT_MAX)
+  return `${boundedLabel}: ${clipText(detail, room)}`
+}
+
+/**
+ * Clips a `host:port` label in the HOST, keeping the port (see
+ * {@link FAILURE_LABEL_MAX}).
+ *
+ * Identification here is PREFIX + PORT, not uniqueness: two schema-distinct
+ * 253-char hosts that agree on their first ~121 characters AND on the port clip
+ * to identical labels (ports may repeat — only hosts are deduped). Each still
+ * contributes its own segment, so #141's per-candidate count is intact.
+ */
+function clipFailureLabel(label: string): string {
+  if (label.length <= FAILURE_LABEL_MAX) return label
+  const colon = label.lastIndexOf(':')
+  if (colon < 0) return `${label.slice(0, FAILURE_LABEL_MAX - 1)}…`
+  const suffix = `…${label.slice(colon)}` // `…` + `:<port>`
+  const hostRoom = FAILURE_LABEL_MAX - suffix.length
+  return hostRoom > 0 ? `${label.slice(0, hostRoom)}${suffix}` : suffix.slice(0, FAILURE_LABEL_MAX)
+}
 
 /** Dials one candidate address and completes the Noise handshake.
+ *
+ * The URL is the published `directEndpointUrl` — it brackets IPv6 literals,
+ * appends the fixed `/v1/remote/connect` path, and selects `ws:` or `wss:`
+ * from the candidate's own `security` (v3 TLS-proxy endpoints dial TLS).
  *
  * Both halves start concurrently (`Promise.all`): the peer's accept half is
  * already running on its side, so a sequential dial would deadlock the
@@ -274,40 +513,90 @@ export { urlHost } from './urlHost.js'
  * rather than assumed: the payload's `desktopIdentity` is the peer the Noise
  * XX handshake must prove, so a swapped-in impostor fails the handshake
  * instead of being pinned as the desktop.
+ *
+ * A failure carries one of THREE kinds into the joined `unreachable` verdict,
+ * because each names the operator's next check: `timeout:` (the per-attempt
+ * timer won its race — check the network), `websocket:` (the socket failed
+ * BEFORE the upgrade — check this address or its TLS), and `channel:` (the
+ * socket came up and the channel failed AFTER it — check the peer's identity
+ * or the protocol offer). A stalled handshake stays `timeout:`: the dial
+ * promise's own timer settles first, so the abort it triggers cannot win.
  */
 async function dial(
-  host: string,
-  port: number,
+  candidate: PairCandidate,
   identity: Uint8Array,
   desktopIdentity: string,
   protocolVersions: readonly number[],
   timeoutMs: number,
+  wsOptions: PairWithPayloadOptions['wsOptions'],
 ): Promise<TempChannel> {
-  const ws = new WebSocket(`ws://${urlHost(host)}:${port}${remoteConnectPath}`)
+  const { host, port } = candidate
+  const ws = new WebSocket(directEndpointUrl(candidate), wsOptions)
   const controller = new AbortController()
   let timer: ReturnType<typeof setTimeout> | undefined
   const timedOut = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`connect to ${host}:${port} timed out`)), timeoutMs)
+    timer = setTimeout(
+      () => reject(new Error(`timeout: connect to ${host}:${port} timed out`)),
+      timeoutMs,
+    )
   })
 
   try {
     const connecting = (async (): Promise<SecureChannel> => {
       await new Promise<void>((resolve, reject) => {
-        ws.once('open', () => resolve())
-        ws.once('error', (error: Error) => reject(error))
-      })
-      const stream = new RemoteSocketStream(
-        toRemoteSocket(ws),
-        silentComponentLogger.forComponent('pairing'),
-        'outbound',
-      )
-      return connectSecureChannel(stream, {
-        identity,
-        logger: silentComponentLogger,
-        protocolVersions: [...protocolVersions],
-        signal: controller.signal,
-        remoteIdentity: desktopIdentity,
+        // A socket can fail before the upgrade completes in two shapes: an
+        // `error` event (the HTTP handshake's own failure) and a `close` with
+        // no error. Both are the `websocket:` kind; the close path is tagged
+        // with the close code and (bounded) reason instead of a message.
+        // Unexercised under the pinned `ws` 8.22: every client pre-open failure
+        // emits `error` first (verified in the library source), so a `ws` bump
+        // must re-check that ordering.
+        // Whichever fires first wins, and the listeners are removed on settle
+        // so a LATER close — e.g. the timeout's `ws.terminate()` — cannot fire
+        // a stale rejection on an open promise nobody waits for anymore.
+        const settle = (outcome: () => void): void => {
+          ws.off('open', onOpen)
+          ws.off('error', onError)
+          ws.off('close', onClose)
+          outcome()
+        }
+        const onOpen = (): void => settle(resolve)
+        const onError = (error: Error): void => settle(() => reject(webSocketFailure(error)))
+        const onClose = (code: number, reason: Buffer): void => {
+          const text = reason.toString('utf8').slice(0, CLOSE_REASON_MAX)
+          settle(() =>
+            reject(
+              new Error(
+                `websocket: closed before open (code ${code})${text === '' ? '' : ` ${text}`}`,
+              ),
+            ),
+          )
+        }
+        ws.once('open', onOpen)
+        ws.once('error', onError)
+        ws.on('close', onClose)
       })
+      // The POST-OPEN half starts here: the upgrade completed, so the socket
+      // is not what failed. Tag it `channel:` rather than `websocket:` — the
+      // address demonstrably worked, and blaming it would send the operator to
+      // the wrong fix. Wrapping only these two statements keeps every pre-open
+      // arm on its own `websocket:`/`timeout:` kind.
+      try {
+        const stream = new RemoteSocketStream(
+          toRemoteSocket(ws),
+          silentComponentLogger.forComponent('pairing'),
+          'outbound',
+        )
+        return await connectSecureChannel(stream, {
+          identity,
+          logger: silentComponentLogger,
+          protocolVersions: [...protocolVersions],
+          signal: controller.signal,
+          remoteIdentity: desktopIdentity,
+        })
+      } catch (error) {
+        throw channelFailure(error instanceof Error ? error : new Error(String(error)))
+      }
     })()
 
     // Aborting on timeout is what unsticks the channel half: the ws 'error'
@@ -362,6 +651,30 @@ type GetResult =
       expiresAt: string
     }
 
+/**
+ * Renders the progress line's host list under {@link STAGE_HOSTS_CHARS} (the
+ * invariant lives on that constant). A truncated list names the first host,
+ * then says how many candidates it is NOT naming — the count is explicit so a
+ * reader can tell a short host list from a bounded one.
+ */
+function stageHosts(hosts: readonly string[]): string {
+  const [first, ...rest] = hosts
+  // Defensive only: both QR arms require at least one candidate, so a parsed
+  // payload always reaches the fill loop below.
+  if (first === undefined) return ''
+  let text = first
+  let used = first.length
+  let shown = 1
+  for (const host of rest) {
+    if (used + host.length + 2 > STAGE_HOSTS_CHARS) break
+    text += `, ${host}`
+    used += host.length + 2
+    shown += 1
+  }
+  const omitted = hosts.length - shown
+  return omitted > 0 ? `${text} (+${omitted} more)` : text
+}
+
 /**
  * Pairs this DSH profile with a Cherry Studio desktop from its pairing payload,
  * returning the PERSISTED record (ruling 6).
@@ -384,11 +697,14 @@ export async function pairWithPayload(opts: PairWithPayloadOptions): Promise<Dev
   const onStatus = opts.onStatus ?? noop
   // INFO-LEVEL PROGRESS (spec §5): every stage transition is logged, so an
   // operator watching a run that can take a minute can see where it is WITHOUT
-  // the tool result. Only the stage NAME and the payload's host list are
-  // recorded — never `invitationSecret`, the claim's verification code, or any
-  // token (those are exactly what the sanitization contract forbids).
+  // the tool result. Only the stage NAME and a BOUNDED view of the payload's
+  // host list are recorded — never `invitationSecret`, the claim's verification
+  // code, or any token (those are exactly what the sanitization contract
+  // forbids), and never an unbounded join of 32 maximum-length hosts.
   const report = (stage: string): void => {
-    console.info(`[cherry-remote] pairing stage ${stage} (hosts: ${payload.hosts.join(', ')})`)
+    console.info(
+      `[cherry-remote] pairing stage ${stage} (hosts: ${stageHosts(payload.candidates.map((candidate) => candidate.host))})`,
+    )
     onStatus(stage)
   }
   report('validate')
@@ -400,52 +716,94 @@ export async function pairWithPayload(opts: PairWithPayloadOptions): Promise<Dev
   const offered = payload.protocolVersions.filter((version) => supported.includes(version))
 
   const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
+  // ONE deadline for the whole candidate walk (issue #141). The per-attempt
+  // bound stays `connectTimeoutMs`, but no candidate may START after this
+  // instant and the last dial is clamped to what is left of it. The CLAIM/POLL
+  // phase below is deliberately outside it: that phase keeps its own FRESH
+  // race guard anchored at the claim (`pollTimeoutMs`), not the invitation's
+  // birth — the peer's own `expired` is the real bound there.
+  //
+  // The deadline rides the MONOTONIC clock: a backward wall-clock step would
+  // GROW `remaining` and re-open the unbounded walk (the per-dial clamp cannot
+  // bound a walk whose deadline moved).
+  const dialBudgetMs =
+    typeof opts.dialBudgetMs === 'number' && Number.isFinite(opts.dialBudgetMs)
+      ? opts.dialBudgetMs
+      : DEFAULT_DIAL_BUDGET_MS
+  const dialDeadline = performance.now() + dialBudgetMs
   report('connect')
 
   const failures: string[] = []
-  for (const host of payload.hosts) {
+  // The approved record, set by the winner and written ONCE after the loop.
+  let approved: DeviceRecord | undefined
+  for (const candidate of payload.candidates) {
+    const label = `${candidate.host}:${candidate.port}`
+    const remaining = dialDeadline - performance.now()
+    if (remaining <= 0) {
+      failures.push(
+        failureSegment(
+          label,
+          `not attempted (the ${dialBudgetMs} ms dial budget was exhausted before this candidate)`,
+        ),
+      )
+      continue
+    }
     let temp: TempChannel
     try {
       temp = await dial(
-        host,
-        payload.port,
+        candidate,
         opts.identity,
         payload.desktopIdentity,
         offered,
-        connectTimeoutMs,
+        // Clamped so the last attempt cannot OVERSHOOT the budget: a dial must
+        // never outlive the deadline it was started under.
+        Math.min(connectTimeoutMs, remaining),
+        opts.wsOptions,
       )
     } catch (error) {
-      failures.push(`${host}: ${error instanceof Error ? error.message : String(error)}`)
+      failures.push(failureSegment(label, error instanceof Error ? error.message : String(error)))
       continue
     }
     try {
-      const record = await claimAndAwait(temp.client, payload, offered, opts, report)
+      approved = await claimAndAwait(temp.client, payload, offered, opts, report, candidate)
       destroy(temp)
-      // `DeviceStore.upsert` persists and returns nothing, so the call returns
-      // the very record it handed over — the persisted archive entry, not a
-      // pre-write copy.
-      opts.store.upsert(record)
-      return record
+      // Settled: stop walking. The ARCHIVE WRITE is deliberately outside this
+      // per-candidate catch (below) — see the fall-through comment.
+      break
     } catch (error) {
       destroy(temp)
       if (error instanceof PairingError) throw error
-      // MID-FLOW FALL-THROUGH (documented boundary): a NON-`PairingError` here
-      // is an unexpected fault on THIS candidate — not a verdict about the
-      // invitation. The walk therefore CONTINUES to the next candidate address,
-      // and if a later candidate reaches a real terminal state that verdict
-      // wins. Only if EVERY candidate fails does the walk end as `unreachable`;
-      // conversely an unexpected fault on the FIRST candidate followed by a
-      // peer `rejected` on the SECOND surfaces as `rejected`, not `unreachable`.
-      // That is deliberate: the peer's answer about the invitation outranks our
-      // own transport trouble, and it is the one the user can act on.
-      failures.push(`${host}: ${error instanceof Error ? error.message : String(error)}`)
+      // MID-FLOW FALL-THROUGH (documented boundary): a NON-`PairingError` DIAL
+      // or CLAIM fault here is an unexpected fault on THIS candidate — not a
+      // verdict about the invitation. The walk therefore CONTINUES to the next
+      // candidate address, and if a later candidate reaches a real terminal
+      // state that verdict wins. Only if EVERY candidate fails does the walk end
+      // as `unreachable`; conversely an unexpected fault on the FIRST candidate
+      // followed by a peer `rejected` on the SECOND surfaces as `rejected`, not
+      // `unreachable`. That is deliberate: the peer's answer about the invitation
+      // outranks our own transport trouble, and it is the one the user can act
+      // on. The archive write is NOT in this arm: it happens once, after a
+      // winner, and is TERMINAL — a store failure is a fact about the archive,
+      // never an address failure.
+      failures.push(failureSegment(label, error instanceof Error ? error.message : String(error)))
     }
   }
 
-  throw new PairingError(
-    'unreachable',
-    `no candidate address could complete pairing (${failures.join('; ')})`,
-  )
+  if (approved === undefined) {
+    throw new PairingError(
+      'unreachable',
+      `no candidate address could complete pairing (${failures.join('; ')})`,
+    )
+  }
+
+  // ONE write, after a winner and outside every per-candidate catch. A failure
+  // here surfaces as itself (`QuarantinedArchiveError`, a validation error, …):
+  // the desktop already approved, so blaming an address would be a lie and the
+  // invitation is already spent. `upsert` returns nothing, so the return value
+  // is the record handed to it — the persisted archive entry, not a pre-write
+  // copy.
+  opts.store.upsert(approved)
+  return approved
 }
 
 /**
@@ -460,6 +818,7 @@ async function claimAndAwait(
   protocolVersions: readonly number[],
   opts: PairWithPayloadOptions,
   onStatus: (stage: string) => void,
+  candidate: PairCandidate,
 ): Promise<DeviceRecord> {
   const deviceName = (opts.name ?? hostname()).slice(0, DEVICE_NAME_MAX)
 
@@ -525,7 +884,7 @@ async function claimAndAwait(
       )
     }
     if (result.status === 'approved') {
-      return recordFrom(payload, result, deviceName)
+      return recordFrom(payload, result, deviceName, candidate)
     }
     // `pending`: the user has not acted yet. The local deadline is race
     // protection for a peer that never reaches a terminal state; the normal
@@ -547,11 +906,26 @@ async function claimAndAwait(
  * `displayName` is the name the claim actually carried — the record must not
  * disagree with what the desktop shows for this device, and re-deriving it
  * here would lose the 64-char truncation.
+ *
+ * The address projection: every candidate host is kept (the v2 record always
+ * did, and reconnect re-walks them), and `port` is the one the pairing actually
+ * completed on — the WINNER's port, and the record-level fallback. A mixed-port
+ * v3 payload is now persisted FAITHFULLY, per host, through `ports` (issue
+ * #135): the 2.1.8 generation side emits one endpoint per custom-address
+ * invitation (`ApiGatewayService.getRemoteEndpoint`:
+ * `advertisedEndpoint ? [advertisedEndpoint] : …`), but a QR that does carry a
+ * mixed list must still reconnect each host on its own port. `security` IS
+ * persisted (issue #126), one entry per host, taken from the very candidates the
+ * walk dialed — so a schemaVersion-4 record remembers the scheme the pairing
+ * actually used, and the steady-state dial (src/connection.ts) rebuilds the
+ * same URL instead of a plain `ws://`. Before that, #124 paired a TLS endpoint
+ * and made it unreachable on every reconnect.
  */
 function recordFrom(
   payload: PairingPayload,
   approved: Extract<GetResult, { status: 'approved' }>,
   deviceName: string,
+  winner: PairCandidate,
 ): DeviceRecord {
   const grants = (approved.authorization?.grants ?? [])
     .map((grant) => grant.domain)
@@ -580,11 +954,21 @@ function recordFrom(
   }
 
   return {
-    schemaVersion: 2,
+    schemaVersion: 4,
     deviceId: approved.deviceId,
     displayName: deviceName,
-    hosts: [...payload.hosts],
-    port: payload.port,
+    hosts: payload.candidates.map((candidate) => candidate.host),
+    // The winner's port, and the record-level fallback (issue #135).
+    port: winner.port,
+    // One scheme and one port per host, from the very candidates the walk
+    // dialed: both maps and `hosts` come from the same list, so they cannot
+    // disagree.
+    security: Object.fromEntries(
+      payload.candidates.map((candidate) => [candidate.host, candidate.security]),
+    ),
+    ports: Object.fromEntries(
+      payload.candidates.map((candidate) => [candidate.host, candidate.port]),
+    ),
     desktopIdentity: payload.desktopIdentity,
     grants,
     accessToken: approved.accessToken,
@@ -605,8 +989,16 @@ function asPairingError(error: unknown, stage: 'hello' | 'claim' | 'poll'): Pair
   if (reason !== undefined) {
     return new PairingError('rejected', `the desktop refused the pairing ${stage} (${reason})`)
   }
+  // The peer's message rides the SAME segment shaping as one candidate failure
+  // (issue #155): this verdict used to pass it through whole, bounded only by
+  // the 64 KiB record budget, and `cherry_pair` hands the message to the model
+  // verbatim. `unreachable` keeps the `pairing <stage> failed: <detail>` label,
+  // so the STAGE is still named; a detail that fits comes back byte for byte.
   return new PairingError(
     'unreachable',
-    `pairing ${stage} failed: ${error instanceof Error ? error.message : String(error)}`,
+    failureSegment(
+      `pairing ${stage} failed`,
+      error instanceof Error ? error.message : String(error),
+    ),
   )
 }