@vellumai/cli 0.10.11-dev.202607222325.35fc367 → 0.10.11-dev.202607230140.b414d01

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

@@ -100,3 +100,93 @@ export interface RemoteWebPairingTokenApprovedResponse {
 export type RemoteWebPairingTokenResponse =
   | RemoteWebPairingTokenPendingResponse
   | RemoteWebPairingTokenApprovedResponse;
+
+// ── Shared pairing URL helpers ──────────────────────────────────────────────
+//
+// Every surface that mints a pairing (the `vellum pair --qr` 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.
+
+/** Why a public base URL can't be advertised in a pairing challenge. */
+export type PublicBaseUrlRejection = "unparseable" | "loopback" | "non-https";
+
+export type PublicBaseUrlResult =
+  | { ok: true; url: string }
+  | { ok: false; reason: PublicBaseUrlRejection };
+
+/**
+ * A loopback URL — `localhost`, `[::1]`, or `127.x.x.x`. A pairing link that
+ * encodes a loopback address is unreachable from the scanning device.
+ */
+export function isLoopbackPublicUrl(url: string): boolean {
+  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)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize an address to the public base a scanning device opens:
+ * query/hash stripped, the `assistant` path segment (and everything after it)
+ * removed so a pasted pair-page URL collapses to its base, and trailing
+ * slashes trimmed. Throws if the value is not a parseable URL.
+ */
+export function normalizePublicBaseUrl(value: string): string {
+  const url = new URL(value);
+  url.search = "";
+  url.hash = "";
+  const parts = url.pathname.split("/").filter(Boolean);
+  const assistantIndex = parts.indexOf("assistant");
+  if (assistantIndex >= 0) {
+    parts.splice(assistantIndex);
+  }
+  url.pathname = parts.length ? `/${parts.join("/")}` : "/";
+  return url.toString().replace(/\/+$/, "");
+}
+
+/**
+ * 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.
+ */
+export function resolvePublicBaseUrl(raw: string): PublicBaseUrlResult {
+  let normalized: string;
+  try {
+    normalized = normalizePublicBaseUrl(raw);
+  } catch {
+    return { ok: false, reason: "unparseable" };
+  }
+  if (isLoopbackPublicUrl(normalized)) {
+    return { ok: false, reason: "loopback" };
+  }
+  if (new URL(normalized).protocol !== "https:") {
+    return { ok: false, reason: "non-https" };
+  }
+  return { ok: true, url: normalized };
+}
+
+/**
+ * The scannable pair URL: the challenge's verification URI with the device
+ * code carried in the fragment (`#device_code=…`), matching what the pair
+ * page reads on load. Fragments never reach the wire.
+ */
+export function buildRemoteWebPairingUrl(
+  challenge: Pick<
+    RemoteWebPairingChallengeResponse,
+    "verificationUri" | "deviceCode"
+  >,
+): string {
+  const url = new URL(challenge.verificationUri);
+  url.hash = new URLSearchParams({
+    device_code: challenge.deviceCode,
+  }).toString();
+  return url.toString();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607222325.35fc367",
+  "version": "0.10.11-dev.202607230140.b414d01",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/commands/pair.ts

@@ -15,11 +15,15 @@ import { nanoid } from "nanoid";
 // error-correction level off `this`, so a destructured import renders nothing.
 import qrcodeTerminal from "qrcode-terminal";
 
-import type {
-  RemoteWebPairingChallengeRequest,
-  RemoteWebPairingChallengeResponse,
-  RemoteWebPairingVerificationRequest,
-  RemoteWebPairingVerificationResponse,
+import {
+  buildRemoteWebPairingUrl,
+  normalizePublicBaseUrl,
+  resolvePublicBaseUrl,
+  type PublicBaseUrlRejection,
+  type RemoteWebPairingChallengeRequest,
+  type RemoteWebPairingChallengeResponse,
+  type RemoteWebPairingVerificationRequest,
+  type RemoteWebPairingVerificationResponse,
 } from "@vellumai/service-contracts/remote-web-pairing";
 
 import { extractFlag } from "../lib/arg-utils.js";
@@ -127,29 +131,6 @@ interface PairResponse {
   refreshAfter?: string;
 }
 
-function normalizePublicBaseUrl(value: string): string {
-  const url = new URL(value);
-  url.search = "";
-  url.hash = "";
-  const parts = url.pathname.split("/").filter(Boolean);
-  const assistantIndex = parts.indexOf("assistant");
-  if (assistantIndex >= 0) {
-    parts.splice(assistantIndex);
-  }
-  url.pathname = parts.length ? `/${parts.join("/")}` : "/";
-  return url.toString().replace(/\/+$/, "");
-}
-
-function buildRemoteWebPairingUrl(
-  challenge: RemoteWebPairingChallengeResponse,
-): string {
-  const url = new URL(challenge.verificationUri);
-  url.hash = new URLSearchParams({
-    device_code: challenge.deviceCode,
-  }).toString();
-  return url.toString();
-}
-
 /** Default URL scheme registered by production builds of the iOS app. */
 const DEFAULT_APP_CONNECT_SCHEME = "vellum-assistant";
 
@@ -167,35 +148,6 @@ export function buildAppConnectUrl(
   return `${scheme}://connect?${params.toString()}`;
 }
 
-type QrPublicBaseUrlFailureReason = "unparseable" | "loopback" | "non-https";
-
-type QrPublicBaseUrlResult =
-  | { ok: true; url: string }
-  | { ok: false; reason: QrPublicBaseUrlFailureReason };
-
-/**
- * Normalize the advertised URL to the public https origin a scanning phone can
- * open, or report why it isn't internet-reachable. Stricter than the copy-paste
- * bundle path's loopback guard: a QR that encodes a loopback or plain-http link
- * is unusable from another device, so both are refused. The failure reason is
- * returned so the caller can emit an accurate message per case.
- */
-function resolveQrPublicBaseUrl(advertisedUrl: string): QrPublicBaseUrlResult {
-  let normalized: string;
-  try {
-    normalized = normalizePublicBaseUrl(advertisedUrl);
-  } catch {
-    return { ok: false, reason: "unparseable" };
-  }
-  if (isLoopbackUrl(normalized)) {
-    return { ok: false, reason: "loopback" };
-  }
-  if (new URL(normalized).protocol !== "https:") {
-    return { ok: false, reason: "non-https" };
-  }
-  return { ok: true, url: normalized };
-}
-
 /**
  * POST a JSON body to a loopback gateway route, exiting with a clear message
  * when the gateway is unreachable or answers non-2xx. Every pairing subcommand
@@ -493,9 +445,9 @@ export async function pair(): Promise<void> {
   if (qrPairing) {
     // Validate the public URL before any network call — a QR that encodes a
     // loopback or plain-http link is unscannable from another device.
-    const qrResult = resolveQrPublicBaseUrl(advertisedUrl);
+    const qrResult = resolvePublicBaseUrl(advertisedUrl);
     if (!qrResult.ok) {
-      const detailByReason: Record<QrPublicBaseUrlFailureReason, string> = {
+      const detailByReason: Record<PublicBaseUrlRejection, string> = {
         unparseable: `${advertisedUrl} isn't a valid URL`,
         loopback: `${advertisedUrl} is a loopback address`,
         "non-https": `${advertisedUrl} is not https`,