brightspace-mcp-server 1.6.3 → 2.0.0

package/build/auth/browser-auth.js

@@ -1,350 +1,151 @@
 /**
- * Purdue Brightspace MCP Server
+ * Brightspace MCP Server
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
- * Licensed under MIT — see LICENSE file for details.
+ * Licensed under MIT: see LICENSE file for details.
  */
 import * as path from "node:path";
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
+import { readFileSync, accessSync } from "node:fs";
 import { BrowserAuthError } from "../utils/errors.js";
 import { log } from "../utils/logger.js";
-import { createSSOFlow } from "./sso-flow.js";
-/**
- * The silent-SSO budget. When the D2L session is dead but the Microsoft Entra
- * cookie in the persistent profile is still alive, the SSO chain completes on
- * its own within a few seconds, provided the two no-secret surfaces in its way
- * get clicked. A URL check cannot see any of that, so the wait is a poll on a
- * positive session check instead.
- */
+import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError } from "./sso-flow.js";
+import { BrowserStateStore } from "./browser-state-store.js";
+import { acquireProcessLock } from "./auth-lock.js";
+import { AuthCooldown } from "./auth-cooldown.js";
+import { mintAccessToken } from "./token-mint.js";
 const SILENT_SSO_TIMEOUT_MS = 30000;
 const SILENT_SSO_POLL_MS = 1000;
+const INITIAL_NAVIGATION_TIMEOUT_MS = 60000;
 const SILENT_SSO = {
-    /** Entra asking who you are. No amount of silent waiting passes it. */
-    emailField: "input[type=email], input[name=loginfmt]",
-    /** The Brightspace campus selector's own link to the SAML endpoint. */
+    emailFields: ["input[type=email]", "input[name=loginfmt]"],
+    credentialFields: ['input#username', 'input#userName', 'input[type="password"]'],
+    mfaChallenges: ["#idRichContext_DisplaySign", "#idDiv_SAOTCAS_Title", "#idDiv_SAOTCC_Title"],
     campusSaml: 'a[href*="/d2l/lp/auth/saml/initiate-login"]',
-    /** Markers unique to the "Stay signed in?" page. */
     kmsiCheckbox: "#KmsiCheckboxField",
     kmsiTitle: "Stay signed in?",
     kmsiSubmit: "#idSIButton9",
 };
-/**
- * Thrown when a headless run reaches the point where a human has to see the
- * screen. Not a failure: the caller relaunches the browser visible and retries.
- */
-export class HeadlessLoginRequiredError extends Error {
-    constructor() {
-        super("A sign-in is needed and the browser must be visible for it");
-        this.name = "HeadlessLoginRequiredError";
+export class BrowserAuthTransportError extends Error {
+    code = "AUTH_TRANSPORT";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BrowserAuthTransportError";
     }
 }
-/** Whether the current attempt has to start over with a window on screen. */
-export function needsVisibleBrowser({ launchedHeadless }) {
-    return launchedHeadless;
-}
 export class BrowserAuth {
     config;
     ssoFlow;
-    /** Whether the browser for the current attempt was launched without a window. */
-    launchedHeadless = false;
+    stateStore;
+    cooldown;
     constructor(config) {
         this.config = config;
         this.ssoFlow = createSSOFlow(config);
+        this.stateStore = new BrowserStateStore(config.sessionDir);
+        this.cooldown = new AuthCooldown(config.sessionDir);
     }
-    /**
-     * Detect if running inside WSL (Windows Subsystem for Linux) or Docker.
-     * These environments require --no-sandbox for Chromium to launch.
-     */
     static isWSLOrDocker() {
         try {
-            // WSL: /proc/version contains "microsoft" or "WSL"
-            const procVersion = require("node:fs").readFileSync("/proc/version", "utf-8");
-            if (/microsoft|wsl/i.test(procVersion))
+            if (/microsoft|wsl/i.test(readFileSync("/proc/version", "utf8")))
                 return true;
         }
-        catch {
-            // Not Linux or /proc not available
-        }
+        catch { /* Not WSL. */ }
         try {
-            // Docker: /.dockerenv exists or /proc/1/cgroup contains "docker"
-            require("node:fs").accessSync("/.dockerenv");
+            accessSync("/.dockerenv");
             return true;
         }
-        catch {
-            // Not Docker
-        }
-        try {
-            const cgroup = require("node:fs").readFileSync("/proc/1/cgroup", "utf-8");
-            if (cgroup.includes("docker") || cgroup.includes("containerd"))
-                return true;
-        }
-        catch {
-            // Not in a container
-        }
-        return false;
-    }
-    /**
-     * Build Chromium launch args based on the current platform and environment.
-     */
-    static buildChromiumArgs() {
-        const args = ["--disable-blink-features=AutomationControlled"];
-        if (process.platform === "win32") {
-            args.push("--disable-gpu");
-        }
-        // On macOS, NSPersistentUIRestorer is disabled via `defaults write` in
-        // applyMacOSCrashGuard() — see issue #10. Passing "-ApplePersistenceIgnoreState YES"
-        // as argv doesn't work here because Playwright's launchPersistentContext rejects
-        // non-flag positional arguments.
-        if (BrowserAuth.isWSLOrDocker()) {
-            args.push("--no-sandbox", "--disable-setuid-sandbox");
-            log("INFO", "Detected WSL/Docker environment — launching Chromium with --no-sandbox");
-        }
-        return args;
-    }
-    /**
-     * Prevent Chrome for Testing from SIGTRAP'ing on launch on macOS (issue #10).
-     *
-     * Three layers, all idempotent and cheap:
-     *   1. ApplePersistenceIgnoreState — disables NSPersistentUIRestorer's crash-prompt
-     *      modal, which Chrome for Testing's AppKit bridge cannot handle.
-     *   2. IIO_LaunchInfo=0 — resets LaunchServices' per-app crash counter so macOS
-     *      stops triggering the recovery pathway in the first place.
-     *   3. Nuke the Cocoa saved-application-state bundle — if it exists, AppKit tries
-     *      to replay window state during launch and can crash the browser process.
-     *
-     * Runs before every launch. None of these are destructive to user data; Chrome
-     * for Testing is a disposable test profile.
-     */
-    static async applyMacOSCrashGuard() {
-        if (process.platform !== "darwin")
-            return;
-        const { execFile } = await import("node:child_process");
-        const { promisify } = await import("node:util");
-        const execFileAsync = promisify(execFile);
+        catch { /* Not Docker. */ }
         try {
-            await execFileAsync("defaults", [
-                "write",
-                "com.google.chrome.for.testing",
-                "ApplePersistenceIgnoreState",
-                "-bool",
-                "yes",
-            ]);
+            return /docker|containerd/.test(readFileSync("/proc/1/cgroup", "utf8"));
         }
         catch {
-            // Non-fatal
-        }
-        try {
-            await execFileAsync("defaults", [
-                "write",
-                "com.google.chrome.for.testing",
-                "IIO_LaunchInfo",
-                "-int",
-                "0",
-            ]);
-        }
-        catch {
-            // Non-fatal
-        }
-        try {
-            const savedState = path.join(os.homedir(), "Library", "Saved Application State", "com.google.chrome.for.testing.savedState");
-            await fs.rm(savedState, { recursive: true, force: true });
-        }
-        catch {
-            // Non-fatal
-        }
-        log("DEBUG", "Applied macOS crash guards for Chrome for Testing");
-    }
-    /**
-     * Recovery step: the current browser-data profile is corrupted in a way that
-     * makes Chromium SIGTRAP during launch (issue #10). Move it aside so the next
-     * launch attempt gets a clean profile. Cheap — user just re-authenticates.
-     */
-    async quarantineBrowserDataDir(browserDataDir) {
-        try {
-            const stamp = Date.now();
-            const quarantined = `${browserDataDir}.corrupted.${stamp}`;
-            await fs.rename(browserDataDir, quarantined);
-            log("WARN", `Quarantined corrupted browser profile to ${quarantined} — starting fresh`);
-        }
-        catch (error) {
-            // If rename fails (permissions, missing dir), try a recursive delete instead.
-            try {
-                await fs.rm(browserDataDir, { recursive: true, force: true });
-                log("WARN", "Deleted corrupted browser profile — starting fresh");
-            }
-            catch (rmError) {
-                log("WARN", "Failed to quarantine browser profile", rmError);
-            }
+            return false;
         }
     }
-    /**
-     * Authenticate, opening a window if the flow turns out to need one.
-     *
-     * Headless is only ever safe for the silent path. The moment a real sign-in
-     * is required the run starts over with a visible browser, because the MFA
-     * number match has to be readable by a human.
-     */
-    async authenticate() {
+    async authenticate(options = {}) {
+        const release = await acquireProcessLock(path.join(this.config.sessionDir, ".auth.lock"));
         try {
-            return await this.attemptAuthentication(this.config.headless);
+            // Even a cookie-only SAML redirect can issue an MFA push. Suppress all
+            // automatic browser attempts during cooldown; HTTP token refresh runs
+            // independently before this entrypoint and remains available.
+            if (options.automatic)
+                await this.cooldown.assertAllowed();
+            const token = await this.attemptAuthentication();
+            await options.onAuthenticated?.(token);
+            await this.cooldown.clear();
+            return token;
         }
-        catch (error) {
-            if (error instanceof HeadlessLoginRequiredError) {
-                log("INFO", "A sign-in is needed, so the browser is reopening with a window");
-                return await this.attemptAuthentication(false);
-            }
-            throw error;
+        finally {
+            await release();
         }
     }
-    async attemptAuthentication(preferHeadless) {
-        let context = null;
+    async attemptAuthentication() {
+        let browser;
+        let context;
+        let page;
+        let listener;
+        let interrupted = false;
+        const closeOnSignal = () => {
+            interrupted = true;
+            void browser?.close().catch(() => { });
+        };
         try {
-            log("INFO", "Starting browser authentication");
-            await BrowserAuth.applyMacOSCrashGuard();
-            const mkdirOpts = { recursive: true };
-            if (process.platform !== "win32") {
-                mkdirOpts.mode = 0o700;
-            }
-            await fs.mkdir(this.config.sessionDir, mkdirOpts);
-            const browserDataDir = path.join(this.config.sessionDir, "browser-data");
-            // Remove stale Chromium lock files that can block persistent context launch.
-            // On Windows, if the browser is killed by antivirus or force-closed, these
-            // lock files persist and prevent all future auth attempts.
-            await this.validateAndClearLockFiles(browserDataDir);
-            // Force headed mode when no credentials — user must interact with the browser
-            const headless = this.ssoFlow.hasCredentials() ? preferHeadless : false;
-            if (!this.ssoFlow.hasCredentials() && preferHeadless) {
-                log("INFO", "Overriding headless mode — browser must be visible for manual login");
-            }
-            this.launchedHeadless = headless;
-            const launchOptions = {
-                headless,
-                viewport: { width: 1280, height: 720 },
-                args: BrowserAuth.buildChromiumArgs(),
-                timeout: 60000,
-            };
-            context = await this.launchBrowserWithRetry(browserDataDir, launchOptions);
-            log("INFO", "Browser context launched");
-            // If the user Ctrl+C's while Chrome is running, Node tears down the
-            // subprocess with SIGKILL — Chrome writes "Crashed" to exit_type, the
-            // LaunchServices crash counter ticks up, and the next launch can SIGTRAP.
-            // Hook SIGINT/SIGTERM so we close the context gracefully first. See issue #10.
-            const contextRef = context;
-            const cleanShutdown = async (signal) => {
-                log("WARN", `Received ${signal} — closing browser cleanly`);
-                try {
-                    await contextRef.close();
-                }
-                catch {
-                    // Already closing
-                }
-                process.exit(130);
-            };
-            process.once("SIGINT", cleanShutdown);
-            process.once("SIGTERM", cleanShutdown);
-            // Load saved storage state if it exists (cookies + localStorage)
-            // This works around Playwright bug #36139 where session cookies don't persist
-            await this.loadStorageState(context);
-            const page = context.pages()[0] || (await context.newPage());
-            // CRITICAL: Set up token interception BEFORE navigation
-            // Use longer timeout for manual login (5 min) vs automated SSO (2 min)
-            const interceptTimeout = this.ssoFlow.hasCredentials() ? 120000 : 300000;
-            const tokenPromise = this.setupTokenInterception(page, interceptTimeout);
-            // Navigate and login if needed
-            const alreadyAuthenticated = await this.navigateAndLogin(page);
-            // Run the extraction strategy chain on BOTH paths. Modern Brightspace's
-            // /d2l/home uses cookie auth and emits no Bearer header, so the passive
-            // interceptor never fires on a fresh manual login — the chain rescues
-            // us via localStorage instead. See issue #10.
-            log("INFO", alreadyAuthenticated
-                ? "Session cookies active — trying to extract API token"
-                : "Login complete — extracting API token from session");
-            const extracted = await this.tryExtractToken(page, context);
-            if (extracted) {
-                const material = await this.harvestSessionMaterial(page, context);
-                await this.saveStorageState(context);
-                log("INFO", "Authentication complete");
-                return { ...extracted, ...material };
-            }
-            // Last resort for the cookie-restore path: clear cookies, force full
-            // re-login through SSO, and race the passive listener as a final fallback.
-            if (alreadyAuthenticated) {
-                log("WARN", "Could not extract valid token from existing session, forcing re-login");
-                await context.clearCookies();
-                await page.close();
-                const freshPage = await context.newPage();
-                const freshTokenPromise = this.setupTokenInterception(freshPage);
-                await this.navigateAndLogin(freshPage);
-                const freshExtracted = await this.tryExtractToken(freshPage, context);
-                if (freshExtracted) {
-                    const material = await this.harvestSessionMaterial(freshPage, context);
-                    await this.saveStorageState(context);
-                    log("INFO", "Authentication complete");
-                    return { ...freshExtracted, ...material };
-                }
-                const accessToken = await freshTokenPromise;
-                log("INFO", "Bearer token captured after forced re-login");
-                const now = Date.now();
-                const tokenData = {
-                    accessToken,
-                    capturedAt: now,
-                    expiresAt: now + this.config.tokenTtl * 1000,
-                    source: "browser",
-                    ...(await this.harvestSessionMaterial(freshPage, context)),
-                };
-                await this.saveStorageState(context);
-                return tokenData;
-            }
-            // Fresh-login final fallback: wait on the passive listener.
-            // Rarely reached in practice — tryExtractToken typically hits localStorage first.
-            log("INFO", "Waiting for Bearer token from network interception");
-            const accessToken = await tokenPromise;
-            log("INFO", "Bearer token captured successfully");
-            const now = Date.now();
-            const tokenData = {
-                accessToken,
-                capturedAt: now,
-                expiresAt: now + this.config.tokenTtl * 1000,
-                source: "browser",
-                ...(await this.harvestSessionMaterial(page, context)),
+            const state = await this.stateStore.load();
+            const { chromium } = await import("playwright");
+            const args = ["--disable-blink-features=AutomationControlled"];
+            if (BrowserAuth.isWSLOrDocker())
+                args.push("--no-sandbox", "--disable-setuid-sandbox");
+            // Use Playwright's own timeout, which cleans up an unsuccessful launch.
+            browser = await chromium.launch({ headless: true, timeout: 60000, args });
+            process.once("SIGINT", closeOnSignal);
+            process.once("SIGTERM", closeOnSignal);
+            context = await browser.newContext({ viewport: { width: 1280, height: 720 }, storageState: state });
+            page = await context.newPage();
+            let captured;
+            listener = (request) => {
+                const url = new URL(request.url());
+                if (url.origin !== new URL(this.config.baseUrl).origin || !url.pathname.startsWith("/d2l/"))
+                    return;
+                const header = request.headers().authorization;
+                if (header?.startsWith("Bearer "))
+                    captured = header.slice(7);
             };
-            await this.saveStorageState(context);
-            log("INFO", "Authentication complete");
-            return tokenData;
-        }
-        catch (error) {
-            const errMsg = error instanceof Error ? error.message : String(error);
-            log("ERROR", "Browser authentication failed", error);
-            // Provide platform-specific troubleshooting hints
-            let hint = "";
-            if (process.platform === "win32") {
-                if (errMsg.includes("Target page, context or browser has been closed")) {
-                    hint = " (Windows hint: antivirus or firewall may be closing the browser. Try adding Chromium to your exclusion list.)";
+            page.on("request", listener);
+            await this.navigateAndLogin(page);
+            // Persist the verified browser state before token acquisition. Token
+            // minting can fail independently, and a temporary outage must not throw
+            // away newly renewed Entra or Brightspace cookies.
+            await this.stateStore.save(await context.storageState());
+            const material = await this.harvestSessionMaterial(page, context);
+            let token = null;
+            if (material.cookieHeader && material.csrfToken) {
+                const minted = await mintAccessToken({ baseUrl: this.config.baseUrl, cookieHeader: material.cookieHeader, csrfToken: material.csrfToken });
+                if (minted.ok) {
+                    token = { accessToken: minted.accessToken, capturedAt: Date.now(), expiresAt: Date.now() + this.config.tokenTtl * 1000, source: "browser" };
                 }
-                else if (errMsg.includes("EPERM") || errMsg.includes("EACCES")) {
-                    hint = " (Windows hint: try running as Administrator, or check that no other process has locked the session directory.)";
+                else if (minted.reason === "transport") {
+                    throw new BrowserAuthTransportError(`Token mint temporarily failed: ${minted.detail ?? "network unavailable"}. Saved sign-in state is preserved.`);
                 }
-                else if (errMsg.includes("Timeout") || errMsg.includes("timeout")) {
-                    hint = " (Windows hint: browser launch timed out. Close all Chromium/Chrome instances in Task Manager and try again. Antivirus may also be blocking the launch.)";
+                else {
+                    throw new BrowserAuthError("Brightspace session expired while acquiring an API token. Retry authentication.", "token_extraction");
                 }
             }
-            if (BrowserAuth.isWSLOrDocker() && (errMsg.includes("spawn") || errMsg.includes("ENOENT") || errMsg.includes("sandbox"))) {
-                hint = " (WSL/Docker hint: ensure Chromium dependencies are installed. Run: npx playwright install-deps chromium)";
+            token ??= await this.tryExtractToken(page, context);
+            if (!token && captured && await this.validateToken(captured)) {
+                token = { accessToken: captured, capturedAt: Date.now(), expiresAt: Date.now() + this.config.tokenTtl * 1000, source: "browser" };
             }
-            throw new BrowserAuthError(`Authentication failed${hint}`, "authenticate", error);
+            if (!token)
+                throw new BrowserAuthError("Brightspace did not provide a usable API token. Saved SSO cookies have been preserved.", "token_extraction");
+            if (interrupted)
+                throw new BrowserAuthError("Authentication interrupted", "interrupted");
+            log("INFO", "Headless authentication complete");
+            return { ...token, ...material, tenantOrigin: new URL(this.config.baseUrl).origin };
         }
         finally {
-            if (context) {
-                log("DEBUG", "Closing browser context");
-                try {
-                    await context.close();
-                }
-                catch (closeError) {
-                    // Context may already be closed (e.g. browser crashed or was closed externally).
-                    // This is common on Windows where the browser process can terminate unexpectedly.
-                    log("DEBUG", "Browser context already closed or failed to close", closeError);
-                }
-            }
+            process.removeListener("SIGINT", closeOnSignal);
+            process.removeListener("SIGTERM", closeOnSignal);
+            if (page && listener)
+                page.removeListener("request", listener);
+            await context?.close().catch(() => { });
+            await browser?.close().catch(() => { });
         }
     }
     /**
@@ -362,7 +163,7 @@ export class BrowserAuth {
                 source: "browser",
             };
         };
-        // Strategy 0: localStorage (D2L.Fetch.Tokens) — fastest
+        // Strategy 0: localStorage (D2L.Fetch.Tokens) : fastest
         const lsToken = await this.extractLocalStorageToken(page);
         if (lsToken && (await this.validateToken(lsToken))) {
             log("INFO", "Extracted valid Bearer token from localStorage");
@@ -380,7 +181,9 @@ export class BrowserAuth {
                 return build(lsToken2);
             }
         }
-        catch {
+        catch (error) {
+            if (error instanceof BrowserAuthTransportError)
+                throw error;
             log("DEBUG", "Direct API navigation did not produce Bearer token");
         }
         // Strategy 2: XSRF / page JS context
@@ -406,115 +209,84 @@ export class BrowserAuth {
      * Returns true if the token is accepted by D2L, false otherwise.
      */
     async validateToken(token) {
+        let response;
         try {
-            const headers = {
-                "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-            };
-            if (token.startsWith("cookie:")) {
-                headers["Cookie"] = token.substring(7);
-            }
-            else {
-                headers["Authorization"] = `Bearer ${token}`;
-            }
-            const response = await fetch(`${this.config.baseUrl}/d2l/api/lp/1.45/users/whoami`, {
-                method: "GET",
-                headers,
+            response = await fetch(`${this.config.baseUrl}/d2l/api/lp/1.45/users/whoami`, {
+                headers: token.startsWith("cookie:") ? { Cookie: token.slice(7) } : { Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(10000),
             });
-            if (response.ok) {
-                log("DEBUG", "Token validation succeeded (whoami returned 200)");
-                return true;
-            }
-            log("DEBUG", `Token validation failed: HTTP ${response.status}`);
-            return false;
         }
         catch (error) {
-            log("DEBUG", "Token validation error", error);
-            return false;
+            throw new BrowserAuthTransportError("Token validation could not reach Brightspace.", { cause: error });
         }
+        if (response.ok) {
+            const contentType = response.headers.get("content-type") ?? "";
+            if (!contentType.includes("json"))
+                return false;
+            let user;
+            try {
+                user = await response.json();
+            }
+            catch (error) {
+                throw new BrowserAuthTransportError("Token validation returned unreadable JSON.", { cause: error });
+            }
+            const identifier = user?.Identifier;
+            return (typeof identifier === "string" && identifier.length > 0) || (typeof identifier === "number" && Number.isFinite(identifier));
+        }
+        if (response.status === 401 || response.status === 403)
+            return false;
+        throw new BrowserAuthTransportError(`Token validation temporarily failed with HTTP ${response.status}.`);
     }
-    /**
-     * Set up passive network request listener to capture Bearer token.
-     * MUST be called BEFORE page.goto() to avoid race condition.
-     */
-    setupTokenInterception(page, timeoutMs = 120000) {
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                reject(new BrowserAuthError(`Token interception timed out after ${timeoutMs / 1000} seconds`, "token_interception"));
-            }, timeoutMs);
-            page.on("request", (request) => {
-                const url = request.url();
-                // Look for any request with a Bearer token
-                if (url.includes("/d2l/")) {
-                    const authHeader = request.headers()["authorization"];
-                    if (authHeader && authHeader.startsWith("Bearer ")) {
-                        const token = authHeader.substring("Bearer ".length);
-                        log("DEBUG", `Token captured from request to ${url}`);
-                        clearTimeout(timeout);
-                        resolve(token);
-                    }
-                }
-            });
-            log("DEBUG", "Token interception listener registered");
-        });
-    }
-    /**
-     * Navigate to Brightspace and login if needed.
-     * Returns true if already authenticated (cookies valid), false if SSO login was performed.
-     */
+    /** Restore first, and only attempt credentials after a real sign-in is needed. */
     async navigateAndLogin(page) {
+        let navigationError;
+        let response;
         try {
-            log("INFO", `Navigating to ${this.config.baseUrl}/d2l/home`);
-            await page.goto(`${this.config.baseUrl}/d2l/home`, {
+            response = await page.goto(`${this.config.baseUrl}/d2l/home`, {
                 waitUntil: "domcontentloaded",
-                timeout: 30000,
+                timeout: INITIAL_NAVIGATION_TIMEOUT_MS,
             });
-            if (await this.awaitSilentSSO(page)) {
-                log("INFO", "Already authenticated - skipping SSO login");
-                await this.settle(page);
-                return true;
-            }
-            // A credential login on Entra ends in a number match: two digits on the
-            // page that the human types into Authenticator. Headless has nowhere to
-            // show them, so the login would time out with the number sitting in a
-            // log file. Bail out and let authenticate() relaunch with a window.
-            if (needsVisibleBrowser({ launchedHeadless: this.launchedHeadless })) {
-                throw new HeadlessLoginRequiredError();
-            }
-            let loginSuccess;
-            if (this.ssoFlow.hasCredentials()) {
-                log("INFO", `Login required (stopped at ${page.url()}) - starting SSO flow`);
-                loginSuccess = await this.ssoFlow.login(page);
-                if (!loginSuccess) {
-                    log("WARN", "Automated SSO flow failed or timed out. Falling back to manual login.");
-                    log("INFO", "Please complete the login manually in the open browser window.");
-                    loginSuccess = await this.ssoFlow.manualLogin(page);
-                }
-            }
-            else {
-                log("INFO", `Login required (stopped at ${page.url()}) - opening browser for manual login`);
-                loginSuccess = await this.ssoFlow.manualLogin(page);
-            }
-            if (!loginSuccess) {
-                throw new BrowserAuthError("Manual login flow failed", "manual_login");
-            }
-            await this.settle(page);
-            return false;
         }
         catch (error) {
-            if (error instanceof BrowserAuthError)
-                throw error;
-            throw new BrowserAuthError("Failed to navigate and login", "navigate_login", error);
+            // Brightspace Bar tolerates a navigation timeout because SAML may keep
+            // redirecting after Playwright stops waiting. Continue with the same
+            // bounded page-state poll, but never infer that credentials are needed
+            // from the navigation failure itself.
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/timeout|ERR_ABORTED|navigation.*interrupted/i.test(message)) {
+                throw new BrowserAuthTransportError("Could not reach Brightspace. Retry when the connection is available.", { cause: error });
+            }
+            navigationError = error;
+            log("WARN", "Initial Brightspace navigation did not settle; checking the current SSO page");
+        }
+        if (response && (response.status() >= 500 || response.status() === 429)) {
+            throw new BrowserAuthTransportError(`Brightspace temporarily returned HTTP ${response.status()}. Saved state is preserved.`);
+        }
+        if (await this.awaitSilentSSO(page)) {
+            log("INFO", "Saved session is active");
+            return true;
+        }
+        const pendingMfa = await this.isAnyOnScreen(page, SILENT_SSO.mfaChallenges);
+        if (!pendingMfa && !await this.hasCredentialPrompt(page)) {
+            throw new BrowserAuthTransportError("The sign-in page has not settled on a supported login challenge. Retry shortly; saved state is preserved.", navigationError === undefined ? undefined : { cause: navigationError });
+        }
+        if (!this.ssoFlow.hasCredentials() && !pendingMfa) {
+            throw new UnsupportedAuthenticationError("Headless sign-in requires saved credentials. Run brightspace-mcp-server setup.");
         }
-    }
-    /** Let the page finish loading, without letting a slow one fail the run. */
-    async settle(page) {
         try {
-            await page.waitForLoadState("domcontentloaded", { timeout: 30000 });
+            if (!await this.ssoFlow.login(page)) {
+                throw new UnsupportedAuthenticationError("The identity provider could not complete headless sign-in.");
+            }
         }
-        catch {
-            log("DEBUG", "Page wait timed out, proceeding anyway");
+        catch (error) {
+            if (error instanceof MfaApprovalError)
+                await this.cooldown.recordMfaFailure();
+            throw error;
         }
+        if (!await this.hasLiveSession(page)) {
+            throw new BrowserAuthError("Sign-in did not produce a verified Brightspace session.", "session_validation");
+        }
+        return false;
     }
     /**
      * Give the SSO chain a bounded window to finish with no human input.
@@ -522,20 +294,57 @@ export class BrowserAuth {
      */
     async awaitSilentSSO(page) {
         const deadline = Date.now() + SILENT_SSO_TIMEOUT_MS;
+        let accountHintAttempted = false;
+        let passwordPromptPolls = 0;
         do {
             if (await this.hasLiveSession(page))
                 return true;
-            // Fail fast rather than spend the budget on a page that will never
-            // advance: a fresh profile otherwise stalls here for the full 30s.
-            if (await this.isOnScreen(page, SILENT_SSO.emailField)) {
-                log("INFO", "Silent SSO cannot pass an account-name prompt - a credential login is needed");
+            // Only a visible supported challenge justifies entering credentials or
+            // waiting for MFA. A stalled redirect is not proof of session expiry.
+            if (await this.isAnyOnScreen(page, SILENT_SSO.emailFields)) {
+                if (!accountHintAttempted && this.ssoFlow.identifyAccount) {
+                    accountHintAttempted = true;
+                    if (await this.ssoFlow.identifyAccount(page)) {
+                        log("DEBUG", "Submitted the configured account name to resume saved SSO");
+                        await page.waitForTimeout(SILENT_SSO_POLL_MS);
+                        continue;
+                    }
+                }
+                log("INFO", "The identity provider requires an account login");
                 return false;
             }
-            await this.clickSilentSurfaces(page);
-            await page.waitForTimeout(SILENT_SSO_POLL_MS);
+            if (await this.isAnyOnScreen(page, SILENT_SSO.mfaChallenges)) {
+                log("INFO", "The identity provider requires a login challenge");
+                return false;
+            }
+            if (await this.isAnyOnScreen(page, SILENT_SSO.credentialFields)) {
+                passwordPromptPolls += 1;
+                // Entra can briefly expose a password-shaped control while its email
+                // view initializes. Brightspace Bar polls the evolving page instead of
+                // concluding from that first transient snapshot.
+                if (passwordPromptPolls >= 2) {
+                    log("INFO", "The identity provider requires a login challenge");
+                    return false;
+                }
+                await page.waitForTimeout(SILENT_SSO_POLL_MS);
+                continue;
+            }
+            passwordPromptPolls = 0;
+            try {
+                await this.clickSilentSurfaces(page);
+                await page.waitForTimeout(SILENT_SSO_POLL_MS);
+            }
+            catch (error) {
+                if (error instanceof BrowserAuthError || error instanceof BrowserAuthTransportError)
+                    throw error;
+                throw new BrowserAuthTransportError("Silent sign-in could not reach the identity provider. Saved state is preserved.", { cause: error });
+            }
         } while (Date.now() < deadline);
-        log("DEBUG", `No session after ${SILENT_SSO_TIMEOUT_MS / 1000}s of silent SSO`);
-        return false;
+        throw new BrowserAuthTransportError("Silent sign-in did not reach Brightspace or a supported login challenge within 30 seconds. Retry shortly; saved state is preserved.");
+    }
+    async hasCredentialPrompt(page) {
+        return await this.isAnyOnScreen(page, SILENT_SSO.emailFields) ||
+            await this.isAnyOnScreen(page, SILENT_SSO.credentialFields);
     }
     /**
      * A POSITIVE session check, never "the URL doesn't look like a login page".
@@ -545,6 +354,13 @@ export class BrowserAuth {
      */
     async hasLiveSession(page) {
         try {
+            const location = new URL(page.url());
+            if (location.origin !== new URL(this.config.baseUrl).origin)
+                return false;
+            // The /d2l/login shell also exposes D2L.LP and stale session cookies.
+            // Only the requested authenticated home page is evidence of success.
+            if (!/^\/d2l\/home(?:\/|$)/.test(location.pathname))
+                return false;
             const cookies = await page.context().cookies(this.config.baseUrl);
             if (!cookies.some((c) => c.name === "d2lSessionVal" && Boolean(c.value))) {
                 return false;
@@ -554,8 +370,8 @@ export class BrowserAuth {
                 return d2l !== undefined && Boolean(d2l.LP);
             });
         }
-        catch {
-            return false;
+        catch (error) {
+            throw new BrowserAuthTransportError("The browser could not verify the saved Brightspace session. Saved state is preserved.", { cause: error });
         }
     }
     /**
@@ -565,6 +381,11 @@ export class BrowserAuth {
     async clickSilentSurfaces(page) {
         const url = page.url();
         if (url.includes("/d2l/login")) {
+            // The Purdue buttons are not ordinary links. Follow the school's known
+            // SAML entry before deciding whether saved Microsoft state has expired.
+            await this.ssoFlow.prepareLogin?.(page);
+            if (!page.url().includes("/d2l/login"))
+                return;
             // Brightspace renders the campus buttons in a shadow DOM, which
             // Playwright's selectors see through. A configured campus is matched by
             // name; otherwise the selector's own SAML link is the only affordance
@@ -598,7 +419,20 @@ export class BrowserAuth {
     }
     /** Visibility without the actionability wait, so a poll keeps its rhythm. */
     async isOnScreen(page, selector) {
-        return page.locator(selector).first().isVisible().catch(() => false);
+        try {
+            return await page.locator(selector).first().isVisible();
+        }
+        catch (error) {
+            throw new BrowserAuthTransportError("The browser could not inspect the sign-in page. Saved state is preserved.", { cause: error });
+        }
+    }
+    /** Check each selector independently so a hidden earlier match cannot mask a visible one. */
+    async isAnyOnScreen(page, selectors) {
+        for (const selector of selectors) {
+            if (await this.isOnScreen(page, selector))
+                return true;
+        }
+        return false;
     }
     /**
      * Try to extract Bearer token from D2L's localStorage.
@@ -693,7 +527,15 @@ export class BrowserAuth {
                     timeout: 15000,
                 });
             }
-            return await page.evaluate(() => {
+        }
+        catch (error) {
+            log("DEBUG", "Could not navigate to Brightspace before XSRF extraction", error);
+            return null;
+        }
+        // Brightspace Bar retries each evaluation independently because a redirect
+        // can destroy one JavaScript context while the next one is already valid.
+        for (let attempt = 0; attempt < 10; attempt += 1) {
+            const token = await page.evaluate(() => {
                 const d2l = window.D2L;
                 try {
                     const lp = d2l?.LP;
@@ -702,7 +544,7 @@ export class BrowserAuth {
                     const xsrf = auth?.Xsrf;
                     const getToken = xsrf?.GetXsrfToken;
                     if (getToken) {
-                        const value = getToken();
+                        const value = getToken.call(xsrf);
                         if (value)
                             return value;
                     }
@@ -712,12 +554,15 @@ export class BrowserAuth {
                 }
                 const metaToken = document.querySelector('meta[name="d2l-xsrf-token"]');
                 return metaToken ? metaToken.getAttribute("content") : null;
+            }).catch((error) => {
+                log("DEBUG", "XSRF evaluation raced a page transition, retrying", error);
+                return null;
             });
+            if (token)
+                return token;
+            await page.waitForTimeout(1000);
         }
-        catch (error) {
-            log("DEBUG", "XSRF-only extraction failed", error);
-            return null;
-        }
+        return null;
     }
     /**
      * Try to extract XSRF/API token from D2L's JavaScript context.
@@ -746,7 +591,7 @@ export class BrowserAuth {
                         const xsrf = auth?.Xsrf;
                         const getToken = xsrf?.GetXsrfToken;
                         if (getToken)
-                            return getToken();
+                            return getToken.call(xsrf);
                     }
                     catch {
                         // Not available
@@ -804,209 +649,5 @@ export class BrowserAuth {
             return null;
         }
     }
-    /**
-     * Load previously saved storage state (cookies + localStorage).
-     * Workaround for Playwright bug #36139: session cookies don't persist in persistent context.
-     */
-    async loadStorageState(context) {
-        try {
-            const storageStatePath = path.join(this.config.sessionDir, "storage-state.json");
-            // Check if storage state file exists
-            let stats;
-            try {
-                stats = await fs.stat(storageStatePath);
-            }
-            catch {
-                log("DEBUG", "No existing storage state to load");
-                return;
-            }
-            // Skip loading stale cookies that would fake "already authenticated"
-            const ageMs = Date.now() - stats.mtimeMs;
-            const maxAgeMs = this.config.tokenTtl * 1000;
-            if (ageMs > maxAgeMs) {
-                log("INFO", `Storage state is ${Math.round(ageMs / 60000)}min old (TTL ${this.config.tokenTtl}s) — skipping stale cookies`);
-                return;
-            }
-            // Read storage state
-            const stateJson = await fs.readFile(storageStatePath, "utf-8");
-            const state = JSON.parse(stateJson);
-            // Restore cookies
-            if (state.cookies && state.cookies.length > 0) {
-                await context.addCookies(state.cookies);
-                log("INFO", `Restored ${state.cookies.length} cookies from storage state`);
-            }
-            // Restore localStorage for each origin
-            if (state.origins && state.origins.length > 0) {
-                for (const origin of state.origins) {
-                    if (origin.localStorage && origin.localStorage.length > 0) {
-                        let tempPage = null;
-                        try {
-                            // Create a temporary page to set localStorage
-                            tempPage = await context.newPage();
-                            await tempPage.goto(origin.origin, { timeout: 10000 });
-                            // Set each localStorage item
-                            await tempPage.evaluate((items) => {
-                                for (const item of items) {
-                                    localStorage.setItem(item.name, item.value);
-                                }
-                            }, origin.localStorage);
-                            log("INFO", `Restored ${origin.localStorage.length} localStorage items for ${origin.origin}`);
-                        }
-                        catch (originError) {
-                            log("WARN", `Failed to restore localStorage for ${origin.origin}`, originError);
-                        }
-                        finally {
-                            if (tempPage) {
-                                try {
-                                    await tempPage.close();
-                                }
-                                catch {
-                                    // Page may already be closed
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            log("INFO", "Storage state restored successfully");
-        }
-        catch (error) {
-            log("WARN", "Failed to load storage state", error);
-        }
-    }
-    async saveStorageState(context) {
-        try {
-            const storageStatePath = path.join(this.config.sessionDir, "storage-state.json");
-            await context.storageState({ path: storageStatePath });
-            await fs.chmod(storageStatePath, 0o600);
-            log("DEBUG", `Storage state saved to ${storageStatePath}`);
-        }
-        catch (error) {
-            log("WARN", "Failed to save storage state", error);
-        }
-    }
-    /**
-     * Launch browser with retry logic.
-     * Windows is prone to 180s launch timeouts (Playwright issue #22117) caused by
-     * lingering Chromium processes, antivirus interference, or resource contention.
-     * On timeout, we clear lock files and retry once.
-     */
-    async launchBrowserWithRetry(browserDataDir, options) {
-        // The only place the browser is needed, so the only place it is loaded.
-        const { chromium } = await import("playwright");
-        // Validate lock files before every launch attempt
-        await this.validateAndClearLockFiles(browserDataDir);
-        try {
-            // Wrap in Promise.race so a hung launch (e.g. stale SingletonLock
-            // that wasn't caught) still falls into the retry path
-            const launchPromise = chromium.launchPersistentContext(browserDataDir, options);
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout: browser launch hung")), options.timeout));
-            return await Promise.race([launchPromise, timeoutPromise]);
-        }
-        catch (error) {
-            const errMsg = error instanceof Error ? error.message : String(error);
-            const isTimeout = errMsg.includes("Timeout") || errMsg.includes("timeout") || errMsg.includes("hung");
-            // macOS: Chrome for Testing died during launch with SIGTRAP / browser
-            // closed. The profile is likely corrupted from prior crashes. Quarantine
-            // it, reapply the crash guards, and retry with a fresh profile.
-            // See issue #10.
-            const isMacBrowserCrash = process.platform === "darwin" &&
-                (errMsg.includes("Target page, context or browser has been closed") ||
-                    errMsg.includes("SIGTRAP") ||
-                    errMsg.includes("did exit"));
-            if (isMacBrowserCrash) {
-                log("WARN", "Chrome for Testing crashed during launch — quarantining profile and retrying");
-                await this.quarantineBrowserDataDir(browserDataDir);
-                await BrowserAuth.applyMacOSCrashGuard();
-                return await chromium.launchPersistentContext(browserDataDir, {
-                    ...options,
-                    timeout: 90000,
-                });
-            }
-            if (isTimeout) {
-                log("WARN", "Browser launch timed out — clearing lock files and retrying");
-                await this.validateAndClearLockFiles(browserDataDir);
-                return await chromium.launchPersistentContext(browserDataDir, {
-                    ...options,
-                    timeout: 90000,
-                });
-            }
-            throw error;
-        }
-    }
-    /**
-     * Validate and remove stale Chromium lock files from the browser data directory.
-     * Playwright's persistent context uses Chromium's SingletonLock mechanism.
-     * If the browser is killed unexpectedly (antivirus, force close, crash),
-     * these lock files persist and block all future launch attempts.
-     *
-     * For SingletonLock (a symlink whose target is "hostname-pid"), we check
-     * whether the owning process is still alive before removing it. This avoids
-     * deleting a lock held by a legitimate running instance.
-     */
-    async validateAndClearLockFiles(browserDataDir) {
-        // Ensure the directory exists before scanning
-        try {
-            await fs.access(browserDataDir);
-        }
-        catch {
-            return; // Directory doesn't exist yet, nothing to clean
-        }
-        const lockFiles = ["SingletonLock", "SingletonCookie", "SingletonSocket"];
-        for (const lockFile of lockFiles) {
-            const lockPath = path.join(browserDataDir, lockFile);
-            try {
-                const stat = await fs.lstat(lockPath);
-                if (stat.isSymbolicLink() && lockFile === "SingletonLock") {
-                    // SingletonLock is a symlink with target "hostname-pid"
-                    const target = await fs.readlink(lockPath);
-                    const dashIdx = target.lastIndexOf("-");
-                    if (dashIdx > 0) {
-                        const lockHostname = target.substring(0, dashIdx);
-                        const lockPid = parseInt(target.substring(dashIdx + 1), 10);
-                        if (lockHostname !== os.hostname()) {
-                            // Lock from a different machine (e.g. NFS home dir, or stale after network change)
-                            log("WARN", `Removing SingletonLock from different host (${lockHostname} vs ${os.hostname()})`);
-                            await fs.unlink(lockPath);
-                            continue;
-                        }
-                        if (!isNaN(lockPid)) {
-                            try {
-                                process.kill(lockPid, 0); // Signal 0 checks if process exists
-                                // Process is alive, leave the lock alone
-                                log("DEBUG", `SingletonLock held by live process ${lockPid}, skipping`);
-                                continue;
-                            }
-                            catch (killErr) {
-                                const code = killErr.code;
-                                if (code === "ESRCH") {
-                                    // Process is dead, safe to remove
-                                    log("WARN", `Removing SingletonLock from dead process ${lockPid}`);
-                                    await fs.unlink(lockPath);
-                                    continue;
-                                }
-                                if (code === "EPERM") {
-                                    // Process exists but we lack permissions, leave it alone
-                                    log("DEBUG", `SingletonLock held by process ${lockPid} (EPERM), skipping`);
-                                    continue;
-                                }
-                            }
-                        }
-                    }
-                    // Could not parse target, remove as a safety measure
-                    log("WARN", `Removing unparseable SingletonLock: ${target}`);
-                    await fs.unlink(lockPath);
-                }
-                else {
-                    // Regular file (SingletonCookie, SingletonSocket) or unknown symlink
-                    await fs.unlink(lockPath);
-                    log("WARN", `Removed stale lock file: ${lockFile}`);
-                }
-            }
-            catch {
-                // File doesn't exist, expected in normal operation
-            }
-        }
-    }
 }
 //# sourceMappingURL=browser-auth.js.map