@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -9,8 +9,11 @@
  *        `gateway/src/remote-web/pairing-challenge-store.ts`)
  *   - `POST /v1/remote-web/pairing-verification`  approve by user code
  *       (`gateway/src/http/routes/remote-web-pairing-verification.ts`)
+ *       (loopback-only)
  *   - `POST /v1/remote-web/pairing-token`         poll + exchange device code
- *       (`gateway/src/http/routes/remote-web-pairing-token.ts`)
+ *       (`gateway/src/http/routes/remote-web-pairing-token.ts`): a browser
+ *        receives its refresh token as an `HttpOnly` cookie; a request that
+ *        carries a `deviceId` receives a device-bound one in the body instead
  *   - `GET  /v1/remote-web/pairing-requests`          list pending challenges
  *       (loopback-only)
  *   - `POST /v1/remote-web/pairing-requests/approve`  approve by request id
@@ -19,7 +22,8 @@
  *       (loopback-only)
  *
  * These shapes mirror those handlers' request/response bodies exactly so the
- * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), and the web SPA
+ * gateway, the `vellum pair` CLI (`cli/src/commands/pair.ts`), the host-side
+ * pairing sessions (`packages/local-mode/src/pair.ts`), and the web SPA
  * (`clients/web/src/lib/auth/remote-gateway-session.ts`) share one definition
  * and cannot silently drift.
  *
@@ -128,10 +132,57 @@ export interface RemoteWebPairingRequestDenyResponse {
   status: "denied";
 }
 
+/**
+ * Platforms a device-bound pairing exchange may declare for itself. The value
+ * is what the host's `Paired devices` list renders for the new pairing.
+ */
+export const REMOTE_WEB_PAIRING_PLATFORMS = [
+  "cli",
+  "desktop",
+  "ios",
+  "android",
+] as const;
+
+export type RemoteWebPairingPlatform =
+  (typeof REMOTE_WEB_PAIRING_PLATFORMS)[number];
+
+/** Platform recorded when an exchange names none the gateway recognizes. */
+export const DEFAULT_REMOTE_WEB_PAIRING_PLATFORM: RemoteWebPairingPlatform =
+  "desktop";
+
+/**
+ * A requested platform coerced to a known value. The pairing-token route is
+ * publicly reachable and the platform renders verbatim in the host's
+ * paired-devices list, so an unrecognized value never reaches the DB.
+ */
+export function resolveRemoteWebPairingPlatform(
+  raw: unknown,
+): RemoteWebPairingPlatform {
+  return (
+    REMOTE_WEB_PAIRING_PLATFORMS.find((platform) => platform === raw) ??
+    DEFAULT_REMOTE_WEB_PAIRING_PLATFORM
+  );
+}
+
 /** `POST /v1/remote-web/pairing-token` request body. */
 export interface RemoteWebPairingTokenRequest {
   /** The `deviceCode` from the challenge. */
   deviceCode: string;
+  /**
+   * Client-generated device id, sent only by a trusted host completing the
+   * exchange for itself. It switches the gateway to a device-bound, per-device
+   * revocable credential whose refresh token comes back in the response body.
+   * Browsers omit it and keep the cookie delivery.
+   */
+  deviceId?: string;
+  /** Platform to record for the device. Ignored without a `deviceId`. */
+  platform?: RemoteWebPairingPlatform;
+  /**
+   * Optional self-reported device name, for example "Vellum iOS app". The gateway
+   * stores it verbatim (capped) and never trusts it for authorization. Absent from
+   * clients that predate this field.
+   */
+  clientReportedName?: string;
 }
 
 /**
@@ -148,8 +199,9 @@ export interface RemoteWebPairingTokenPendingResponse {
 
 /**
  * `POST /v1/remote-web/pairing-token` approved response body (200) — carries
- * the minted browser session credentials. The refresh token is delivered out
- * of band as an `HttpOnly` cookie, not in this body.
+ * the minted session credentials. A browser exchange (no `deviceId`) receives
+ * its refresh token out of band as an `HttpOnly` cookie and so omits the two
+ * refresh fields below; a device-bound exchange receives it here instead.
  */
 export interface RemoteWebPairingTokenApprovedResponse {
   status: "approved";
@@ -160,6 +212,10 @@ export interface RemoteWebPairingTokenApprovedResponse {
   refreshAfter: string;
   guardianId: string;
   assistantId: string;
+  /** Device-bound refresh token, present only for a `deviceId` exchange. */
+  refreshToken?: string;
+  /** ISO-8601 instant the device-bound refresh token expires. */
+  refreshTokenExpiresAt?: string;
 }
 
 /** Union of the two terminal `pairing-token` response bodies. */
@@ -169,7 +225,7 @@ export type RemoteWebPairingTokenResponse =
 
 // ── Shared pairing URL helpers ──────────────────────────────────────────────
 //
-// Every surface that mints a pairing (the `vellum pair --qr` CLI, the web
+// Every surface that mints a pairing (the `vellum pair` CLI, the web
 // settings "Pair a device" card) must accept the same public URLs and build
 // the same scannable links. The helpers are environment-neutral (WHATWG URL
 // only) so both Node and browser callers share one implementation.
@@ -178,6 +234,7 @@ export type RemoteWebPairingTokenResponse =
 export type PublicBaseUrlRejection =
   | "unparseable"
   | "loopback"
+  | "private-address"
   | "non-https"
   | "service-website";
 
@@ -204,6 +261,16 @@ export const TUNNEL_PROVIDER_WEBSITE_HOSTS = [
   "www.cloudflare.com",
 ] as const;
 
+/**
+ * A hostname with any trailing DNS root dot removed. `example.com.` and
+ * `example.com` name the same host, and a resolver reads `localhost.` as the
+ * loopback name, so every host comparison below runs on the stripped form.
+ * Bracketed IPv6 literals never carry one.
+ */
+function hostnameWithoutRootDot(hostname: string): string {
+  return hostname.replace(/\.+$/, "");
+}
+
 /**
  * A URL whose exact host is a tunnel/ingress vendor's own website (see
  * {@link TUNNEL_PROVIDER_WEBSITE_HOSTS}). Exact-host only: a user's real
@@ -214,7 +281,7 @@ export function isTunnelProviderWebsiteUrl(url: string): boolean {
   let hostname: string;
   try {
     // WHATWG URL lowercases the hostname during parsing.
-    hostname = new URL(url).hostname;
+    hostname = hostnameWithoutRootDot(new URL(url).hostname);
   } catch {
     return false;
   }
@@ -231,7 +298,7 @@ export function isTunnelProviderWebsiteUrl(url: string): boolean {
 export function tunnelProviderWebsiteName(url: string): string | null {
   let hostname: string;
   try {
-    hostname = new URL(url).hostname;
+    hostname = hostnameWithoutRootDot(new URL(url).hostname);
   } catch {
     return null;
   }
@@ -247,21 +314,223 @@ export function tunnelProviderWebsiteName(url: string): string | null {
 }
 
 /**
- * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
- * encodes a loopback address is unreachable from the scanning device.
+ * A URL's comparable host: root dot stripped and IPv6 brackets removed, or
+ * null when the value is not a parseable URL.
  */
-export function isLoopbackPublicUrl(url: string): boolean {
+function comparableHost(url: string): string | null {
   try {
-    // WHATWG URL canonicalizes hostnames, so IPv6 loopback is always "[::1]".
-    const hostname = new URL(url).hostname;
-    return (
-      hostname === "localhost" ||
-      hostname === "[::1]" ||
-      /^127(?:\.\d{1,3}){3}$/.test(hostname)
+    // WHATWG URL canonicalizes hostnames: IPv6 loopback is always "[::1]", a
+    // bare "0" is "0.0.0.0", and encoded IPv4 literals become dotted quads.
+    return hostnameWithoutRootDot(new URL(url).hostname).replace(
+      /^\[|\]$/g,
+      "",
     );
   } catch {
+    return null;
+  }
+}
+
+/**
+ * Hosts that reach the dialing machine without a resolver having to agree:
+ * `localhost`, `127.x.x.x`, `[::1]`, and the wildcard binds `0.0.0.0` / `[::]`,
+ * in their dotted, hex, and IPv4-mapped spellings.
+ */
+function isDnsIndependentLoopbackHost(host: string): boolean {
+  return (
+    host === "localhost" ||
+    host === "::1" ||
+    host === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(host) ||
+    // A wildcard host reaches a local listener when dialed, so it counts as
+    // local for the pairing and refresh-channel guards alike.
+    host === "0.0.0.0" ||
+    host === "0" ||
+    host === "::" ||
+    host === "0:0:0:0:0:0:0:0" ||
+    // IPv4-mapped loopback and wildcard, in dotted and hex encodings.
+    /^(?:0:0:0:0:0|:):ffff:127(?:\.\d{1,3}){3}$/.test(host) ||
+    /^(?:0:0:0:0:0|:):ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}$/.test(host) ||
+    /^(?:0:0:0:0:0|:):ffff:0\.0\.0\.0$/.test(host) ||
+    /^(?:0:0:0:0:0|:):ffff:0:0$/.test(host)
+  );
+}
+
+/**
+ * A URL that reaches a listener on the machine dialing it, judged wide: the
+ * literals {@link isDnsIndependentLoopbackHost} covers PLUS the whole reserved
+ * `localhost` namespace (RFC 6761, so `foo.localhost` counts). A pairing link
+ * that encodes one is unreachable from the scanning device, and a host that
+ * POSTs to one is calling a service on its own machine.
+ *
+ * This is the one loopback predicate the whole pairing path reads (the pasted
+ * address, and the gatewayUrl an import registers), so the same address class
+ * can never be refused by one entry point and accepted by another. Every read
+ * of it REFUSES the address it matches, which is why it is the wide one.
+ * A guard that GRANTS something to loopback reads
+ * {@link isDnsIndependentLoopbackUrl} instead.
+ */
+export function isLoopbackPublicUrl(url: string): boolean {
+  const host = comparableHost(url);
+  if (host === null) {
     return false;
   }
+  return host.endsWith(".localhost") || isDnsIndependentLoopbackHost(host);
+}
+
+/**
+ * A URL that reaches this machine whatever the resolver does, judged narrow:
+ * exact `localhost` and the loopback/wildcard IP literals, and NOT the
+ * reserved `.localhost` namespace. RFC 6761 says a resolver should map that
+ * namespace to loopback, but glibc does not by default, so `evil.localhost`
+ * is an ordinary DNS name that can answer with any address at all.
+ *
+ * Read this wherever loopback EARNS a privilege a public host does not get,
+ * such as accepting a plaintext channel as confidential; read the wider
+ * {@link isLoopbackPublicUrl} wherever loopback is refused. Both directions
+ * then fail safe on a name that only might be local.
+ */
+export function isDnsIndependentLoopbackUrl(url: string): boolean {
+  const host = comparableHost(url);
+  return host !== null && isDnsIndependentLoopbackHost(host);
+}
+
+/** Canonical dotted-quad as its four octets, or null when it is not one. */
+function parseIpv4Literal(hostname: string): number[] | null {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+  if (!match) {
+    return null;
+  }
+  const octets = match.slice(1).map(Number);
+  return octets.every((octet) => octet <= 255) ? octets : null;
+}
+
+/** Bracketed IPv6 literal as its eight 16-bit pieces, or null. */
+function parseIpv6Literal(hostname: string): number[] | null {
+  if (!hostname.startsWith("[") || !hostname.endsWith("]")) {
+    return null;
+  }
+  const halves = hostname.slice(1, -1).split("::");
+  if (halves.length > 2) {
+    return null;
+  }
+  const toPieces = (part: string): number[] | null => {
+    if (!part) {
+      return [];
+    }
+    const pieces: number[] = [];
+    const labels = part.split(":");
+    for (const [index, label] of labels.entries()) {
+      // A trailing dotted-quad is legal IPv6 text. The WHATWG serializer never
+      // emits one, but a hand-built literal can still reach this parser.
+      if (index === labels.length - 1 && label.includes(".")) {
+        const octets = parseIpv4Literal(label);
+        if (!octets) {
+          return null;
+        }
+        pieces.push(
+          ((octets[0] ?? 0) << 8) | (octets[1] ?? 0),
+          ((octets[2] ?? 0) << 8) | (octets[3] ?? 0),
+        );
+        continue;
+      }
+      if (!/^[0-9a-f]{1,4}$/i.test(label)) {
+        return null;
+      }
+      pieces.push(Number.parseInt(label, 16));
+    }
+    return pieces;
+  };
+  const head = toPieces(halves[0] ?? "");
+  const tail = halves.length === 2 ? toPieces(halves[1] ?? "") : [];
+  if (!head || !tail) {
+    return null;
+  }
+  if (halves.length === 1) {
+    return head.length === 8 ? head : null;
+  }
+  const gap = 8 - head.length - tail.length;
+  return gap >= 1 ? [...head, ...Array<number>(gap).fill(0), ...tail] : null;
+}
+
+/**
+ * IPv4 ranges that are not publicly routable, judged from the four octets of a
+ * canonical dotted-quad. Loopback (127/8) is included so the predicate is
+ * complete on its own; `resolvePublicBaseUrl` still reports it as `loopback`
+ * because it checks that first.
+ *
+ * 100.64.0.0/10 is DELIBERATELY ABSENT. Tailscale hands out CGNAT addresses
+ * from that range and a Tailscale endpoint is a supported pairing target.
+ */
+function isPrivateIpv4(octets: readonly number[]): boolean {
+  const a = octets[0] ?? 0;
+  const b = octets[1] ?? 0;
+  const c = octets[2] ?? 0;
+  return (
+    a === 0 || // 0/8 "this network"
+    a === 10 || // 10/8 private
+    a === 127 || // 127/8 loopback
+    (a === 169 && b === 254) || // 169.254/16 link-local, incl. cloud metadata
+    (a === 172 && b >= 16 && b <= 31) || // 172.16/12 private
+    (a === 192 && b === 0 && c === 0) || // 192.0.0/24 protocol assignments
+    (a === 192 && b === 168) || // 192.168/16 private
+    (a === 198 && (b === 18 || b === 19)) || // 198.18/15 benchmarking
+    a >= 224 // 224/4 multicast, 240/4 reserved, 255.255.255.255 broadcast
+  );
+}
+
+/**
+ * A URL whose hostname is an IP literal outside publicly routable space:
+ * private, loopback, link-local (which is where the cloud instance metadata
+ * endpoint 169.254.169.254 lives), multicast, or reserved, in either address
+ * family. Pairing POSTs to whatever address the user pasted, so a literal
+ * aimed at the host's own network is refused before any request is made.
+ *
+ * Only literals written directly in the address are checked. Hostnames are
+ * NEVER resolved and resolved addresses are NEVER filtered, deliberately:
+ * Tailscale endpoints (`*.ts.net`) are a supported pairing target and resolve
+ * into the 100.64.0.0/10 CGNAT range, so post-DNS filtering would refuse them
+ * outright. It would also be TOCTOU-prone, since a name can resolve
+ * differently between the check and the connection.
+ */
+export function isPrivateNetworkPublicUrl(url: string): boolean {
+  let hostname: string;
+  try {
+    // WHATWG URL canonicalizes IP literals: decimal, octal, and hex IPv4 forms
+    // collapse to a dotted-quad, and IPv6 to a bracketed lowercase literal.
+    hostname = hostnameWithoutRootDot(new URL(url).hostname);
+  } catch {
+    return false;
+  }
+  const ipv4 = parseIpv4Literal(hostname);
+  if (ipv4) {
+    return isPrivateIpv4(ipv4);
+  }
+  const ipv6 = parseIpv6Literal(hostname);
+  if (!ipv6) {
+    return false;
+  }
+  // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d) literals carry
+  // an IPv4 destination, so they are unwrapped and judged as IPv4.
+  const low = ipv6[5] ?? 0;
+  if (
+    ipv6.slice(0, 5).every((piece) => piece === 0) &&
+    (low === 0xffff || low === 0)
+  ) {
+    const mapped = ipv6[6] ?? 0;
+    const trailing = ipv6[7] ?? 0;
+    return isPrivateIpv4([
+      mapped >> 8,
+      mapped & 0xff,
+      trailing >> 8,
+      trailing & 0xff,
+    ]);
+  }
+  const top = ipv6[0] ?? 0;
+  return (
+    (top & 0xfe00) === 0xfc00 || // fc00::/7 unique-local
+    (top & 0xffc0) === 0xfe80 || // fe80::/10 link-local
+    (top & 0xff00) === 0xff00 // ff00::/8 multicast
+  );
 }
 
 /**
@@ -285,8 +554,13 @@ export function normalizePairingBaseUrl(value: string): string {
 
 /**
  * Resolve an address to the public https base URL to advertise in a pairing
- * challenge, or report why it can't be used. Loopback and non-https links are
- * refused with a specific reason callers turn into their own guidance.
+ * challenge, or report why it can't be used. Loopback, private-network IP
+ * literals, and non-https links are refused with a specific reason callers
+ * turn into their own guidance.
+ *
+ * Hosts POST to this address during pairing, so the refusals are the SSRF
+ * containment for every pairing surface. See
+ * {@link isPrivateNetworkPublicUrl} for why resolved addresses are left alone.
  */
 export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   let normalized: string;
@@ -298,6 +572,9 @@ export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
   if (isLoopbackPublicUrl(normalized)) {
     return { ok: false, reason: "loopback" };
   }
+  if (isPrivateNetworkPublicUrl(normalized)) {
+    return { ok: false, reason: "private-address" };
+  }
   if (isTunnelProviderWebsiteUrl(normalized)) {
     return { ok: false, reason: "service-website" };
   }
@@ -324,3 +601,216 @@ export function buildRemoteWebPairingUrl(
   }).toString();
   return url.toString();
 }
+
+/**
+ * Base that makes a relative pairing link parseable. Only the query and
+ * fragment are read off the result, so it never reaches a caller.
+ */
+const RELATIVE_PAIRING_LINK_BASE = "https://pairing.invalid";
+
+/** The device/user codes a pairing link can carry. */
+export interface RemoteWebPairingParams {
+  deviceCode: string | null;
+  userCode: string | null;
+}
+
+function firstParam(
+  params: URLSearchParams,
+  ...names: string[]
+): string | null {
+  for (const name of names) {
+    const value = params.get(name)?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Query parameters merged with fragment parameters, query winning on a clash.
+ * Pairing links carry the device code in the fragment so it never reaches the
+ * wire, but hand-assembled links put it in the query.
+ */
+function pairingLinkParams(url: URL): URLSearchParams {
+  const merged = new URLSearchParams(url.search);
+  const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+  for (const [key, value] of new URLSearchParams(hash)) {
+    if (!merged.has(key)) {
+      merged.set(key, value);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Read the pairing codes off a link, accepting either casing (`device_code` /
+ * `deviceCode`) from either the query string or the fragment. Relative values
+ * are accepted so a router can pass `pathname + search + hash` straight in.
+ */
+export function parseRemoteWebPairingParams(
+  value: string | URL,
+): RemoteWebPairingParams {
+  const url =
+    typeof value === "string"
+      ? new URL(value, RELATIVE_PAIRING_LINK_BASE)
+      : value;
+  const params = pairingLinkParams(url);
+  return {
+    deviceCode: firstParam(params, "deviceCode", "device_code"),
+    userCode: firstParam(params, "userCode", "user_code"),
+  };
+}
+
+/** Outcome of {@link parsePairingAddress}. */
+export type ParsePairingAddressResult =
+  | { ok: true; publicBaseUrl: string; deviceCode: string | null }
+  | { ok: false; reason: PublicBaseUrlRejection };
+
+/**
+ * The inverse of {@link buildRemoteWebPairingUrl}: what a pasted pairing
+ * address means. A full pairing link yields its base plus the device code it
+ * carries; a bare `https://host` address yields a null device code, leaving
+ * the caller to mint its own challenge. The base goes through
+ * {@link resolvePublicBaseUrl}, so loopback, private-network literals,
+ * non-https, and tunnel-vendor websites are refused with the same reasons
+ * every other pairing surface reports.
+ */
+export function parsePairingAddress(raw: string): ParsePairingAddressResult {
+  const resolved = resolvePublicBaseUrl(raw);
+  if (!resolved.ok) {
+    return resolved;
+  }
+  return {
+    ok: true,
+    publicBaseUrl: resolved.url,
+    deviceCode: parseRemoteWebPairingParams(raw).deviceCode,
+  };
+}
+
+/**
+ * What a pairing attempt failed on, for callers picking recovery copy. Every
+ * pairing surface reports one of these: the host-side sessions in
+ * `@vellumai/local-mode`, the Electron bridge, the desktop connect dialog, and
+ * the `vellum connect import` CLI.
+ */
+export type PairingFailureReason =
+  /** The pasted address is not a usable assistant address. */
+  | "invalid-address"
+  /** No live session for this handle: it was cancelled or never existed. */
+  | "unknown-session"
+  /** The device code expired, was denied, or was already spent. */
+  | "expired"
+  /** The assistant could not be reached. */
+  | "unreachable"
+  /**
+   * The assistant refused the request with a status that left the device code
+   * exchangeable, so the same session is worth another attempt.
+   */
+  | "gateway-retryable"
+  /**
+   * The assistant answered, but with a reply this device cannot use. The code
+   * behind it is spent or unknowable, so the attempt is settled.
+   */
+  | "gateway"
+  /** The credentials arrived, but registering them locally was refused. */
+  | "import"
+  /**
+   * The local destination was refused BEFORE the exchange, so the one-time
+   * code is untouched and the session is still pollable. Only a caller that
+   * changes what it asked for (a different `name`) can get past it, so it is
+   * not worth another identical attempt.
+   */
+  | "import-precheck";
+
+/**
+ * Every reason, mapped to whether another attempt against the same session can
+ * still succeed. Two classes leave the device code exchangeable host-side:
+ *
+ * - `unreachable`, the transport class (a thrown fetch, a timeout, a refused
+ *   redirect, a body that errored mid-stream). Nothing reached the assistant,
+ *   so the session and the code are untouched.
+ * - `gateway-retryable`, a non-200 the assistant answered with. The gateway
+ *   releases the challenge before a repairable failure (a transient error, or
+ *   the `GUARDIAN_REPAIR_REQUIRED` 503), so the same code stays exchangeable.
+ *
+ * Everything else ends the attempt. `invalid-address` and `unknown-session`
+ * cannot resolve by waiting; `expired` and `import` mean the one-time code is
+ * already spent; `gateway` means the assistant answered with something this
+ * device cannot use (an over-cap body, credentials it cannot persist, a 200
+ * that is not a pairing reply), past which the code is spent rather than
+ * released; and `import-precheck` refused the local destination before the
+ * exchange, so an identical attempt is refused identically.
+ *
+ * `import-precheck` is the one of those that leaves the SESSION alive, which
+ * is a separate question from whether to retry: see
+ * {@link pairingSessionSurvives}.
+ *
+ * The `satisfies` clause keeps the map exhaustive, so a new reason does not
+ * compile until it is classified here.
+ */
+const PAIRING_REASON_RETRYABLE = {
+  "invalid-address": false,
+  "unknown-session": false,
+  expired: false,
+  unreachable: true,
+  "gateway-retryable": true,
+  gateway: false,
+  import: false,
+  "import-precheck": false,
+} satisfies Record<PairingFailureReason, boolean>;
+
+/** The reasons {@link isRetryablePairingReason} accepts. */
+export const RETRYABLE_PAIRING_REASONS: ReadonlySet<PairingFailureReason> =
+  new Set(
+    (Object.keys(PAIRING_REASON_RETRYABLE) as PairingFailureReason[]).filter(
+      (reason) => PAIRING_REASON_RETRYABLE[reason],
+    ),
+  );
+
+/**
+ * Whether a refused pairing step is worth another attempt. An unlabelled
+ * failure reads as settled, so a host too old to name a reason ends the
+ * attempt rather than being spun against until the code expires.
+ */
+export function isRetryablePairingReason(
+  reason: PairingFailureReason | null | undefined,
+): boolean {
+  return reason != null && RETRYABLE_PAIRING_REASONS.has(reason);
+}
+
+/**
+ * Every reason, mapped to whether the pairing session it came from is still
+ * live host-side. A caller holding the handle reads this to decide whether to
+ * release the session: releasing a live one throws away a device code that is
+ * still good and costs the user a fresh pairing link.
+ *
+ * This is deliberately NOT the retryable map. `import-precheck` is the reason
+ * the two disagree on: nothing was spent and the same handle still polls, but
+ * only once the caller changes the name it asked for, so a blind retry is
+ * futile while dropping the session is destructive.
+ *
+ * `invalid-address` never had a session to begin with, so it reads false the
+ * same way a dead one does: there is nothing to hold onto either way.
+ */
+const PAIRING_REASON_SESSION_LIVE = {
+  "invalid-address": false,
+  "unknown-session": false,
+  expired: false,
+  unreachable: true,
+  "gateway-retryable": true,
+  gateway: false,
+  import: false,
+  "import-precheck": true,
+} satisfies Record<PairingFailureReason, boolean>;
+
+/**
+ * Whether the session behind a refused pairing step is still pollable. An
+ * unlabelled failure reads as settled, so a host too old to name a reason has
+ * its session released rather than left to time out.
+ */
+export function pairingSessionSurvives(
+  reason: PairingFailureReason | null | undefined,
+): boolean {
+  return reason != null && PAIRING_REASON_SESSION_LIVE[reason] === true;
+}