brightspace-mcp-server 3.7.1 → 3.7.3

package/README.md

@@ -105,6 +105,10 @@ Run it from your home folder. On macOS, a terminal that lacks Files and Folders
 
 **MFA at Purdue** commonly uses Microsoft Authenticator number matching (some schools use Duo instead). When a sign-in needs it, the tool call itself returns quickly with the number to enter, rather than sitting silent for up to five minutes — approve it on your phone, then call the tool again; sign-in finishes in the background in the meantime. Google Authenticator and other one-time-code apps work too, with no setting to change: run the auth command above in a terminal and it prompts for the code when your provider asks for one. Pick the visible-browser option during setup only if your identity provider needs interaction the server cannot drive. The MCP also sends authentication progress as logging notifications to clients that display them, useful if you don't see the number in the tool response for some reason.
 
+The number in that response can go stale if the request times out or you tap Deny before approving it: the server asks Microsoft for another one and the next tool call reports the new number, so always enter whatever number the most recent response shows. If a background sign-in gets stuck, running the auth command above in a terminal takes it over immediately instead of waiting for it to finish or time out.
+
+**On a Duo tenant**, if Duo asks "Is this your device?" before it will send a push, automatic sign-in answers **yes** so the push can go out at all — a headless run has nobody to click it otherwise. That also makes Duo remember the device, which skips its own device check on later logins from this machine. Don't run automatic sign-in on a shared or public computer if you'd rather Duo keep asking. Setting `D2L_DUO_PASSCODE` to any value switches from waiting for a push to typing a code from Duo Mobile's passcode option instead.
+
 ## What You Can Ask About
 
 | Topic | Examples |

package/build/auth/auth-lock.js

@@ -48,15 +48,20 @@ export class AuthenticationInProgressError extends Error {
 async function readOwner(lockPath) {
     try {
         const owner = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf8"));
-        if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.host === "string" && typeof owner.nonce === "string")
-            return owner;
+        if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.host === "string" && typeof owner.nonce === "string") {
+            // A lock file written before `mode` existed, or one that carries an
+            // unrecognized value, is treated as "explicit" — the safer default,
+            // since only an "automatic" owner is ever eligible to be taken over.
+            const mode = owner.mode === "automatic" ? "automatic" : "explicit";
+            return { pid: owner.pid, host: owner.host, nonce: owner.nonce, mode };
+        }
     }
     catch {
         // An incomplete or unknown lock is not proof that its owner is gone.
     }
     return undefined;
 }
-function isDead(owner) {
+function isDeadImpl(owner) {
     // Session directories are local-only. DHCP can change the host's name
     // without changing this process table, so only PID liveness decides.
     try {
@@ -67,6 +72,20 @@ function isDead(owner) {
         return error.code === "ESRCH";
     }
 }
+/**
+ * Process operations behind a swappable seam. Production code always goes
+ * through this object with its real implementations; a test that needs a
+ * "live" owner it can safely terminate (without spawning or signaling a real
+ * process) replaces `kill`/`isDead` here instead. This file is intentionally
+ * free of relative imports — see tests/auth/auth-lock.test.ts, which loads it
+ * standalone via a data: URL for its real-process tests, and a relative
+ * import cannot be resolved from that base — so this seam is a plain
+ * exported object rather than an injected logger or similar dependency.
+ */
+export const lockOps = {
+    kill: (pid, signal) => { process.kill(pid, signal); },
+    isDead: isDeadImpl,
+};
 /** Remove only our fixed metadata names, after the directory was retired. */
 async function cleanRetired(lockPath) {
     await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });
@@ -103,16 +122,56 @@ class Lease {
         await cleanRetired(this.directory);
     }
 }
+/**
+ * How long an explicit run waits, after signaling a live automatic owner,
+ * for that owner to actually release the lock (either by dying outright or
+ * by finishing its own cleanup and renaming the directory away) before
+ * retrying acquisition.
+ */
+const TAKEOVER_WAIT_MS = 10_000;
+const TAKEOVER_POLL_MS = 100;
+/**
+ * SIGTERM a live automatic owner and wait for it to actually give up the
+ * lock. browser-auth.ts's `closeOnSignal` handles SIGTERM by closing the
+ * browser, which makes the automatic run's in-flight MFA loop throw; its
+ * `authenticate()` then runs its `finally` and releases the lock the normal
+ * way (the directory is renamed away). If the child instead dies outright
+ * (already-registered signal handler races the browser launch, or the
+ * process is killed some other way), `isDead` catches that instead. Either
+ * way this resolves once the lock is free for `acquireLease` to retry, or
+ * once TAKEOVER_WAIT_MS has passed without either happening.
+ */
+async function waitForTakeover(lockPath, stale) {
+    try {
+        lockOps.kill(stale.pid, "SIGTERM");
+    }
+    catch (error) {
+        // The owner exited between the liveness check and the signal. That is the
+        // outcome a takeover wants; the wait below sees the dead PID and returns.
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+    const deadline = Date.now() + TAKEOVER_WAIT_MS;
+    while (Date.now() < deadline) {
+        if (lockOps.isDead(stale))
+            return;
+        const current = await readOwner(lockPath);
+        if (!current || current.nonce !== stale.nonce)
+            return;
+        await delay(TAKEOVER_POLL_MS);
+    }
+}
 /** Acquire a process-shared lock without waiting or relying on its age. */
-export async function acquireProcessLock(lockPath) {
+export async function acquireProcessLock(lockPath, options = {}) {
     await fs.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
-    const lease = await acquireLease(lockPath, 0);
+    const mode = options.mode ?? "explicit";
+    const lease = await acquireLease(lockPath, 0, mode);
     return () => lease.release();
 }
-async function acquireLease(lockPath, depth) {
+async function acquireLease(lockPath, depth, mode) {
     if (depth > 16)
         throw new AuthenticationInProgressError();
-    const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+    const owner = { pid: process.pid, host: hostname(), nonce: randomUUID(), mode };
     for (let attempt = 0; attempt < 3; attempt += 1) {
         try {
             await fs.mkdir(lockPath, { mode: 0o700 });
@@ -132,15 +191,29 @@ async function acquireLease(lockPath, depth) {
                 throw error;
         }
         const stale = await readOwner(lockPath);
-        if (!stale || !isDead(stale))
+        if (!stale)
             throw new AuthenticationInProgressError();
+        if (!lockOps.isDead(stale)) {
+            // A live owner is not stale — the existing behavior for two contending
+            // explicit runs, or an automatic run finding anything alive at all.
+            // The one exception: an explicit run may take over a live *automatic*
+            // one, since a background sign-in nobody is watching should not block
+            // someone who just sat down to fix it in a terminal.
+            if (mode !== "explicit" || stale.mode !== "automatic")
+                throw new AuthenticationInProgressError();
+            // No import of the shared logger here — see lockOps's doc comment on
+            // why this file stays free of relative imports.
+            console.error(`[${new Date().toISOString()}] [WARN] Took over a background sign-in (pid ${stale.pid}) for an explicit auth run`);
+            await waitForTakeover(lockPath, stale);
+            continue;
+        }
         // Recovery gets its own process lock within the stale directory. If a
         // recovering process crashes, the same dead-owner rules recover its lock.
         // Keep this claim in the directory during rename to serialize contenders.
-        const claim = await acquireLease(path.join(lockPath, "reclaim.lock"), depth + 1);
+        const claim = await acquireLease(path.join(lockPath, "reclaim.lock"), depth + 1, mode);
         try {
             const current = await readOwner(lockPath);
-            if (current?.nonce !== stale.nonce || !isDead(current))
+            if (current?.nonce !== stale.nonce || !lockOps.isDead(current))
                 throw new AuthenticationInProgressError();
             const retired = `${lockPath}.stale.${owner.nonce}`;
             // A rename blocked by contention means another contender is inside this

package/build/auth/auth-runner.js

@@ -408,7 +408,7 @@ export class AuthRunner {
                 }
                 else {
                     const failures = {
-                        2: ["busy", "Authentication already in progress in another process. Complete that attempt, then retry."],
+                        2: ["busy", `Authentication already in progress in another process. Complete that attempt, then retry, or run \`${AUTH_COMMAND}\` in a terminal to take over that background attempt.`],
                         3: ["cooldown", `Automatic MFA is paused after an unsuccessful attempt. Run ${AUTH_COMMAND} to retry immediately.`],
                         4: ["unsupported", "This identity provider cannot complete headless authentication. See the authentication logs."],
                         5: ["secureStorage", "The native credential store is unavailable or locked. Unlock it and retry."],

package/build/auth/browser-auth.js

@@ -19,7 +19,11 @@ const SILENT_SSO_POLL_MS = 1000;
 const INITIAL_NAVIGATION_TIMEOUT_MS = 60000;
 const VISIBLE_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 const SILENT_SSO = {
-    emailFields: ["input[type=email]", "input[name=loginfmt]"],
+    // Kept in sync with purdue-sso.ts's EMAIL_SELECTORS: awaitSilentSSO gates on
+    // this list before ever calling into that file, so a two-step Shibboleth/CAS
+    // IdP whose username field only matches j_username or #signinid would never
+    // get past this gate otherwise.
+    emailFields: ["input[type=email]", "input[name=loginfmt]", "input[name=j_username]", "input#signinid"],
     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"]',
@@ -64,7 +68,7 @@ export class BrowserAuth {
         }
     }
     async authenticate(options = {}) {
-        const release = await acquireProcessLock(path.join(this.config.sessionDir, ".auth.lock"));
+        const release = await acquireProcessLock(path.join(this.config.sessionDir, ".auth.lock"), { mode: options.automatic ? "automatic" : "explicit" });
         try {
             // Even a cookie-only SAML redirect can issue an MFA push. Suppress all
             // automatic browser attempts during cooldown; HTTP token refresh runs

package/build/auth/duo-mfa.js

@@ -30,6 +30,8 @@ const PROMPT_SCOPE_SELECTORS = [
     "main",
     "body",
 ];
+/** Duo's own passcode field, which its Universal Prompt labels inconsistently. */
+const PASSCODE_INPUT_SELECTORS = ["#passcode-input", 'input[name="passcode"]'];
 /** The digits on a visible element, or null when it is absent or not digits. */
 async function readCodeFrom(target) {
     if (!await target.isVisible().catch(() => false))
@@ -53,31 +55,109 @@ export class DuoMfaHandler {
     approvalAnnounced = false;
     verificationCodeAnnounced = null;
     passcodeSubmitted = false;
+    /** True once Duo's remembered-device question has been answered this login. */
+    deviceQuestionAnswered = false;
+    /** Step guards for walking Duo's "Other options" menu to the passcode field. */
+    otherOptionsClicked = false;
+    passcodeChoiceClicked = false;
     /** True once onMfaChallenge has been told about this login, code or not. */
     announcedToCaller = false;
+    /** The last code actually handed to onMfaChallenge. See purdue-sso.ts's lastAnnouncedNumber for why this is tracked separately from verificationCodeAnnounced. */
+    lastAnnouncedCode = null;
     constructor(options) {
         this.options = options;
     }
     isChallenge(page) {
         return isDuoPrompt(page);
     }
+    /**
+     * Some tenants gate the push behind a remembered-device question ("Is this
+     * your device?") that nothing proceeds past until it is answered. A headless
+     * run has nobody to click it, so the whole login stalls until the five-minute
+     * MFA deadline expires. Answering yes also makes Duo remember this device,
+     * which is what an unattended client wants.
+     */
+    async answerDeviceQuestion(page) {
+        if (this.deviceQuestionAnswered)
+            return false;
+        const candidates = [
+            page.getByRole("button", { name: /yes.*this is my device/i }).first(),
+            page.locator("button", { hasText: /yes.*this is my device/i }).first(),
+        ];
+        for (const candidate of candidates) {
+            if (!await candidate.isVisible().catch(() => false))
+                continue;
+            this.deviceQuestionAnswered = true;
+            log("INFO", "Answered Duo's remembered-device question with yes.");
+            await candidate.click().catch(() => { });
+            return true;
+        }
+        return false;
+    }
+    /** Duo's passcode field, whichever of its shapes is on screen. */
+    async passcodeInput(page) {
+        for (const selector of PASSCODE_INPUT_SELECTORS) {
+            const target = page.locator(selector).first();
+            if (await target.isVisible().catch(() => false))
+                return target;
+        }
+        const byRole = page.getByRole("textbox", { name: /passcode|verification code/i }).first();
+        return await byRole.isVisible().catch(() => false) ? byRole : null;
+    }
+    /**
+     * Duo opens on "Check for a Duo Push" and keeps the passcode field behind its
+     * "Other options" menu ("Select an option to log in" -> "Duo Mobile
+     * passcode"). Walking that path makes sign-in independent of push delivery
+     * and of the device Duo happens to pick. Each step is clicked at most once,
+     * so a re-render cannot bounce the page back and forth.
+     */
+    async openPasscodeEntry(page) {
+        if (await this.passcodeInput(page))
+            return;
+        if (!this.otherOptionsClicked) {
+            const other = page.getByRole("button", { name: /other options/i }).first();
+            if (await other.isVisible().catch(() => false)) {
+                this.otherOptionsClicked = true;
+                log("INFO", "Opening Duo's Other options menu for a passcode.");
+                await other.click().catch(() => { });
+                await page.waitForTimeout(1500);
+            }
+        }
+        if (this.passcodeChoiceClicked)
+            return;
+        const choice = page.getByRole("button", { name: /duo mobile passcode/i }).first();
+        if (await choice.isVisible().catch(() => false)) {
+            this.passcodeChoiceClicked = true;
+            log("INFO", "Choosing Duo Mobile passcode entry.");
+            await choice.click().catch(() => { });
+            await page.waitForTimeout(1500);
+        }
+    }
     /** Returns true while the page is on a Duo challenge. */
     async handle(page) {
         if (!this.isChallenge(page))
             return false;
+        // Answer before announcing the push: on a gated tenant no push is sent
+        // until this is answered, so announcing first would be a lie.
+        await this.answerDeviceQuestion(page);
+        // Opt-in, because it replaces a push with a typed code: without it a tenant
+        // whose pushes work keeps the zero-touch path.
+        if (process.env.D2L_DUO_PASSCODE)
+            await this.openPasscodeEntry(page);
         const verificationCode = await this.readVerificationCode(page);
         if (!this.approvalAnnounced) {
             this.approvalAnnounced = true;
             log("WARN", "Waiting up to 5 minutes for Duo MFA approval on your device.");
             this.options.onMfaChallenge?.(verificationCode);
-            if (verificationCode)
-                this.announcedToCaller = true;
+            this.announcedToCaller = true;
+            this.lastAnnouncedCode = verificationCode;
         }
         if (verificationCode && verificationCode !== this.verificationCodeAnnounced) {
             this.verificationCodeAnnounced = verificationCode;
             log("WARN", `Duo verification code: ${verificationCode}. Enter it in Duo Mobile.`);
-            if (!this.announcedToCaller) {
+            if (!this.announcedToCaller || verificationCode !== this.lastAnnouncedCode) {
                 this.announcedToCaller = true;
+                this.lastAnnouncedCode = verificationCode;
                 this.options.onMfaChallenge?.(verificationCode);
             }
         }
@@ -126,8 +206,8 @@ export class DuoMfaHandler {
     async submitPasscode(page) {
         if (this.options.headless === false || this.passcodeSubmitted)
             return;
-        const input = page.getByRole("textbox", { name: /passcode|verification code/i }).first();
-        if (!await input.isVisible().catch(() => false))
+        const input = await this.passcodeInput(page);
+        if (!input)
             return;
         if (!this.options.requestMfaCode) {
             throw new UnsupportedAuthenticationError(`Duo requires a passcode. Run \`${AUTH_COMMAND}\` in a terminal to enter it.`);

package/build/auth/purdue-sso.js

@@ -8,7 +8,9 @@ import { log } from "../utils/logger.js";
 import { MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
 import { DuoMfaHandler } from "./duo-mfa.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
-const EMAIL_SELECTORS = ["input[type=email]", "input[name=loginfmt]"];
+// Entra names its username field type=email/loginfmt; Shibboleth portals (USC's
+// login.usc.edu among them) use the protocol's j_username.
+const EMAIL_SELECTORS = ["input[type=email]", "input[name=loginfmt]", "input[name=j_username]", "input#signinid"];
 const PASSWORD_SELECTORS = ["input[type=password]", "input[name=passwd]"];
 const SUBMIT_SELECTORS = ["#idSIButton9", "input[type=submit]", "button[type=submit]"];
 const FIELD_TIMEOUT_MS = 30_000;
@@ -26,6 +28,48 @@ const MFA_CODE_SUBMIT_SELECTORS = ["#idSubmit_SAOTCC_Continue", "#idSIButton9"];
 const NUMBER_MATCH_POLL_MS = 2000;
 /** A person has to find their phone, unlock it, and read a prompt. */
 const MFA_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Entra's number-match request itself expires (typically ~1-2 minutes) well
+ * before the 5-minute MFA_TIMEOUT_MS this flow allows overall, or the user
+ * can tap Deny. Either way Entra stops showing the number and offers a way to
+ * send another request; without asking for one this flow just polls a dead
+ * request until MFA_TIMEOUT_MS. Bounded so a tenant that never clears this
+ * screen still hits the ordinary timeout instead of resending forever.
+ */
+const MAX_RESENDS = 2;
+/**
+ * EXPECTED, not verified against a live tenant from here: Entra's "Send
+ * another request" control on the number-match timeout/denied view.
+ * Matched by id first because it is far more specific than the text fallback
+ * below. Entra's own title ids for this view — `#idDiv_SAASTO_Title` for a
+ * timeout, `#idDiv_SAASDS_Title` for a denial — are not matched directly
+ * since this id is the more stable target, but are left here as a breadcrumb
+ * for whoever next has a live tenant to confirm these against.
+ */
+const RESEND_ID_SELECTOR = "#idA_SAASTO_Resend";
+/**
+ * EXPECTED, not observed: a fallback for when Entra renames the id above.
+ * Any visible control whose text reads as a resend action, scoped to the
+ * sign-in surface (never the whole document, which can contain unrelated
+ * matches).
+ */
+const RESEND_TEXT_PATTERN = /send another request|resend notification|try again|send again/i;
+/**
+ * Never click a control offering to switch verification methods — that
+ * abandons number-match for something this headless flow cannot complete.
+ */
+const RESEND_SWITCH_METHOD_PATTERN = /can.t use|sign in another way|different verification|other ways/i;
+/** Where the text-based resend fallback is allowed to look. */
+const RESEND_SCOPE_SELECTORS = ["#lightbox", "form"];
+/** Log once, not on every poll, when no resend control turns up after a number vanishes. */
+const RESEND_NOT_FOUND_WARN_MS = 30_000;
+/**
+ * Don't click the resend control again on the immediately following poll —
+ * give Entra a full cycle to re-render before looking again. Two poll
+ * intervals rather than one so ordinary per-poll overhead can never make the
+ * elapsed time creep past a single interval and defeat the guard.
+ */
+const RESEND_CLICK_GUARD_MS = NUMBER_MATCH_POLL_MS * 2;
 /** Microsoft expects Purdue's full sign-in name, while setup also accepts a career account. */
 function signInName(username, baseUrl) {
     const isPurdue = baseUrl && new URL(baseUrl).hostname.toLowerCase() === "purdue.brightspace.com";
@@ -57,6 +101,14 @@ export class PurdueSSOFlow {
         const email = signInName(this.config.username, this.config.baseUrl);
         if (!await this.fillWhenReady(page, EMAIL_SELECTORS, email))
             return false;
+        // Reached via awaitSilentSSO, a single-page IdP (see enterCredentials)
+        // renders its password field next to the username too. Clicking submit
+        // without filling it first would post an empty password and burn the
+        // attempt, so detect and handle it here the same way.
+        if (this.config.password && await this.hasCoVisiblePassword(page)) {
+            if (!await this.fillWhenReady(page, PASSWORD_SELECTORS, this.config.password))
+                return false;
+        }
         if (!await this.clickWhenReady(page, SUBMIT_SELECTORS))
             return false;
         this.accountHintSubmitted = true;
@@ -125,17 +177,34 @@ export class PurdueSSOFlow {
         if (!hintAccepted) {
             const email = signInName(this.config.username, this.config.baseUrl);
             if (!await this.fillWhenReady(page, EMAIL_SELECTORS, email)) {
-                throw new UnsupportedAuthenticationError("The Microsoft email field did not appear. Automatic sign-in cannot continue.");
+                throw new UnsupportedAuthenticationError("The identity provider's username field did not appear. Automatic sign-in cannot continue.");
+            }
+            // A single-page identity provider (Shibboleth portals such as USC's
+            // login.usc.edu) renders the password field next to the username. Clicking
+            // submit between the two would post an empty password and spend the
+            // attempt, so fill both and click once. Entra can also flash a
+            // password-shaped decoy for a single instant while its email view is
+            // still initializing (see awaitSilentSSO's passwordPromptPolls in
+            // browser-auth.ts), so this only takes the single-page branch once the
+            // field survives two consecutive checks.
+            if (await this.hasCoVisiblePassword(page)) {
+                if (!await this.fillWhenReady(page, PASSWORD_SELECTORS, this.config.password)) {
+                    throw new UnsupportedAuthenticationError("The identity provider's password field did not appear. Automatic sign-in cannot continue.");
+                }
+                if (!await this.clickWhenReady(page, SUBMIT_SELECTORS)) {
+                    throw new UnsupportedAuthenticationError("The identity provider's submit button did not appear. Automatic sign-in cannot continue.");
+                }
+                return;
             }
             if (!await this.clickWhenReady(page, SUBMIT_SELECTORS)) {
-                throw new UnsupportedAuthenticationError("The Microsoft email submit button did not appear. Automatic sign-in cannot continue.");
+                throw new UnsupportedAuthenticationError("The identity provider's username submit button did not appear. Automatic sign-in cannot continue.");
             }
         }
         if (!await this.fillWhenReady(page, PASSWORD_SELECTORS, this.config.password)) {
-            throw new UnsupportedAuthenticationError("The Microsoft password field did not appear. Automatic sign-in cannot continue.");
+            throw new UnsupportedAuthenticationError("The identity provider's password field did not appear. Automatic sign-in cannot continue.");
         }
         if (!await this.clickWhenReady(page, SUBMIT_SELECTORS)) {
-            throw new UnsupportedAuthenticationError("The Microsoft password submit button did not appear. Automatic sign-in cannot continue.");
+            throw new UnsupportedAuthenticationError("The identity provider's password submit button did not appear. Automatic sign-in cannot continue.");
         }
     }
     /** Ported from Brightspace Bar's proven four-step Entra choreography. */
@@ -168,6 +237,22 @@ export class PurdueSSOFlow {
         }
         return false;
     }
+    /**
+     * True only when the password field is visible on two consecutive checks.
+     * Entra can transiently show a password-shaped control for a single
+     * instant while its email view is still initializing (documented next to
+     * awaitSilentSSO's `passwordPromptPolls` in browser-auth.ts); trusting one
+     * instantaneous observation can fill that decoy and click Next, leaving
+     * Entra's real password page never filled. A genuinely single-page IdP
+     * (Shibboleth portals such as USC's login.usc.edu) keeps the field on
+     * screen, so it survives the second check.
+     */
+    async hasCoVisiblePassword(page) {
+        if (!await this.anyVisible(page, PASSWORD_SELECTORS))
+            return false;
+        await page.waitForTimeout(FIELD_POLL_MS);
+        return await this.anyVisible(page, PASSWORD_SELECTORS);
+    }
     async hasPostCredentialChallenge(page) {
         return this.duoMfa.isChallenge(page) || await this.anyVisible(page, [
             NUMBER_MATCH_SELECTOR,
@@ -186,6 +271,20 @@ export class PurdueSSOFlow {
         let announced = null;
         /** True once onMfaChallenge has been told about this login, number or not. */
         let announcedToCaller = false;
+        /**
+         * The last number actually handed to onMfaChallenge. Distinct from
+         * `announced` (which only dedupes the WARN log): once the caller has been
+         * told about a number, a later DIFFERENT one — including a numberless
+         * announcement's first number — must reach onMfaChallenge again, even
+         * though `announced` already fires the log every time it changes.
+         */
+        let lastAnnouncedNumber = null;
+        /** True once a number has appeared at least once this login (Fix 2 below only reacts after one has). */
+        let sawNumber = false;
+        let resendCount = 0;
+        let resendLastClickAt = null;
+        let numberVanishedAt = null;
+        let resendNotFoundWarned = false;
         try {
             while (Date.now() < deadline) {
                 if (await this.duoMfa.handle(page))
@@ -193,6 +292,8 @@ export class PurdueSSOFlow {
                 if (await this.submitMfaCode(page))
                     challenged = true;
                 const number = await this.readNumberMatch(page);
+                if (number)
+                    sawNumber = true;
                 const challengeVisible = number !== null ||
                     await page.locator("#idDiv_SAOTCAS_Title").first().isVisible().catch(() => false) ||
                     await page.locator("#idDiv_SAOTCC_Title").first().isVisible().catch(() => false);
@@ -200,22 +301,50 @@ export class PurdueSSOFlow {
                     challenged = true;
                     log("WARN", "Waiting up to 5 minutes for Microsoft MFA approval on your device.");
                     this.config.onMfaChallenge?.(number);
-                    if (number)
-                        announcedToCaller = true;
+                    announcedToCaller = true;
+                    lastAnnouncedNumber = number;
                 }
                 if (number && number !== announced) {
                     announced = number;
                     log("WARN", `Number match: ${number}. Enter it in Microsoft Authenticator.`);
-                    if (!announcedToCaller) {
+                    if (!announcedToCaller || number !== lastAnnouncedNumber) {
                         announcedToCaller = true;
+                        lastAnnouncedNumber = number;
                         this.config.onMfaChallenge?.(number);
                     }
                 }
+                if (number) {
+                    numberVanishedAt = null;
+                    resendNotFoundWarned = false;
+                }
                 if (await this.isAuthenticated(page)) {
                     log("INFO", "Login successful - verified Brightspace home");
                     return;
                 }
+                // Fix 2: Entra's number-match request itself times out (or the user
+                // taps Deny) well before the 5-minute budget above. Once that has
+                // happened, ask Entra for another one instead of polling a dead
+                // request until MFA_TIMEOUT_MS; readNumberMatch on the next poll
+                // picks up the fresh number, and the re-announce logic above tells
+                // the caller about it.
+                if (sawNumber && number === null && new URL(page.url()).hostname === "login.microsoftonline.com") {
+                    if (numberVanishedAt === null)
+                        numberVanishedAt = Date.now();
+                    resendNotFoundWarned = await this.tryResendNumberMatch(page, {
+                        resendCount,
+                        resendLastClickAt,
+                        numberVanishedAt,
+                        resendNotFoundWarned,
+                        onResend: (clickedAt) => {
+                            resendCount += 1;
+                            resendLastClickAt = clickedAt;
+                        },
+                    });
+                }
                 await this.clickProvenKmsi(page);
+                // The federated-domain trust prompt arrives after the IdP succeeds, so
+                // it has to be caught by this loop rather than by enterCredentials.
+                await this.clickTrustPrompt(page);
                 await page.waitForTimeout(NUMBER_MATCH_POLL_MS);
             }
         }
@@ -230,6 +359,53 @@ export class PurdueSSOFlow {
             throw new MfaApprovalError(undefined, announced ?? undefined);
         throw new UnsupportedAuthenticationError("Sign-in did not reach a supported MFA challenge or Brightspace within 5 minutes.");
     }
+    /**
+     * Look for Entra's "send another request" affordance and click it, at most
+     * MAX_RESENDS times per login and never twice in immediate succession.
+     * Returns the (possibly updated) resendNotFoundWarned flag for the caller
+     * to carry into the next poll.
+     */
+    async tryResendNumberMatch(page, state) {
+        if (state.resendCount >= MAX_RESENDS)
+            return state.resendNotFoundWarned;
+        if (state.resendLastClickAt !== null && Date.now() - state.resendLastClickAt < RESEND_CLICK_GUARD_MS) {
+            return state.resendNotFoundWarned;
+        }
+        const control = await this.findResendControl(page);
+        if (!control) {
+            if (!state.resendNotFoundWarned && Date.now() - state.numberVanishedAt >= RESEND_NOT_FOUND_WARN_MS) {
+                log("WARN", "Number-match request appears to have expired or been denied, but no \"send another request\" control was found; continuing to wait.");
+                return true;
+            }
+            return state.resendNotFoundWarned;
+        }
+        const clickedAt = Date.now();
+        state.onResend(clickedAt);
+        log("WARN", `Number-match request expired; sent another request (${state.resendCount + 1} of ${MAX_RESENDS}).`);
+        await control.click().catch(() => { });
+        return state.resendNotFoundWarned;
+    }
+    /** Entra's resend control, matched by id first, then by a scoped text fallback. See the selector constants' own comments. */
+    async findResendControl(page) {
+        const byId = page.locator(RESEND_ID_SELECTOR).first();
+        if (await byId.isVisible().catch(() => false))
+            return byId;
+        for (const scopeSelector of RESEND_SCOPE_SELECTORS) {
+            const scope = page.locator(scopeSelector).first();
+            if (!await scope.isVisible().catch(() => false))
+                continue;
+            const candidates = await scope.getByText(RESEND_TEXT_PATTERN).all().catch(() => []);
+            for (const candidate of candidates) {
+                if (!await candidate.isVisible().catch(() => false))
+                    continue;
+                const text = (await candidate.textContent().catch(() => null)) ?? "";
+                if (RESEND_SWITCH_METHOD_PATTERN.test(text))
+                    continue;
+                return candidate;
+            }
+        }
+        return null;
+    }
     async submitMfaCode(page) {
         const input = await this.firstVisible(page, MFA_CODE_SELECTORS);
         if (!input)
@@ -301,6 +477,60 @@ export class PurdueSSOFlow {
             log("DEBUG", 'Clicked Yes on "Stay signed in?"');
         }
     }
+    /**
+     * Microsoft asks users of a federated domain to confirm they trust it ("Do
+     * you trust usc.edu?") before issuing the SAML assertion to Brightspace.
+     * Nothing proceeds until Continue is clicked, and a headless run has nobody
+     * to click it, so the flow parks on this page until the MFA deadline and
+     * the session is never established. This dialog is an anti-login-CSRF
+     * control, not a nuisance interstitial, so it is not enough to notice the
+     * text is present somewhere on the page (`page.getByText()` is a whole-page
+     * substring search, not a heading-scoped match) — the domain named in the
+     * prompt is parsed out and compared against the domain this login is
+     * actually signing into. A mismatch (e.g. the browser was steered to a
+     * different tenant's confirmation) is left unclicked; the existing 5-minute
+     * MFA timeout is the safe failure mode for that, same as any other
+     * unhandled prompt.
+     */
+    async clickTrustPrompt(page) {
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com")
+            return;
+        const prompt = page.getByText(/Do you trust/i).first();
+        if (!await prompt.isVisible().catch(() => false))
+            return;
+        const text = await prompt.textContent().catch(() => null);
+        const promptDomain = text ? this.extractTrustDomain(text) : null;
+        const expectedDomain = this.expectedTrustDomain();
+        if (!promptDomain || !expectedDomain || promptDomain !== expectedDomain) {
+            log("WARN", `Domain-trust prompt named "${promptDomain ?? "an unknown domain"}", which does not match the configured sign-in domain; not confirming trust automatically.`);
+            return;
+        }
+        const cont = page.getByRole("button", { name: /continue/i }).first();
+        if (!await cont.isVisible().catch(() => false))
+            return;
+        await cont.click().catch(() => { });
+        log("INFO", `Clicked Continue on Microsoft's domain-trust prompt for ${promptDomain}.`);
+    }
+    /** Pulls the domain Microsoft named out of "Do you trust <domain>?" text. */
+    extractTrustDomain(text) {
+        const match = text.match(/do you trust\s+([a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+)/i);
+        return match ? match[1].toLowerCase() : null;
+    }
+    /** The domain this login is actually signing into, to check the trust prompt against. */
+    expectedTrustDomain() {
+        if (this.config.username) {
+            const email = signInName(this.config.username, this.config.baseUrl);
+            const at = email.lastIndexOf("@");
+            if (at !== -1)
+                return email.slice(at + 1).toLowerCase();
+        }
+        // Purdue's own tenant is federated to purdue.edu regardless of what the
+        // configured username looks like.
+        if (this.config.baseUrl && new URL(this.config.baseUrl).hostname.toLowerCase() === "purdue.brightspace.com") {
+            return "purdue.edu";
+        }
+        return null;
+    }
     /** The digits on screen, or null when Entra is not showing any. */
     async readNumberMatch(page) {
         const sign = page.locator(NUMBER_MATCH_SELECTOR).first();

package/build/tools/tool-helpers.js

@@ -57,7 +57,8 @@ export function errorResponse(message) {
  * words in the response. The full error still goes to the log.
  */
 const AUTH_FAILURE_GUIDANCE = {
-    busy: "A sign-in is already running in another process. Let it finish, then try again.",
+    busy: "A sign-in is already running in another process. Let it finish, then try again, " +
+        `or run \`${AUTH_COMMAND}\` in a terminal to take over that background attempt.`,
     cooldown: "Automatic sign-in is paused because an MFA prompt went unanswered. " +
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to retry now and see the number to enter.`,
     unsupported: "This login needs something your AI client cannot supply, usually a code from an "

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.7.1",
+  "version": "3.7.3",
   "mcpName": "io.github.rohanmuppa/brightspace",
   "description": "MCP server for Brightspace (D2L). Check grades, due dates, assignments, announcements, syllabus, rosters and more via Claude, ChatGPT, Cursor, Windsurf, or any MCP client.",
   "type": "module",