@mathismeadows/roamer-device-auth 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathismeadows/roamer-device-auth",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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.",

package/roamer-device-auth.mjs

@@ -34,11 +34,27 @@ const ROAMER_MCP_ORIGIN = new URL(ROAMER_MCP_URL).origin;
 
 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");
+
+// 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`);
 }
 
+// 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).
@@ -55,7 +71,11 @@ async function showDeviceCodeDialog(verificationUri, userCode) {
 
 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;
   }
@@ -63,7 +83,41 @@ 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(() => {});
+}
+
+// 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
+// human can click through inside a short timeout. Without persisting the in-progress flow,
+// every respawn called /oauth/device/start again, which mints a BRAND NEW device_code/
+// user_code — the user would see a different code every single retry, forever, with no
+// path to ever actually finish signing in. Confirmed live 2026-08-21. Persisting the
+// pending flow means a respawned process resumes polling the SAME still-valid code instead.
+async function readPendingFlow() {
+  try {
+    const pending = JSON.parse(await readFile(PENDING_FILE, "utf8"));
+    if (!pending?.device_code || Date.now() > pending.expiresAt) return null;
+    return pending;
+  } catch {
+    return null;
+  }
+}
+
+async function writePendingFlow(device) {
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+  const pending = { ...device, expiresAt: Date.now() + device.expires_in * 1000 };
+  await writeFile(PENDING_FILE, JSON.stringify(pending, null, 2), { mode: 0o600 });
+  return pending;
+}
+
+function clearPendingFlow() {
+  return writeFile(PENDING_FILE, "{}", { mode: 0o600 }).catch(() => {});
 }
 
 function expiresSoon(tokens) {
@@ -119,14 +173,28 @@ async function pollDeviceFlow(deviceCode, intervalSeconds) {
   }
 }
 
-async function getValidTokens() {
-  let tokens = await readCachedTokens();
+// 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 getValidTokens(forceRefresh = false) {
+  if (inFlightTokens) return inFlightTokens;
+  inFlightTokens = doGetValidTokens(forceRefresh).finally(() => {
+    inFlightTokens = null;
+  });
+  return inFlightTokens;
+}
+
+async function doGetValidTokens(forceRefresh) {
+  let tokens = forceRefresh ? null : await readCachedTokens();
 
-  if (tokens?.access_token && !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);
@@ -138,30 +206,56 @@ async function getValidTokens() {
     }
   }
 
-  log("Starting sign-in...");
-  const device = await startDeviceFlow();
+  if (forceRefresh) await clearCachedTokens();
+
+  // Resume an already-in-progress flow (from a process this host killed and respawned)
+  // instead of minting a new device_code the user would have to start over for.
+  let device = await readPendingFlow();
+  let resuming = Boolean(device);
+  if (!resuming) {
+    log("Starting sign-in...");
+    device = await startDeviceFlow();
+    await writePendingFlow(device);
+  } else {
+    log("Resuming an already-in-progress sign-in (a prior process was restarted before it finished)...");
+  }
+
   log(`Go to ${device.verification_uri} and enter code: ${device.user_code}`);
   // 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_complete);
-  } catch {
-    // Best-effort only — the dialog and QR code below already carry the URL and code.
+  // must not wait on it being dismissed. Skip re-showing it on a resume — the human already
+  // saw it (or is mid-flow in the browser) from the process that started this same code.
+  if (!resuming) showDeviceCodeDialog(device.verification_uri, device.user_code);
+  if (!resuming) {
+    try {
+      const { default: open } = await import("open");
+      await open(device.verification_uri_complete);
+    } catch {
+      // Best-effort only — the dialog and QR code below already carry the URL and code.
+    }
   }
   // 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`);
-  });
+  if (!resuming) {
+    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("Sign-in complete.");
-  return tokens;
+  try {
+    const fresh = await pollDeviceFlow(device.device_code, device.interval ?? 5);
+    tokens = { ...fresh, obtained_at: Date.now() };
+    await writeCachedTokens(tokens);
+    await clearPendingFlow();
+    log("Sign-in complete.");
+    return tokens;
+  } catch (err) {
+    // A hard failure (expired/denied, not just this process being killed) means the pending
+    // code is genuinely dead — clear it so the next attempt starts a real fresh one instead
+    // of retrying a code that will never succeed.
+    await clearPendingFlow();
+    throw err;
+  }
 }
 
 async function main() {
@@ -175,7 +269,13 @@ 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.");
 
@@ -200,7 +300,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}`);
         }