@tokenoftrust/cli 2.0.11 → 2.0.14

package/src/oauth.mjs

@@ -26,6 +26,7 @@ import http from "node:http";
 import crypto from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { openBrowser } from "./open.mjs";
+import { CliDiagnosticError, sanitizeDiagnosticText } from "./diagnostics.mjs";
 
 const CLIENT_NAME = "Token of Trust CLI (tot)";
 const SCOPE = "mcp offline_access"; // offline_access → the refresh token
@@ -34,6 +35,87 @@ const SCOPE = "mcp offline_access"; // offline_access → the refresh token
 // ephemeral port that the MCP matches port-agnostically.
 const LOOPBACK_REDIRECT = "http://127.0.0.1/callback";
 
+function oauthTraceId() {
+  return crypto.randomUUID().replaceAll("-", "");
+}
+
+async function oauthJson(url, init, operation, fetchImpl) {
+  const traceId = oauthTraceId();
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      ...init,
+      headers: { ...(init?.headers || {}), "X-Trace-Id": traceId },
+    });
+  } catch (cause) {
+    throw new CliDiagnosticError(`${operation} failed before a response arrived`, {
+      operation, category: "network", message: cause?.message || String(cause), traceId,
+    }, { cause });
+  }
+  const returnedTraceId = res.headers?.get?.("x-trace-id") || traceId;
+  const requestId = res.headers?.get?.("x-request-id") || returnedTraceId;
+  const contentType = res.headers?.get?.("content-type") || "";
+  let text;
+  let body;
+  let parseError;
+  try {
+    if (typeof res.text === "function") {
+      text = await res.text();
+      body = text ? JSON.parse(text) : null;
+    } else {
+      body = await res.json();
+      text = JSON.stringify(body);
+    }
+  } catch (cause) {
+    parseError = cause;
+    body = null;
+  }
+  const responseBytes = text === undefined ? undefined : Buffer.byteLength(text);
+  if (res.ok && parseError) {
+    throw new CliDiagnosticError(`${operation} returned malformed JSON`, {
+      operation, category: "malformed_response", httpStatus: res.status,
+      traceId: returnedTraceId, requestId, contentType, responseBytes,
+    }, { cause: parseError });
+  }
+  if (res.ok && body === null) {
+    throw new CliDiagnosticError(`${operation} returned an empty response`, {
+      operation, category: "empty_response", httpStatus: res.status,
+      traceId: returnedTraceId, requestId, contentType, responseBytes,
+    });
+  }
+  body ||= {};
+  return {
+    res,
+    body,
+    context: {
+      operation,
+      httpStatus: res.status,
+      statusText: res.statusText,
+      serverCode: typeof body?.error === "string" ? body.error : undefined,
+      message: sanitizeDiagnosticText(body?.error_description || body?.error || "", 300),
+      traceId: returnedTraceId,
+      requestId,
+      contentType,
+      responseBytes: responseBytes ?? 0,
+    },
+  };
+}
+
+function oauthFailure(message, context) {
+  return new CliDiagnosticError(message, {
+    ...context,
+    category: context.serverCode ? "oauth" : `http_${context.httpStatus}`,
+  });
+}
+
+function oauthShapeFailure(message, context) {
+  return new CliDiagnosticError(message, {
+    ...context,
+    category: "malformed_response",
+    message,
+  });
+}
+
 const b64url = (buf) =>
   buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 
@@ -63,11 +145,12 @@ export function randomState() {
 export async function discoverMetadata(mcpUrl, fetchImpl = fetch) {
   const root = String(mcpUrl).replace(/\/+$/, "");
   const url = `${root}/.well-known/oauth-authorization-server`;
-  const res = await fetchImpl(url, { headers: { Accept: "application/json" } });
-  if (!res.ok) throw new Error(`could not read the MCP's OAuth metadata (HTTP ${res.status} at ${url})`);
-  const meta = await res.json();
+  const { res, body: meta, context } = await oauthJson(
+    url, { headers: { Accept: "application/json" } }, "oauth_metadata", fetchImpl,
+  );
+  if (!res.ok) throw oauthFailure(`could not read the MCP's OAuth metadata (HTTP ${res.status} at ${url})`, context);
   if (!meta?.authorization_endpoint || !meta?.token_endpoint) {
-    throw new Error("the MCP's OAuth metadata is missing authorization/token endpoints");
+    throw oauthShapeFailure("the MCP's OAuth metadata is missing authorization/token endpoints", context);
   }
   return meta;
 }
@@ -79,7 +162,7 @@ export async function registerClient(
   fetchImpl = fetch,
 ) {
   if (!registrationEndpoint) throw new Error("the MCP does not advertise a registration endpoint");
-  const res = await fetchImpl(registrationEndpoint, {
+  const { res, body, context } = await oauthJson(registrationEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
@@ -97,10 +180,9 @@ export async function registerClient(
       token_endpoint_auth_method: "none",
       scope: SCOPE,
     }),
-  });
-  if (!res.ok) throw new Error(`client registration failed (HTTP ${res.status})`);
-  const body = await res.json();
-  if (!body?.client_id) throw new Error("client registration returned no client_id");
+  }, "oauth_client_registration", fetchImpl);
+  if (!res.ok) throw oauthFailure(`client registration failed (HTTP ${res.status})`, context);
+  if (!body?.client_id) throw oauthShapeFailure("client registration returned no client_id", context);
   return body.client_id;
 }
 
@@ -121,22 +203,19 @@ export function buildAuthorizeUrl(authorizationEndpoint, {
 }
 
 async function tokenRequest(tokenEndpoint, params, fetchImpl) {
-  const res = await fetchImpl(tokenEndpoint, {
+  const { res, body, context } = await oauthJson(tokenEndpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-www-form-urlencoded",
       Accept: "application/json",
     },
     body: new URLSearchParams(params).toString(),
-  });
-  const text = await res.text();
-  let body;
-  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  }, "oauth_token", fetchImpl);
   if (!res.ok) {
     const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
-    throw new Error(`token request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+    throw oauthFailure(`token request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`, context);
   }
-  if (!body.access_token) throw new Error("token endpoint returned no access_token");
+  if (!body.access_token) throw oauthShapeFailure("token endpoint returned no access_token", context);
   return body;
 }
 
@@ -327,7 +406,7 @@ export function deviceEndpoint(mcpUrl, meta, path) {
  * response { device_code, user_fingerprint, interval, expires_in }. Throws a clear,
  * non-stack error on rejection (an expired / already-used handle). */
 export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientId, challenge }, fetchImpl = fetch) {
-  const res = await fetchImpl(attachEndpoint, {
+  const { res, body, context } = await oauthJson(attachEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/json", Accept: "application/json" },
     body: JSON.stringify({
@@ -336,16 +415,13 @@ export async function attachRendezvous(attachEndpoint, { rendezvousCode, clientI
       code_challenge: challenge,
       code_challenge_method: "S256",
     }),
-  });
-  const text = await res.text();
-  let body;
-  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  }, "oauth_rendezvous_attach", fetchImpl);
   if (!res.ok) {
     const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
-    throw new Error(`your sign-in code was not accepted (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+    throw oauthFailure(`your sign-in code was not accepted (HTTP ${res.status}${detail ? `: ${detail}` : ""})`, context);
   }
   if (!body.device_code || !body.user_fingerprint) {
-    throw new Error("the attach endpoint returned no device_code/fingerprint");
+    throw oauthShapeFailure("the attach endpoint returned no device_code/fingerprint", context);
   }
   return body;
 }
@@ -417,20 +493,17 @@ export async function rendezvousLoginFlow({
  *   verification_uri_complete?, expires_in, interval}>}
  */
 export async function deviceAuthorize(deviceAuthorizationEndpoint, { clientId, scope = SCOPE }, fetchImpl = fetch) {
-  const res = await fetchImpl(deviceAuthorizationEndpoint, {
+  const { res, body, context } = await oauthJson(deviceAuthorizationEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
     body: new URLSearchParams({ client_id: clientId, scope }).toString(),
-  });
-  const text = await res.text();
-  let body;
-  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  }, "oauth_device_authorization", fetchImpl);
   if (!res.ok) {
     const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
-    throw new Error(`device authorization request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+    throw oauthFailure(`device authorization request failed (HTTP ${res.status}${detail ? `: ${detail}` : ""})`, context);
   }
   if (!body.device_code || !body.user_code) {
-    throw new Error("device authorization response is missing device_code/user_code");
+    throw oauthShapeFailure("device authorization response is missing device_code/user_code", context);
   }
   return body;
 }
@@ -442,7 +515,7 @@ export async function deviceAuthorize(deviceAuthorizationEndpoint, { clientId, s
  * (with `slowDown` set) for those instead of throwing.
  */
 async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifier }, fetchImpl) {
-  const res = await fetchImpl(tokenEndpoint, {
+  const { res, body, context } = await oauthJson(tokenEndpoint, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
     body: new URLSearchParams({
@@ -454,19 +527,16 @@ async function deviceTokenPoll(tokenEndpoint, { deviceCode, clientId, codeVerifi
       // Absent for the plain RFC 8628 device flow (no PKCE) — omitted then.
       ...(codeVerifier ? { code_verifier: codeVerifier } : {}),
     }).toString(),
-  });
-  const text = await res.text();
-  let body;
-  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  }, "oauth_device_token", fetchImpl);
   if (res.ok) {
-    if (!body.access_token) throw new Error("token endpoint returned no access_token");
+    if (!body.access_token) throw oauthShapeFailure("token endpoint returned no access_token", context);
     return { pending: false, token: body };
   }
   if (body.error === "authorization_pending") return { pending: true, slowDown: false };
   if (body.error === "slow_down") return { pending: true, slowDown: true };
   const reason = body.error === "access_denied" ? "was denied" : body.error === "expired_token" ? "code expired" : "failed";
   const detail = body.error_description ? ` — ${body.error_description}` : "";
-  throw new Error(`sign-in ${reason}${detail}`);
+  throw oauthFailure(`sign-in ${reason}${detail}`, context);
 }
 
 /**

package/src/open.mjs

@@ -17,19 +17,34 @@ import { setTimeout as delay } from "node:timers/promises";
  * Mirror of scripts/dev/port-check.mjs (separate package — kept dependency-free).
  * @param {number} port @returns {Promise<boolean>}
  */
-export function isPortFree(port) {
+/**
+ * @param {number} port
+ * @param {string | undefined} [host]
+ * @param {boolean} [unsupportedIsFree]
+ */
+function canBind(port, host = undefined, unsupportedIsFree = false) {
   return new Promise((resolve) => {
     const srv = net.createServer();
-    srv.once("error", () => resolve(false));
+    srv.once("error", (error) => {
+      const code = /** @type {NodeJS.ErrnoException} */ (error).code;
+      const unsupported = code === "EAFNOSUPPORT" || code === "EADDRNOTAVAIL";
+      resolve(unsupportedIsFree && unsupported);
+    });
     srv.once("listening", () => srv.close(() => resolve(true)));
     try {
-      srv.listen(port);
+      srv.listen({ port, ...(host ? { host } : {}) });
     } catch {
       resolve(false);
     }
   });
 }
 
+export async function isPortFree(port) {
+  if (!(await canBind(port))) return false;
+  if (!(await canBind(port, "127.0.0.1"))) return false;
+  return canBind(port, "::1", true);
+}
+
 /**
  * First free port at or after `preferred`. Lets the CLI derive the URL it opens +
  * polls from the SAME port the runner will bind — Vite's strictPort is off, so a