@mathismeadows/roamer-device-auth 1.0.1 → 1.1.1

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@mathismeadows/roamer-device-auth",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "private": false,
   "type": "module",
-  "description": "OAuth 2.0 Device Authorization Grant auth + stdio<->HTTP MCP proxy for Roamer MCP, used by roamer-bridge.sh when the OS's default browser is Safari (AUTH-14).",
+  "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.",
   "bin": {
     "roamer-device-auth": "./roamer-device-auth.mjs"
   },
@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "open": "^11.0.0"
+    "open": "^11.0.0",
+    "qrcode-terminal": "^0.12.0"
   }
 }

package/roamer-device-auth.mjs

@@ -1,37 +1,22 @@
 #!/usr/bin/env node
-// Roamer MCP — device-code auth path (AUTH-14).
+// Roamer MCP — server-mediated device authorization flow (AUTH-25).
 //
-// Used instead of roamer-bridge.sh's normal mcp-remote/loopback-redirect flow
-// when the OS's default browser is Safari. Safari's HTTPS-Only Mode blocks
-// ANY plain http:// top-level navigation, so a loopback redirect callback
-// (http://127.0.0.1:<port>/oauth/callback) never works there no matter what
-// the redirect URI looks like — see AUTH-14 and the roamer-bridge.sh comments.
+// 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.
 //
-// The OAuth 2.0 Device Authorization Grant sidesteps the problem entirely:
-// there is no redirect URI and no local listener at all. The user visits a
-// real https://microsoft.com page and types a short code; this process polls
-// Entra's token endpoint until that completes. Independent of mcp-remote —
-// this file owns its own token cache and its own stdio<->HTTP MCP proxying
-// (via the official @modelcontextprotocol/sdk), rather than assuming anything
-// about mcp-remote's on-disk format.
+// 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,
+// version-pinned package via npx rather than running this file in place.
 //
-// stdout is reserved for the JSON-RPC protocol channel; all logging goes to
-// stderr, matching the convention in roamer-bridge.sh / mcp-remote.
-//
-// The verification URL + user code are also shown via a native macOS dialog
-// (osascript), not just logged to stderr: this script normally runs as an MCP
-// host's spawned stdio subprocess, and hosts are not obligated to surface a
-// child process's stderr anywhere visible — confirmed by hitting exactly that
-// with a stderr-only first version of this file. Entra's device-code response
-// has no verification_uri_complete (pre-filled-code URL) field, so the code
-// can only be conveyed as text; the dialog is what makes that text guaranteed
-// visible, the same way the redirect flow's login prompt is inherently
-// visible by virtue of a real browser window opening.
-//
-// 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, version-pinned package via npx rather than running this file
-// in place, so the public plugin repo doesn't have to carry this source.
+// stdout is reserved for the JSON-RPC protocol channel; all logging goes to stderr.
 
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
@@ -40,43 +25,56 @@ 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 qrcode from "qrcode-terminal";
 
 const execFileAsync = promisify(execFile);
 
 const ROAMER_MCP_URL = process.env.ROAMER_MCP_URL ?? "https://roamer-mcp.mathismeadows.com/mcp";
-const ROAMER_MCP_CLIENT_ID = process.env.ROAMER_MCP_CLIENT_ID ?? "a55708ff-a990-4a06-afa8-d2fc86980b4e";
-const ROAMER_MCP_TENANT_ID = process.env.ROAMER_MCP_TENANT_ID ?? "6099dc20-e8a0-4925-b68d-b9d267e01cff";
-const SCOPE = "https://roamer-mcp.mathismeadows.com/mcp/mcp.access offline_access";
+const ROAMER_MCP_ORIGIN = new URL(ROAMER_MCP_URL).origin;
 
-const AUTHORITY = `https://login.microsoftonline.com/${ROAMER_MCP_TENANT_ID}/oauth2/v2.0`;
 const CACHE_DIR = join(homedir(), ".mcp-auth-device");
 const CACHE_FILE = join(CACHE_DIR, "roamer_tokens.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
+// enough to trust it — confirmed live 2026-08-21: a stale Entra JWT in this exact cache file
+// was blindly reused and rejected by Cloudflare with invalid_token, with no way to detect or
+// recover short of manually deleting the file. This version stamp is the fix.
+const CACHE_VERSION = 1;
+
 function log(message) {
   process.stderr.write(`[roamer-device-auth] ${message}\n`);
 }
 
-// stderr text alone is not a reliable way to reach the user: this process is
-// typically spawned as an MCP host's stdio subprocess, and hosts are not
-// obligated to surface a child process's stderr anywhere a human will see it
-// (confirmed — a host running this exact script did not). A native dialog is
-// an OS-level surface, guaranteed visible independent of what the host does
-// with stderr, mirroring how the redirect flow's visibility never depended on
-// stderr either (a real browser window opening is its own visible side effect).
+// StreamableHTTPClientTransport surfaces the upstream response body in the error message
+// (confirmed live: "Streamable HTTP error: Error POSTing to endpoint: {"error":"invalid_token",...}")
+// — pattern-match on that rather than a status code, since the SDK doesn't expose one directly.
+function isAuthError(err) {
+  return /invalid_token|unauthorized|\b401\b/i.test(err?.message ?? "");
+}
+
+// A native dialog is an OS-level surface, guaranteed visible independent of whether the MCP
+// host surfaces this process's stderr anywhere a human will see it (confirmed on the old
+// Entra-direct flow: a stderr-only first version left the user with no way to see the code).
 async function showDeviceCodeDialog(verificationUri, userCode) {
   const message = `Sign in to Roamer MCP:\n\n1. Go to ${verificationUri}\n2. Enter code: ${userCode}`;
   const script = `display dialog "${message.replace(/"/g, '\\"')}" with title "Roamer MCP Sign-In" buttons {"OK"} default button "OK"`;
   try {
     await execFileAsync("osascript", ["-e", script]);
   } catch {
-    // Best-effort only — the code is still in the fatal-error-free stderr log
-    // above for anyone who does have visibility into it.
+    // Best-effort, macOS-only — the terminal-visible QR code and stderr log below are the
+    // fallback for every other OS and for any environment without osascript.
   }
 }
 
 async function readCachedTokens() {
   try {
-    return JSON.parse(await readFile(CACHE_FILE, "utf8"));
+    const tokens = JSON.parse(await readFile(CACHE_FILE, "utf8"));
+    // A cache from an incompatible prior format must never be trusted just because it
+    // happens to have the right field names — see CACHE_VERSION's comment.
+    if (tokens?.cacheVersion !== CACHE_VERSION) return null;
+    return tokens;
   } catch {
     return null;
   }
@@ -84,35 +82,51 @@ async function readCachedTokens() {
 
 async function writeCachedTokens(tokens) {
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
-  await writeFile(CACHE_FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+  const stamped = { ...tokens, cacheVersion: CACHE_VERSION };
+  await writeFile(CACHE_FILE, JSON.stringify(stamped, null, 2), { mode: 0o600 });
+}
+
+function clearCachedTokens() {
+  return writeFile(CACHE_FILE, "{}", { mode: 0o600 }).catch(() => {});
+}
+
+function expiresSoon(tokens) {
+  // expires_in is optional in the response shape — an absent value means treat the token as
+  // long-lived and rely on a real 401 to trigger re-auth rather than guessing a lifetime.
+  if (!tokens.expires_in) return false;
+  const obtainedAt = tokens.obtained_at ?? 0;
+  const expiresAt = obtainedAt + tokens.expires_in * 1000;
+  return Date.now() > expiresAt - 60_000; // refresh a minute early
 }
 
-async function requestDeviceCode() {
-  const body = new URLSearchParams({ client_id: ROAMER_MCP_CLIENT_ID, scope: SCOPE });
-  const response = await fetch(`${AUTHORITY}/devicecode`, {
+async function refreshTokens(refreshToken) {
+  const response = await fetch(`${ROAMER_MCP_ORIGIN}/oauth/device/refresh`, {
     method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ refresh_token: refreshToken }),
   });
   if (!response.ok) {
-    throw new Error(`Device code request failed: ${response.status} ${await response.text()}`);
+    throw new Error(`Token refresh failed: ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+async function startDeviceFlow() {
+  const response = await fetch(`${ROAMER_MCP_ORIGIN}/oauth/device/start`, { method: "POST" });
+  if (!response.ok) {
+    throw new Error(`Device flow start failed: ${response.status} ${await response.text()}`);
   }
   return response.json();
 }
 
-async function pollForToken(deviceCode, intervalSeconds) {
+async function pollDeviceFlow(deviceCode, intervalSeconds) {
   let interval = intervalSeconds;
-  const body = new URLSearchParams({
-    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-    device_code: deviceCode,
-    client_id: ROAMER_MCP_CLIENT_ID,
-  });
   for (;;) {
     await sleep(interval * 1000);
-    const response = await fetch(`${AUTHORITY}/token`, {
+    const response = await fetch(`${ROAMER_MCP_ORIGIN}/oauth/device/poll`, {
       method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code: deviceCode }),
     });
     const data = await response.json();
     if (response.ok) {
@@ -125,45 +139,32 @@ async function pollForToken(deviceCode, intervalSeconds) {
       interval += 5;
       continue;
     }
-    throw new Error(`Device code login failed: ${data.error} — ${data.error_description ?? ""}`);
+    throw new Error(`Device flow login failed: ${data.error}`);
   }
 }
 
-async function refreshTokens(refreshToken) {
-  // Deliberately scope-based (not resource-based) — see the AADSTS90009 note
-  // in roamer-bridge.sh for why a resource-indicator refresh fails against
-  // this app registration.
-  const body = new URLSearchParams({
-    grant_type: "refresh_token",
-    refresh_token: refreshToken,
-    client_id: ROAMER_MCP_CLIENT_ID,
-    scope: SCOPE,
-  });
-  const response = await fetch(`${AUTHORITY}/token`, {
-    method: "POST",
-    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-    body,
-  });
-  if (!response.ok) {
-    throw new Error(`Token refresh failed: ${response.status} ${await response.text()}`);
-  }
-  return response.json();
-}
+// Concurrent stdin messages arriving during a refresh/re-auth window must not each kick off
+// their own competing flow — worst case that means multiple device-code dialogs popping up
+// at once, or two refreshes racing on a rotating refresh_token where the loser's retry then
+// forces an unnecessary full sign-in. All concurrent callers await the same in-flight op.
+let inFlightTokens = null;
 
-function expiresSoon(tokens) {
-  const obtainedAt = tokens.obtained_at ?? 0;
-  const expiresAt = obtainedAt + (tokens.expires_in ?? 0) * 1000;
-  return Date.now() > expiresAt - 60_000; // refresh a minute early
+function getValidTokens(forceRefresh = false) {
+  if (inFlightTokens) return inFlightTokens;
+  inFlightTokens = doGetValidTokens(forceRefresh).finally(() => {
+    inFlightTokens = null;
+  });
+  return inFlightTokens;
 }
 
-async function getValidTokens() {
-  let tokens = await readCachedTokens();
+async function doGetValidTokens(forceRefresh) {
+  let tokens = forceRefresh ? null : await readCachedTokens();
 
-  if (tokens && !expiresSoon(tokens)) {
+  if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
     return tokens;
   }
 
-  if (tokens?.refresh_token) {
+  if (!forceRefresh && tokens?.refresh_token) {
     try {
       log("Refreshing cached token...");
       const fresh = await refreshTokens(tokens.refresh_token);
@@ -171,27 +172,35 @@ async function getValidTokens() {
       await writeCachedTokens(tokens);
       return tokens;
     } catch (err) {
-      log(`Refresh failed (${err.message}), falling back to device-code login.`);
+      log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
     }
   }
 
-  log("Starting device-code login...");
-  const device = await requestDeviceCode();
+  if (forceRefresh) await clearCachedTokens();
+
+  log("Starting sign-in...");
+  const device = await startDeviceFlow();
   log(`Go to ${device.verification_uri} and enter code: ${device.user_code}`);
-  // Fire-and-forget: the dialog is how the human actually sees this (see
-  // showDeviceCodeDialog above); polling below must not wait on it being
-  // dismissed.
+  // Fire-and-forget: the dialog is how the human actually sees this on macOS; polling below
+  // must not wait on it being dismissed.
   showDeviceCodeDialog(device.verification_uri, device.user_code);
   try {
     const { default: open } = await import("open");
-    await open(device.verification_uri);
+    await open(device.verification_uri_complete);
   } catch {
-    // Best-effort only — the dialog above already carries the URL and code.
+    // Best-effort only — the dialog and QR code below already carry the URL and code.
   }
-  const fresh = await pollForToken(device.device_code, device.interval ?? 5);
+  // Terminal-visible for any client where a human sees this process's stderr/log output
+  // (Claude Code CLI, VS Code's integrated terminal) — QR codes are a real usability win
+  // for CLI auth over typing an 8-character code by hand.
+  qrcode.generate(device.verification_uri_complete, { small: true }, (qr) => {
+    process.stderr.write(`${qr}\n`);
+  });
+
+  const fresh = await pollDeviceFlow(device.device_code, device.interval ?? 5);
   tokens = { ...fresh, obtained_at: Date.now() };
   await writeCachedTokens(tokens);
-  log("Login complete.");
+  log("Sign-in complete.");
   return tokens;
 }
 
@@ -206,14 +215,19 @@ async function main() {
     },
   });
 
-  transport.onerror = (err) => log(`Transport error: ${err.message}`);
+  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();
+  };
   await transport.start();
   log("Connected to remote server using StreamableHTTPClientTransport.");
 
-  // 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).
+  // 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`);
   };
@@ -232,7 +246,18 @@ async function main() {
           if (expiresSoon(tokens)) {
             tokens = await getValidTokens();
           }
-          await transport.send(JSON.parse(line));
+          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}`);
         }