@mathismeadows/roamer-device-auth 1.1.2 → 1.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@mathismeadows/roamer-device-auth",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
-  "description": "AUTH-25: server-mediated device authorization flow + stdio<->HTTP MCP proxy for Roamer MCP. Used by roamer-bridge.sh for every OS and every default browser (no more Safari-specific branching, AUTH-14) — Cloudflare Access's Managed OAuth has no device-code grant of its own, so RoamerMcp's server implements it and this script talks to that instead of Entra directly.",
+  "description": "AUTH-14/AUTH-25: stdio<->HTTP MCP proxy for Roamer MCP with two auth mechanisms, chosen per-machine by default-browser detection. Safari-default machines use a server-mediated device authorization flow (AUTH-25) since Safari's HTTPS-Only Mode blocks a loopback redirect; every other machine uses a standard direct loopback redirect against Cloudflare Access Managed OAuth instead.",
   "bin": {
     "roamer-device-auth": "./roamer-device-auth.mjs"
   },

package/roamer-device-auth.mjs

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
-// Roamer MCP — server-mediated device authorization flow (AUTH-25).
+// Roamer MCP — server-mediated device authorization flow (AUTH-25), used only for
+// Safari-default clients since AUTH-14's 2026-08-25 revival. Non-Safari clients (and any
+// OS where Safari isn't an option, e.g. Windows/Linux) instead use a standard direct
+// loopback-redirect flow against Cloudflare Access Managed OAuth — see
+// getValidTokensLoopback() below — removing the device-code confirmation screen AUTH-25's
+// prior unified design imposed on every client, Safari or not.
 //
-// Replaces both the old mcp-remote redirect flow (AUTH-11) and this script's own previous
-// Entra-direct device-code flow (AUTH-14) — a single mechanism for every OS and every
-// default browser now, including Safari, which blocked the old loopback-redirect approach
-// entirely (WebKitErrorDomain:305, confirmed live 2026-08-20). Cloudflare Access's Managed
-// OAuth has no device-code grant of its own (confirmed live the same day — device
-// authentication is not supported for MCP portals per Cloudflare's own docs), so
-// RoamerMcp's server implements the RFC 8628 shape itself, brokering a real Authorization
-// Code + PKCE exchange with Cloudflare server-to-server. This script only ever talks plain
-// HTTPS to RoamerMcp — no local port, no local TLS certificate, no browser-default
-// detection needed at all.
+// Why Safari still needs device-code: Safari's HTTPS-Only Mode unconditionally blocks the
+// loopback flow's plain http:// callback (WebKitErrorDomain:305, confirmed live
+// 2026-08-20), and Cloudflare Access's Managed OAuth has no device-code grant of its own
+// (confirmed live the same day — device authentication is not supported for MCP portals
+// per Cloudflare's own docs), so RoamerMcp's server implements the RFC 8628 shape itself
+// for that case, brokering a real Authorization Code + PKCE exchange with Cloudflare
+// server-to-server. detectDefaultBrowser() below decides which path a given machine takes.
 //
 // AUTH-24: this is the publishable source for the @mathismeadows/roamer-device-auth npm
 // package — roamer-bridge.sh (here and in roamer-mcp-plugin) invokes the published,
@@ -19,12 +21,22 @@
 // stdout is reserved for the JSON-RPC protocol channel; all logging goes to stderr.
 
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  discoverOAuthServerInfo,
+  extractWWWAuthenticateParams,
+  registerClient,
+  startAuthorization,
+  exchangeAuthorization,
+  refreshAuthorization,
+} from "@modelcontextprotocol/sdk/client/auth.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { createServer } from "node:http";
 import qrcode from "qrcode-terminal";
 
 const execFileAsync = promisify(execFile);
@@ -36,6 +48,13 @@ const CACHE_DIR = join(homedir(), ".mcp-auth-device");
 const CACHE_FILE = join(CACHE_DIR, "roamer_tokens.json");
 const PENDING_FILE = join(CACHE_DIR, "roamer_pending.json");
 
+// AUTH-14: the loopback flow's own independent cache — never assumed interchangeable with
+// the device-code cache above, matching this file's existing precedent of not trusting a
+// differently-obtained cache just because it happens to share field names (see
+// CACHE_VERSION's own comment on the mcp-remote-era predecessor of that exact mistake).
+const LOOPBACK_TOKENS_FILE = join(CACHE_DIR, "roamer_loopback_tokens.json");
+const LOOPBACK_CLIENT_FILE = join(CACHE_DIR, "roamer_loopback_client.json");
+
 // Bumped whenever the cached shape changes meaningfully. A cache written by a prior
 // mechanism (e.g. the retired Entra-direct flow, AUTH-11/14) happens to share field names
 // (access_token, expires_in, obtained_at) with this format, so a plain presence check isn't
@@ -91,6 +110,69 @@ function clearCachedTokens() {
   return writeFile(CACHE_FILE, "{}", { mode: 0o600 }).catch(() => {});
 }
 
+// AUTH-14: loopback-flow cache — a brand-new file, never previously used by any other
+// mechanism, so (unlike CACHE_FILE above) there's no prior-format collision risk to guard
+// against with a version stamp.
+async function readLoopbackTokens() {
+  try {
+    const tokens = JSON.parse(await readFile(LOOPBACK_TOKENS_FILE, "utf8"));
+    return tokens?.access_token ? tokens : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeLoopbackTokens(tokens) {
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(LOOPBACK_TOKENS_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+}
+
+function clearLoopbackTokens() {
+  return writeFile(LOOPBACK_TOKENS_FILE, "{}", { mode: 0o600 }).catch(() => {});
+}
+
+// DCR'd client registration is reused across runs — Cloudflare's registration_endpoint has
+// no reason to be hit on every single sign-in, only the first one (or after a reset).
+async function readLoopbackClientInfo() {
+  try {
+    const info = JSON.parse(await readFile(LOOPBACK_CLIENT_FILE, "utf8"));
+    return info?.client_id ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeLoopbackClientInfo(info) {
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(LOOPBACK_CLIENT_FILE, JSON.stringify(info, null, 2), { mode: 0o600 });
+}
+
+// AUTH-14: which auth mechanism a given machine uses. Safari-default clients (macOS only —
+// Safari isn't an option elsewhere) take the device-code path above, since Safari's
+// HTTPS-Only Mode blocks the loopback callback outright. Everything else, including every
+// non-macOS platform (no Launch Services plist to query, so this always reports "unknown"
+// there — correctly falling through to the loopback path), takes the lighter direct
+// redirect. ROAMER_MCP_AUTH_FLOW overrides detection entirely — used by this file's own
+// test suite to pin a deterministic path regardless of the CI machine's real OS/browser.
+async function detectDefaultBrowser() {
+  const override = process.env.ROAMER_MCP_AUTH_FLOW;
+  if (override === "device-code") return "com.apple.safari";
+  if (override === "loopback") return "unknown";
+
+  try {
+    const plistPath = join(
+      homedir(),
+      "Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist",
+    );
+    const { stdout } = await execFileAsync("plutil", ["-convert", "json", "-o", "-", plistPath]);
+    const data = JSON.parse(stdout);
+    const handler = (data.LSHandlers ?? []).find((h) => h.LSHandlerURLScheme === "http");
+    return handler?.LSHandlerRoleAll ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // Claude Code (or any MCP host) may kill this process and respawn a fresh one if it doesn't
 // see a stdio handshake within its own connect timeout — and the interactive device flow
 // (dialog -> browser -> Cloudflare's consent screen -> poll) routinely takes longer than a
@@ -258,34 +340,239 @@ async function doGetValidTokens(forceRefresh) {
   }
 }
 
-async function main() {
-  let tokens = await getValidTokens();
+// AUTH-14: fixed, well-known port for the loopback callback — Cloudflare's DCR'd client
+// registration is persisted and reused across every future sign-in (see
+// readLoopbackClientInfo), so the redirect_uri baked into that registration has to stay
+// stable across runs. A fixed port sidesteps re-registering on every single interactive
+// sign-in; the tradeoff (a port-in-use conflict is possible, if rare) is the same one this
+// project's original AUTH-11/AUTH-14 mcp-remote-based flow already lived with for months.
+const LOOPBACK_PORT = Number(process.env.ROAMER_MCP_OAUTH_PORT ?? 38271);
+const LOOPBACK_REDIRECT_URI = `http://127.0.0.1:${LOOPBACK_PORT}/callback`;
+
+async function refreshLoopbackTokens(refreshToken, serverInfo, clientInformation) {
+  const fresh = await refreshAuthorization(serverInfo.authorizationServerUrl, {
+    metadata: serverInfo.authorizationServerMetadata,
+    clientInformation,
+    refreshToken,
+  });
+  return { ...fresh, refresh_token: fresh.refresh_token ?? refreshToken };
+}
 
-  const transport = new StreamableHTTPClientTransport(new URL(ROAMER_MCP_URL), {
-    requestInit: {
-      get headers() {
-        return { Authorization: `Bearer ${tokens.access_token}` };
+function waitForLoopbackCallback(server) {
+  return new Promise((resolve, reject) => {
+    server.on("request", (req, res) => {
+      const url = new URL(req.url, LOOPBACK_REDIRECT_URI);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        error
+          ? `<html><body>Sign-in failed: ${error}. You can close this window.</body></html>`
+          : `<html><body>Signed in to Roamer MCP. You can close this window.</body></html>`,
+      );
+      if (error) reject(new Error(`Loopback authorization failed: ${error}`));
+      else if (code) resolve(code);
+      else reject(new Error("Loopback callback had neither code nor error"));
+    });
+  });
+}
+
+// AUTH-14: must follow the real WWW-Authenticate resource_metadata hint from a live 401,
+// not RoamerMcp's own default .well-known/oauth-protected-resource document, which still
+// mirrors Entra directly and would send a standards-compliant client to the wrong
+// authorization server entirely — confirmed live 2026-08-26 (see thread
+// SAFARI-DEVICE-CODE-UX; the stale default document itself is a separate, lower-priority
+// gap tracked as AUTH-27, not fixed by this flow following the correct header instead).
+async function discoverLoopbackServerInfo() {
+  const probe = await fetch(ROAMER_MCP_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: "{}",
+  });
+  const { resourceMetadataUrl } = extractWWWAuthenticateParams(probe);
+  await probe.body?.cancel?.();
+  return discoverOAuthServerInfo(ROAMER_MCP_URL, { resourceMetadataUrl });
+}
+
+// Same single-flight guard shape as getValidTokens above, kept independent since only one
+// of the two mechanisms is ever active in a given process (see detectDefaultBrowser).
+let inFlightLoopbackTokens = null;
+
+function getValidTokensLoopback(forceRefresh = false) {
+  if (inFlightLoopbackTokens) return inFlightLoopbackTokens;
+  inFlightLoopbackTokens = doGetValidTokensLoopback(forceRefresh).finally(() => {
+    inFlightLoopbackTokens = null;
+  });
+  return inFlightLoopbackTokens;
+}
+
+async function doGetValidTokensLoopback(forceRefresh) {
+  let tokens = forceRefresh ? null : await readLoopbackTokens();
+
+  if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
+    return tokens;
+  }
+
+  const serverInfo = await discoverLoopbackServerInfo();
+  let clientInformation = await readLoopbackClientInfo();
+
+  if (!forceRefresh && tokens?.refresh_token && clientInformation) {
+    try {
+      log("Refreshing cached token...");
+      const fresh = await refreshLoopbackTokens(tokens.refresh_token, serverInfo, clientInformation);
+      tokens = { ...fresh, obtained_at: Date.now() };
+      await writeLoopbackTokens(tokens);
+      return tokens;
+    } catch (err) {
+      log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
+    }
+  }
+
+  if (forceRefresh) await clearLoopbackTokens();
+
+  if (!clientInformation) {
+    log("Registering as a new OAuth client with Cloudflare...");
+    clientInformation = await registerClient(serverInfo.authorizationServerUrl, {
+      metadata: serverInfo.authorizationServerMetadata,
+      clientMetadata: {
+        client_name: "Roamer MCP (stdio bridge)",
+        redirect_uris: [LOOPBACK_REDIRECT_URI],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
       },
-    },
+    });
+    await writeLoopbackClientInfo(clientInformation);
+  }
+
+  log("Starting sign-in...");
+  const { authorizationUrl, codeVerifier } = await startAuthorization(serverInfo.authorizationServerUrl, {
+    metadata: serverInfo.authorizationServerMetadata,
+    clientInformation,
+    redirectUrl: LOOPBACK_REDIRECT_URI,
+    // RFC 8707: Cloudflare's authorization endpoint rejects the request without this
+    // (invalid_target / "No resource parameter found") — the exact same requirement
+    // DeviceFlowService.cs already hit and fixed server-side for the device-code path
+    // (confirmed live 2026-08-21) and just reconfirmed live here 2026-08-26. Only the
+    // authorization step needs it; DeviceFlowService.cs's token/refresh calls don't
+    // reference it at all, so exchangeAuthorization/refreshAuthorization below don't either.
+    resource: new URL(ROAMER_MCP_URL),
   });
 
-  transport.onerror = (err) => {
-    log(`Transport error: ${err.message}`);
-    // Same reasoning as the send-path retry below: an auth error means whatever's cached is
-    // known-bad, so drop it now rather than let the next proactive expiresSoon() check
-    // (which only reasons about calendar time) keep handing it out.
-    if (isAuthError(err)) clearCachedTokens();
+  const server = createServer();
+  const callbackPromise = waitForLoopbackCallback(server);
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(LOOPBACK_PORT, "127.0.0.1", resolve);
+  }).catch((err) => {
+    throw new Error(
+      `Could not start the local sign-in listener on port ${LOOPBACK_PORT} (${err.message}). ` +
+        "Another roamer-device-auth process may already be signing in — wait for it to finish, " +
+        "or set ROAMER_MCP_OAUTH_PORT to a free port.",
+    );
+  });
+
+  log(`Go to ${authorizationUrl} to sign in.`);
+  try {
+    const { default: open } = await import("open");
+    await open(authorizationUrl.toString());
+  } catch {
+    // Best-effort only — the logged URL above is the fallback for any environment without a
+    // way to auto-launch a browser.
+  }
+
+  let authorizationCode;
+  try {
+    authorizationCode = await callbackPromise;
+  } finally {
+    server.close();
+  }
+
+  const fresh = await exchangeAuthorization(serverInfo.authorizationServerUrl, {
+    metadata: serverInfo.authorizationServerMetadata,
+    clientInformation,
+    authorizationCode,
+    codeVerifier,
+    redirectUri: LOOPBACK_REDIRECT_URI,
+  });
+  tokens = { ...fresh, obtained_at: Date.now() };
+  await writeLoopbackTokens(tokens);
+  log("Sign-in complete.");
+  return tokens;
+}
+
+// AUTH-28: extracted so it can run both for live traffic (post-sign-in) and for messages
+// queued while sign-in was still in progress, with identical forwarding/retry behavior.
+async function forwardLine(transport, line, getTokens, setTokens, getFreshTokens) {
+  try {
+    let tokens = getTokens();
+    if (expiresSoon(tokens)) {
+      tokens = await getFreshTokens();
+      setTokens(tokens);
+    }
+    try {
+      await transport.send(JSON.parse(line));
+    } catch (err) {
+      // Reactive invalidation: proactive expiry math can't catch everything (server-side
+      // revocation, clock skew, or an incompatible cache — see CACHE_VERSION). A real
+      // auth failure from the server is the ground truth; when we see one, invalidate
+      // whatever we're holding, force a genuinely fresh token, and retry once.
+      if (!isAuthError(err)) throw err;
+      log(`Send failed with an auth error (${err.message}) — invalidating cached token and retrying once.`);
+      tokens = await getFreshTokens(true);
+      setTokens(tokens);
+      await transport.send(JSON.parse(line));
+    }
+  } catch (err) {
+    log(`Send failed: ${err.message}`);
+  }
+}
+
+// AUTH-28: a hard sign-in failure (denied/expired device code) must tell the host exactly
+// that, per request, rather than leaving requests unanswered for the host to time out on.
+function respondWithSignInError(line, err) {
+  let id = null;
+  try {
+    id = JSON.parse(line)?.id ?? null;
+  } catch {
+    // Malformed input never had a usable id anyway — respond with null per JSON-RPC convention.
+  }
+  const response = {
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32001, message: `Roamer MCP sign-in failed: ${err.message}` },
   };
-  await transport.start();
-  log("Connected to remote server using StreamableHTTPClientTransport.");
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
 
-  // stdin/stdout <-> transport pass-through. Each stdin line is one JSON-RPC message;
-  // transport.send() delivers it, and transport.onmessage delivers whatever comes back
-  // (including server-initiated messages over the SSE half of the streamable-HTTP transport).
-  transport.onmessage = (message) => {
-    process.stdout.write(`${JSON.stringify(message)}\n`);
+async function main() {
+  // AUTH-28: stdin is read (and, until sign-in completes, queued) from the very first tick —
+  // a cold-cache device-code flow can take minutes, and the MCP host must never see this
+  // process as unresponsive/silent during that window. That silence, not the auth flow
+  // itself, is what triggers the host's connect-timeout kill/respawn (see readPendingFlow's
+  // comment above) — this fix targets the silence, not the flow's real, unavoidable duration.
+  let tokens = null;
+  let transport = null;
+  let ready = false;
+  const pendingLines = [];
+
+  const getTokens = () => tokens;
+  const setTokens = (fresh) => {
+    tokens = fresh;
   };
 
+  // AUTH-14: assigned below, only after the stdin listener is attached — forwardLine (the
+  // only consumer) never runs before `ready` flips true, which itself never happens before
+  // these are set, so deferring the assignment past the listener attach is safe and keeps
+  // AUTH-28's guarantee (listener attaches before any await) intact.
+  let getFreshTokens;
+  let clearFreshTokens;
+
   let buffer = "";
   process.stdin.setEncoding("utf8");
   process.stdin.on("data", (chunk) => {
@@ -295,40 +582,80 @@ async function main() {
       const line = buffer.slice(0, newlineIndex);
       buffer = buffer.slice(newlineIndex + 1);
       if (!line.trim()) continue;
-      (async () => {
-        try {
-          if (expiresSoon(tokens)) {
-            tokens = await getValidTokens();
-          }
-          try {
-            await transport.send(JSON.parse(line));
-          } catch (err) {
-            // Reactive invalidation: proactive expiry math can't catch everything (server-side
-            // revocation, clock skew, or an incompatible cache — see CACHE_VERSION). A real
-            // auth failure from the server is the ground truth; when we see one, invalidate
-            // whatever we're holding, force a genuinely fresh token, and retry once.
-            if (!isAuthError(err)) throw err;
-            log(`Send failed with an auth error (${err.message}) — invalidating cached token and retrying once.`);
-            tokens = await getValidTokens(true);
-            await transport.send(JSON.parse(line));
-          }
-        } catch (err) {
-          log(`Send failed: ${err.message}`);
-        }
-      })();
+      if (ready) {
+        forwardLine(transport, line, getTokens, setTokens, getFreshTokens);
+      } else {
+        pendingLines.push(line);
+      }
     }
   });
 
   process.stdin.on("end", async () => {
     log("stdin closed, shutting down.");
-    await transport.close();
+    if (transport) await transport.close();
     process.exit(0);
   });
 
   log("Local STDIO proxy running. Press Ctrl+C to exit.");
+
+  // AUTH-14: decided once per process — detectDefaultBrowser() shells out to Launch
+  // Services, no need to re-check mid-session. Safari-default machines keep using the
+  // existing device-code mechanism (AUTH-25); everything else uses the lighter loopback
+  // redirect, including refreshes and reactive re-auth below.
+  const isSafari = (await detectDefaultBrowser()) === "com.apple.safari";
+  getFreshTokens = isSafari ? getValidTokens : getValidTokensLoopback;
+  clearFreshTokens = isSafari ? clearCachedTokens : clearLoopbackTokens;
+
+  try {
+    tokens = await getFreshTokens();
+  } catch (err) {
+    // Sign-in genuinely failed (denied/expired), not just slow — every message queued while
+    // we waited, starting with `initialize`, gets a real JSON-RPC error so the host sees an
+    // explicit failure instead of a process it has to silently time out on.
+    log(`Sign-in failed: ${err.message}`);
+    for (const line of pendingLines) respondWithSignInError(line, err);
+    process.exit(1);
+  }
+
+  transport = new StreamableHTTPClientTransport(new URL(ROAMER_MCP_URL), {
+    requestInit: {
+      get headers() {
+        return { Authorization: `Bearer ${tokens.access_token}` };
+      },
+    },
+  });
+
+  transport.onerror = (err) => {
+    log(`Transport error: ${err.message}`);
+    // Same reasoning as the send-path retry above: an auth error means whatever's cached is
+    // known-bad, so drop it now rather than let the next proactive expiresSoon() check
+    // (which only reasons about calendar time) keep handing it out.
+    if (isAuthError(err)) clearFreshTokens();
+  };
+  // stdin/stdout <-> transport pass-through. Each stdin line is one JSON-RPC message;
+  // transport.send() delivers it, and transport.onmessage delivers whatever comes back
+  // (including server-initiated messages over the SSE half of the streamable-HTTP transport).
+  transport.onmessage = (message) => {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+  };
+
+  await transport.start();
+  log("Connected to remote server using StreamableHTTPClientTransport.");
+
+  ready = true;
+  for (const line of pendingLines) {
+    forwardLine(transport, line, getTokens, setTokens, getFreshTokens);
+  }
+}
+
+// Only auto-run when invoked directly (npx/CLI) — importing this module from a test file
+// must not trigger a live device-auth flow and stdio takeover as a side effect.
+const isMainModule = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  main().catch((err) => {
+    log(`Fatal error: ${err.stack ?? err.message}`);
+    process.exit(1);
+  });
 }
 
-main().catch((err) => {
-  log(`Fatal error: ${err.stack ?? err.message}`);
-  process.exit(1);
-});
+export { respondWithSignInError, forwardLine, detectDefaultBrowser };