brightspace-mcp-server 5.1.20 → 5.1.21

package/README.md

@@ -159,7 +159,7 @@ npx -y brightspace-mcp-server@latest auth
 
 **Want fewer 2FA prompts?** `setup` asks one question, "How often do you want to approve sign-ins on your phone?": **1** every time (default), **2** remember this computer, or **3** let this computer answer Microsoft's code requests itself (needs an authenticator setup key). Options 2 and 3 are opt-in and not for shared computers; to turn them off, rerun `setup` and pick 1. The tradeoffs and the steps for getting the key are in [docs/sign-in.md](docs/sign-in.md#fewer-2fa-prompts).
 
-**To sign out early** (on a shared computer, say), just ask your AI app to sign you out of Brightspace, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal. It deletes this computer's saved Brightspace session, so the next question does a full sign-in. Your saved password, authenticator key, and settings are kept, so with a saved authenticator key that sign-in can finish without you; on a shared computer, also delete the saved `brightspace-mcp-server` entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows). Other AI apps open on this computer are signed out too and will ask you to sign in on their next question. (An app you opened before updating may keep answering for up to an hour; quit and reopen it to sign it out right away.) It only clears this computer; it does not sign you out of Microsoft or Brightspace anywhere else. If a sign-in is in progress, it refuses and deletes nothing.
+**To sign out early** (on a shared computer, say), just ask your AI app to sign you out of Brightspace, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal. It deletes this computer's saved Brightspace session, so the next question does a full sign-in. Your saved password, authenticator key, and settings are kept, so with a saved authenticator key that sign-in can finish without you; on a shared computer, also delete the saved `brightspace-mcp-server` entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows). Other AI apps open on this computer are signed out too and will ask you to sign in on their next question. (An app you opened before updating may keep answering for up to an hour; quit and reopen it to sign it out right away.) It only clears this computer; it does not sign you out of Microsoft or Brightspace anywhere else. Asking your AI app also cancels a sign-in still waiting for you to approve it; the `auth --logout` command instead refuses and deletes nothing while a sign-in is in progress. Cancelling doesn't get you a new prompt any sooner: Microsoft won't send another until the earlier one expires, up to 5 minutes after it was sent.
 
 How often you're asked is up to your school, not this tool. Everything else about sign-in — Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) — is in [docs/sign-in.md](docs/sign-in.md).
 

package/build/auth/auth-lock.js

@@ -116,6 +116,17 @@ export async function inspectLockOwner(lockPath) {
         return undefined;
     return { mode: owner.mode === "automatic" ? "automatic" : "explicit", gone: lockOps.isDead(owner) };
 }
+/**
+ * The PID of a live "automatic" owner (a background AuthRunner child), or
+ * undefined when the lock is free, its owner is gone, or it is held some other
+ * way. Used by sign_out to cancel another app's waiting sign-in.
+ */
+export async function liveAutomaticOwner(lockPath) {
+    const owner = await readOwner(lockPath);
+    if (!owner || owner.mode !== "automatic" || lockOps.isDead(owner))
+        return undefined;
+    return owner.pid;
+}
 /** Remove only our fixed metadata names, after the directory was retired. */
 async function cleanRetired(lockPath) {
     await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });

package/build/auth/auth-runner.js

@@ -13,8 +13,8 @@ import { AUTH_COMMAND } from "../utils/commands.js";
 import { dependencyRepairHint, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
 import { devActivity, newRecoveryId, RECOVERY_ID_ENV } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
-import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
-import { inspectLockOwner } from "./auth-lock.js";
+import { AUTOMATIC_PENDING_MARKER, MFA_HELD_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
+import { inspectLockOwner, liveAutomaticOwner } from "./auth-lock.js";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
@@ -134,6 +134,14 @@ function mfaPendingFailure(numberMatch) {
  * send the user looking for a prompt that will never arrive.
  */
 const automaticPendingFailure = (relayed = false) => new AuthProcessError("automaticPending", "Sign-in is entering its own verification code in the background. Try again.", undefined, false, relayed);
+/**
+ * Microsoft is refusing a new prompt for the account until an earlier one
+ * expires. Nothing is on the user's phone to approve, and calling again does
+ * not help sooner, so it is neither "approve now" nor "still starting".
+ */
+const mfaHeldFailure = () => new AuthProcessError("mfaHeld", "Microsoft is holding a new prompt until an earlier one expires. Try again in a minute.");
+/** What every caller of a sign-in that was stopped from outside (sign_out, a kill) is answered. */
+const cancelledFailure = (relayed = false) => new AuthProcessError("cancelled", "The sign-in was cancelled before it finished.", undefined, false, relayed);
 export class AuthProcessError extends AuthError {
     kind;
     numberMatch;
@@ -200,6 +208,80 @@ function descendantPids(parentPid) {
     visit(parentPid);
     return descendants;
 }
+/**
+ * SIGKILL a sign-in child, its Chromium descendants and its process group.
+ * SIGKILL rather than SIGTERM: a graceful stop runs the MFA loop's failure
+ * path, which records the cooldown, and the user never had a chance to answer.
+ */
+function forceStop(pid) {
+    if (process.platform === "win32") {
+        try {
+            execFileSync("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", timeout: 5000 });
+        }
+        catch { /* Already exited. */ }
+        return;
+    }
+    try {
+        for (const descendant of descendantPids(pid)) {
+            try {
+                process.kill(descendant, "SIGKILL");
+            }
+            catch { /* Already exited. */ }
+        }
+    }
+    catch { /* Still terminate the owned process group if ps is unavailable. */ }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch { /* Not a group leader, or gone. */ }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch { /* Already exited. */ }
+}
+/** How long a cancel waits for a stopped sign-in to actually exit. */
+const CANCEL_WAIT_MS = 5000;
+/**
+ * Stop a background sign-in that ANOTHER server process on this computer
+ * started and that holds the cross-process lock, so sign_out can cancel a
+ * sign-in whichever app began it. Only an "automatic" owner is stopped (a
+ * person's `auth` run in a terminal never is), and only after its command
+ * line confirms it is this package's sign-in child: the PID comes from a file,
+ * and a PID the system has since reused must never be killed. That check
+ * needs ps, so on Windows nothing is stopped and sign_out reports the sign-in
+ * as one it cannot cancel. Its own server's waiting calls are answered
+ * "cancelled" (see the close handler in spawnAuth). The dead owner leaves a
+ * stale lock the next lock holder reclaims. Resolves true once it has exited.
+ */
+export async function stopAutomaticSignIn(lockPath) {
+    if (process.platform === "win32")
+        return false;
+    const pid = await liveAutomaticOwner(lockPath);
+    if (pid === undefined)
+        return false;
+    let command = "";
+    try {
+        command = execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 1000 });
+    }
+    catch {
+        return false;
+    }
+    if (!/auth-cli\.js\b/.test(command) || !command.includes("--automatic"))
+        return false;
+    log("WARN", `Cancelling another app's background sign-in (pid ${pid}) for sign_out`);
+    forceStop(pid);
+    const deadline = Date.now() + CANCEL_WAIT_MS;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return false;
+}
 /**
  * Forward a child stream to the server log, one line at a time.
  *
@@ -322,6 +404,8 @@ export class AuthRunner {
      * which can linger for seconds after it has said everything it will say.
      */
     relayProbe = null;
+    /** Stops the current child and resolves once it has exited; null between children. */
+    cancelChild = null;
     scriptPath;
     timeoutMs;
     onProgress;
@@ -344,6 +428,22 @@ export class AuthRunner {
     busy() {
         return this.inFlight !== null || this.childDone !== null;
     }
+    /**
+     * Cancel this process's sign-in, if one is running: stop the child at once
+     * (no MFA cooldown is recorded, see forceStop) and answer every call waiting
+     * on it, here or behind the shared HTTP server, with a "cancelled" error
+     * instead of leaving it to time out. The next call starts a new sign-in and
+     * sends a new prompt. Resolves true once the child has exited, so the
+     * cross-process lock it held is reclaimable; false when nothing was running.
+     */
+    async cancel() {
+        const cancelChild = this.cancelChild;
+        if (!cancelChild)
+            return false;
+        log("INFO", "Cancelling the background sign-in for sign_out");
+        await cancelChild();
+        return true;
+    }
     /**
      * Authenticate, joining the login this process already started if there is
      * one. Returns true on success and throws a useful error on failure.
@@ -547,10 +647,11 @@ export class AuthRunner {
                 this.relayTold.clear();
                 return true;
             }
-            // The owner died without releasing its lock. Waiting longer only runs
-            // the clock down; the next call's sign-in reclaims the dead lock.
+            // The owner died without releasing its lock: cancelled (sign_out) or
+            // crashed. Waiting longer only runs the clock down; the next call's
+            // sign-in reclaims the dead lock.
             if ((await inspectLockOwner(lockPath))?.gone)
-                throw new AuthProcessError("inProgress", STILL_SIGNING_IN);
+                throw cancelledFailure(true);
             const relayed = await relayChallenge(lockPath);
             if (relayed) {
                 const next = relayed.kind === "automatic"
@@ -664,6 +765,10 @@ export class AuthRunner {
                     reject(automaticPendingFailure());
                     return;
                 }
+                if (pending?.kind === "mfaHeld") {
+                    reject(mfaHeldFailure());
+                    return;
+                }
                 const numberMatch = this.pendingChallenge?.numberMatch ?? challenge?.numberMatch;
                 reject(new AuthProcessError(...mfaPendingFailure(numberMatch), numberMatch));
             }, graceMs);
@@ -725,6 +830,8 @@ export class AuthRunner {
             let relayed = false;
             /** The child reported it is answering its own code (see the marker below). */
             let automaticSeen = false;
+            /** Microsoft held back a new prompt at some point in this sign-in (MFA_HELD_MARKER). */
+            let heldSeen = false;
             /** watchAttention is armed once per child; a second timer could kill a live sign-in. */
             let attentionWatched = false;
             let abandonTimer;
@@ -759,6 +866,7 @@ export class AuthRunner {
             };
             const onExit = () => kill("SIGTERM");
             process.once("exit", onExit);
+            const exited = new Promise((resolve) => child.once("exit", () => resolve()));
             const settleCaller = (error) => {
                 if (callerSettled)
                     return;
@@ -788,10 +896,21 @@ export class AuthRunner {
                     this.challengeTold = null;
                     this.challengeToldKey = null;
                     this.relayProbe = null;
+                    this.cancelChild = null;
                 }
             });
             trackedCompletion.catch(() => { });
             this.childDone = trackedCompletion;
+            this.cancelChild = async () => {
+                if (!childFinished) {
+                    if (child.pid)
+                        forceStop(child.pid);
+                    else
+                        child.kill("SIGKILL");
+                    finishChild(cancelledFailure());
+                }
+                await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, CANCEL_WAIT_MS).unref?.())]);
+            };
             this.pendingChallenge = null;
             this.challengeToldKey = null;
             this.relayProbe = null;
@@ -831,7 +950,9 @@ export class AuthRunner {
                 // An automatic sign-in that later shows a real approval challenge (it
                 // fell back, or Entra changed its mind) must be upgraded, so a joiner
                 // is told the number instead of "still working".
-                const firstChallenge = this.pendingChallenge === null || this.pendingChallenge.kind === "automaticPending";
+                // A hold is replaced by any real challenge, numbered or not.
+                const firstChallenge = this.pendingChallenge === null || this.pendingChallenge.kind === "automaticPending" ||
+                    this.pendingChallenge.kind === "mfaHeld";
                 startWatching();
                 if (firstChallenge)
                     devActivity("mfa_observed", { elapsedMs: Date.now() - started, recoveryId });
@@ -868,6 +989,20 @@ export class AuthRunner {
                     this.relayProbe = answer;
                 settleCaller(answer);
             };
+            /**
+             * Microsoft refused a new prompt while an earlier one is open. Answer
+             * the waiting caller now with the real wait; a number that appears
+             * later replaces this (it is published like any challenge).
+             */
+            const publishHeld = () => {
+                heldSeen = true;
+                if (this.pendingChallenge?.kind === "mfaPending")
+                    return;
+                this.pendingChallenge = { kind: "mfaHeld" };
+                startWatching();
+                resolveChallengeSignal();
+                settleCaller(mfaHeldFailure());
+            };
             // Runs once the child is actually done. Settles the caller too, if an
             // early answer had not already done so; otherwise this is just the
             // background sign-in finishing, which only childDone's joiner sees.
@@ -929,6 +1064,9 @@ export class AuthRunner {
                 else if (line === AUTOMATIC_PENDING_MARKER) {
                     publishAutomaticProgress();
                 }
+                else if (line === MFA_HELD_MARKER) {
+                    publishHeld();
+                }
                 else if (line === RELAYED_CHALLENGE_MARKER) {
                     // Recorded as the line is read, so it is set before the challenge
                     // marker that follows it settles the caller.
@@ -957,10 +1095,16 @@ export class AuthRunner {
                 kill("SIGKILL");
                 finishChild(new AuthProcessError("failed", `Could not start authentication. Run ${AUTH_COMMAND} for details.`));
             });
-            child.on("close", (code) => {
+            child.on("close", (code, signal) => {
                 if (childFinished)
                     return;
-                if (timedOut) {
+                if (!timedOut && signal === "SIGKILL") {
+                    // Stopped from outside this process: another app's sign_out (see
+                    // stopAutomaticSignIn), or someone killed it. Either way it will not
+                    // finish, and the next call starts a new sign-in.
+                    finishChild(cancelledFailure());
+                }
+                else if (timedOut) {
                     kill("SIGKILL");
                     finishChild(new AuthProcessError("timeout", `Authentication timed out. Run ${AUTH_COMMAND} to try again.`));
                 }
@@ -994,6 +1138,10 @@ export class AuthRunner {
                     // challenge yet: the caller can wait on it (see attendRelay).
                     else if (code === 2 && relayed && this.sessionDir)
                         failures[2] = ["inProgress", STILL_SIGNING_IN];
+                    // Unsupported only because Microsoft held every new prompt until
+                    // this sign-in ran out of time: the next call starts a fresh one.
+                    if (code === 4 && heldSeen)
+                        failures[4] = ["mfaHeld", mfaHeldFailure().message];
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
                     const challenged = kind === "mfaPending" || kind === "automaticPending" || kind === "inProgress";

package/build/auth/browser-auth.js

@@ -84,7 +84,12 @@ export class BrowserAuth {
                 onAutomaticPending?.();
             }
             catch { /* Reporting must not interrupt authentication. */ }
-        });
+        }, options.onMfaHeld && (() => {
+            try {
+                options.onMfaHeld?.();
+            }
+            catch { /* Reporting must not interrupt authentication. */ }
+        }));
         this.stateStore = new BrowserStateStore(config.sessionDir);
         this.cooldown = new AuthCooldown(config.sessionDir);
     }

package/build/auth/mfa-challenge.js

@@ -77,6 +77,11 @@ export function challengeRelayedAt(lockPath) {
  * beside challengeMarker so the child and AuthRunner cannot drift apart.
  */
 export const AUTOMATIC_PENDING_MARKER = "AUTH_AUTOMATIC_PENDING";
+/**
+ * The child reports that Microsoft is refusing to send a new prompt because an
+ * earlier one for the account is still open (see PurdueSSOFlow's onMfaHeld).
+ */
+export const MFA_HELD_MARKER = "AUTH_MFA_HELD";
 /**
  * Printed on the line before a challenge marker when the challenge is another
  * process's, relayed from the lock directory, rather than this child's own.

package/build/auth/purdue-sso.js

@@ -120,6 +120,31 @@ const CODE_METHOD_STEPS = [
     ["code", /^use a verification code$/i],
     ["other", /^(?:I can.t use my .+ right now|sign in another way|use a different verification option)$/i],
 ];
+/**
+ * Entra's "Verify your identity" heading when it refuses a new prompt: an
+ * earlier prompt for the account is still open (BeginAuth answers
+ * UserAuthFailedDuplicateRequest, error 500121), whether it was missed or its
+ * sign-in was cancelled. It lasts until that prompt expires, up to 5 minutes
+ * after it was sent. Seen live on Purdue's tenant on 2026-10-25, where asking
+ * the list for another Authenticator request during the hold was refused the
+ * same way (see HELD_RETRY_MS for asking again once it may have ended).
+ */
+const MFA_HELD_TEXT = /having trouble verifying your account/i;
+/**
+ * While Microsoft holds the account, ask it again through the list's
+ * Authenticator option this often. A request made during the hold is refused
+ * and sends nothing to the phone; the first one after the earlier prompt
+ * expires sends exactly one new prompt, whose number ends the hold here.
+ * Without this the page never changes and the login waits out its own 5
+ * minutes after Microsoft would already have sent a new prompt.
+ */
+const HELD_RETRY_MS = 60_000;
+/** Enough tries to outlast a 5-minute hold, and no more. */
+const MAX_HELD_RETRIES = 6;
+const PUSH_METHOD_SELECTOR = '[data-value="PhoneAppNotification"]';
+const PUSH_METHOD_LABEL = /^approve a request on my microsoft authenticator app$/i;
+/** Short, so a list that changes under the click cannot hold the loop for Playwright's 30 s default. */
+const PUSH_CLICK_TIMEOUT_MS = 5000;
 /** Let Entra re-render the method page before the loop looks at it again. */
 const METHOD_SWITCH_SETTLE_MS = 500;
 /**
@@ -389,6 +414,11 @@ export class PurdueSSOFlow {
         const startedAt = Date.now();
         const deadline = startedAt + MFA_TIMEOUT_MS;
         let challenged = false;
+        /** True once onMfaHeld has reported this login. */
+        let heldReported = false;
+        /** Requests made through the held list, and when the last one was made. */
+        let heldRetries = 0;
+        let heldRetryAt = 0;
         /**
          * True once this login has told the user to go approve something. Only
          * then is a timeout really a missed approval; an automatic code sign-in
@@ -481,6 +511,24 @@ export class PurdueSSOFlow {
                     await page.locator("#idDiv_SAOTCAS_Title").first().isVisible().catch(() => false) ||
                     await page.locator("#idDiv_SAOTCC_Title").first().isVisible().catch(() => false) ||
                     await this.anyVisible(page, PASSWORDLESS_APPROVAL_SELECTORS);
+                // Microsoft refusing a new prompt while an earlier one is still open:
+                // tell the caller how long that lasts instead of "still starting".
+                if (manualRequired && !challengeVisible && await this.isHeldByMicrosoft(page)) {
+                    if (!heldReported) {
+                        heldReported = true;
+                        heldRetryAt = Date.now();
+                        log("WARN", "Microsoft is holding back a new prompt until an earlier one for this account expires (up to 5 minutes after it was sent).");
+                        this.config.onMfaHeld?.();
+                    }
+                    else if (!sawNumber && heldRetries < MAX_HELD_RETRIES && Date.now() - heldRetryAt >= HELD_RETRY_MS) {
+                        heldRetryAt = Date.now();
+                        if (await this.requestPromptFromHeldList(page)) {
+                            heldRetries += 1;
+                            await page.waitForTimeout(METHOD_SWITCH_SETTLE_MS);
+                            continue;
+                        }
+                    }
+                }
                 // Entra showed a challenge but never a way to type a code. Stop
                 // waiting for one and fall back to the announce-and-approve path this
                 // flow has always used, rather than polling a dead page for 5 minutes.
@@ -739,6 +787,49 @@ export class PurdueSSOFlow {
         }
         return "noSwitch";
     }
+    /**
+     * Ask the held list for an Authenticator prompt (see HELD_RETRY_MS). Only
+     * when Microsoft's page names the configured account, so a held list for
+     * someone else never sends that person a prompt.
+     */
+    async requestPromptFromHeldList(page) {
+        const tile = page.locator(PUSH_METHOD_SELECTOR).first();
+        const control = await tile.isVisible().catch(() => false) ? tile : page.getByText(PUSH_METHOD_LABEL).first();
+        if (!await control.isVisible().catch(() => false))
+            return false;
+        if (!await this.showsConfiguredAccount(page))
+            return false;
+        log("INFO", "Asking Microsoft again for an Authenticator prompt.");
+        await control.click({ timeout: PUSH_CLICK_TIMEOUT_MS }).catch(() => { });
+        devActivity("mfa_method_selected");
+        return true;
+    }
+    /**
+     * True only when this is Microsoft's own sign-in page and one of its account
+     * labels names the configured account. Stricter than
+     * assertExpectedMicrosoftAccount, which lets a page with no label through.
+     */
+    async showsConfiguredAccount(page) {
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com" || !this.config.username)
+            return false;
+        const expected = signInName(this.config.username, this.config.baseUrl).toLowerCase();
+        for (const selector of ACCOUNT_LABEL_SELECTORS) {
+            const account = page.locator(selector).first();
+            if (await account.count().catch(() => 0) === 0)
+                continue;
+            const value = await account.textContent({ timeout: 1000 }).catch(() => null);
+            const shown = value?.match(/[\w.+-]+@[\w.-]+\.[a-z]{2,}/i)?.[0]?.toLowerCase();
+            if (shown)
+                return shown === expected;
+        }
+        return false;
+    }
+    /** Microsoft's own sign-in page refusing a new prompt; see MFA_HELD_TEXT. */
+    async isHeldByMicrosoft(page) {
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com")
+            return false;
+        return await page.getByText(MFA_HELD_TEXT).first().isVisible().catch(() => false);
+    }
     /**
      * Refuse to drive Entra's method pages, or type a code into them, unless
      * this really is Microsoft showing the account we are signing in as. A code

package/build/auth/sso-flow.js

@@ -49,7 +49,7 @@ export class MfaApprovalError extends BrowserAuthError {
  * else uses the default flow, which already covers the common Shibboleth,
  * CAS, and Microsoft Entra forms.
  */
-export function createSSOFlow(config, requestMfaCode, onMfaChallenge, onAutomaticPending) {
+export function createSSOFlow(config, requestMfaCode, onMfaChallenge, onAutomaticPending, onMfaHeld) {
     const credentials = {
         username: config.username,
         password: config.password,
@@ -67,6 +67,7 @@ export function createSSOFlow(config, requestMfaCode, onMfaChallenge, onAutomati
         requestMfaCode,
         onMfaChallenge,
         onAutomaticPending,
+        onMfaHeld,
     };
     if (isTUDelftBrightspace(config.baseUrl)) {
         return new TUDelftSSOFlow(credentials);

package/build/auth-cli.js

@@ -12,7 +12,7 @@ import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
 import { formatPhaseMarker } from "./auth/auth-phases.js";
 import { AuthenticationInProgressError } from "./auth/auth-lock.js";
-import { AUTOMATIC_PENDING_MARKER, challengeMarker, relayedLockLines } from "./auth/mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, MFA_HELD_MARKER, challengeMarker, relayedLockLines } from "./auth/mfa-challenge.js";
 import { runLogout } from "./auth/logout.js";
 import { configureDevActivity } from "./utils/dev-activity.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
@@ -88,7 +88,10 @@ async function main() {
         const onAutomaticPending = automatic
             ? () => console.log(AUTOMATIC_PENDING_MARKER)
             : undefined;
-        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase, onAutomaticPending }).authenticate({
+        // Microsoft refused a new prompt until an earlier one expires: the parent
+        // says so instead of "still starting". A terminal run reads the log line.
+        const onMfaHeld = automatic ? () => console.log(MFA_HELD_MARKER) : undefined;
+        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase, onAutomaticPending, onMfaHeld }).authenticate({
             automatic,
             onAuthenticated: async (token) => {
                 await tokenManager.setToken(token);

package/build/tools/sign-out.js

@@ -3,8 +3,10 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import { stopAutomaticSignIn } from "../auth/auth-runner.js";
 import { AuthenticationInProgressError } from "../auth/auth-lock.js";
 import { clearSavedSession, RemoveError } from "../auth/logout.js";
+import { authLockPath } from "../auth/mfa-challenge.js";
 import { log } from "../utils/logger.js";
 import { SignOutSchema } from "./schemas.js";
 import { withUpdateNotice } from "./tool-helpers.js";
@@ -12,8 +14,11 @@ const KEPT = "Kept (if you set them up): your saved password, your settings, and
 const OTHER_APPS = "Other Brightspace apps open on this computer are signed out too and will sign in again from scratch on their next question. An app you opened before updating to this version may keep answering for up to an hour; quit and reopen it to sign it out right away.";
 const NEXT_SIGN_IN = "Because your saved password (and authenticator key, if you saved one) stay on this computer, that next sign-in may just ask you to approve it, or finish on its own if you saved an authenticator key. On a shared computer, also delete the saved \"brightspace-mcp-server\" entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows).";
 const LOCAL_ONLY = "This only clears this computer. It does not sign you out of Microsoft or Brightspace on other devices.";
-const IN_PROGRESS = "Not signed out: a sign-in is in progress on this computer, so nothing was deleted. If you don't want to sign in, don't approve the prompt. Tell the user to ask again after the sign-in finishes or times out; do not call sign_out again on your own.";
+const IN_PROGRESS = "Not signed out: a sign-in that sign_out can't cancel is in progress on this computer (one started in a terminal with `auth`, for example), so nothing was deleted and it was left running. Tell the user to finish or close that sign-in, then ask again; do not call sign_out again on your own.";
+const CANCELLED = "Cancelled the Brightspace sign-in that was waiting for approval, so the prompt or number from it no longer works.";
+const NEXT_QUESTION = "Microsoft keeps that prompt open for up to 5 minutes after sending it and sends this account no other until then, so the next Brightspace question can take that long to show a new number to approve.";
 const ALREADY_SIGNED_OUT = "You're already signed out of Brightspace on this computer; there was no saved session to remove.";
+const NOTHING_SAVED = "There was no saved session to remove.";
 const UNEXPECTED_FAILURE = "Could not clear the saved session because of an unexpected error. Nothing more was changed; try again, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal to see the details.";
 function text(message, isError = false) {
     const result = withUpdateNotice([{ type: "text", text: message }]);
@@ -22,47 +27,58 @@ function text(message, isError = false) {
 /**
  * Register sign_out tool.
  *
- * The in-chat version of `auth --logout`: it deletes this computer's saved
+ * The in-chat version of `auth --logout`, plus one thing the command does not
+ * do: it first cancels a background sign-in still waiting on MFA, this
+ * server's (AuthRunner.cancel, which answers every call waiting on it) or
+ * another app's on this computer (stopAutomaticSignIn). A user who missed the
+ * prompt otherwise waited out its 5-minute window for a new one. Then it
+ * deletes this computer's saved
  * session for the account the server is configured with (clearSavedSession,
  * under the sign-in lock, so a running sign-in is never disturbed), then
  * empties the API client's response cache and this process's in-memory token
  * so it serves nothing from the session it just signed out of. Answers are
- * plain text, not JSON. A sign-in in progress and an env-supplied credential
- * are ordinary answers rather than errors, so a model has no reason to retry
- * in a loop; only a file that could not be deleted is reported as a failure.
+ * plain text, not JSON. A sign-in it cannot cancel (a person's `auth` run)
+ * and an env-supplied credential are ordinary answers rather than errors, so
+ * a model has no reason to retry in a loop; only a file that could not be
+ * deleted is reported as a failure.
  *
  * authRunner covers the moment between this server spawning a sign-in and
  * that child taking the cross-process lock, when the lock alone still looks
  * free. It is absent when the server uses a pasted credential (no runner).
  *
- * clear is an injection seam: tests point it at a temporary directory.
+ * clear and stopElsewhere are injection seams for tests.
  */
-export function registerSignOut(server, config, apiClient, tokenManager, authRunner, clear = clearSavedSession) {
+export function registerSignOut(server, config, apiClient, tokenManager, authRunner, clear = clearSavedSession, stopElsewhere = (dir) => stopAutomaticSignIn(authLockPath(dir))) {
     server.registerTool("sign_out", {
         title: "Sign Out of Brightspace",
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-        description: "Sign out of Brightspace on this computer: delete the saved Brightspace session, so every Brightspace app here must sign in again from scratch on its next question. Keeps the saved password, settings, and authenticator key. Does not sign out of Microsoft or Brightspace on other devices. Call this ONLY when the user explicitly asks to sign out or log out of Brightspace (a shared computer, handing the machine on). Never call it to fix an error, never as part of answering another question, and never to retry or refresh a sign-in.",
+        description: "Sign out of Brightspace on this computer: cancel any sign-in still waiting for MFA approval here, then delete the saved Brightspace session, so every Brightspace app here must sign in again from scratch on its next question. Keeps the saved password, settings, and authenticator key. Does not sign out of Microsoft or Brightspace on other devices. Cancelling a waiting sign-in doesn't get a new prompt sooner: Microsoft sends no other prompt to the account until the one already sent expires, up to 5 minutes after it was sent. Call this ONLY when the user explicitly asks to sign out or log out of Brightspace (a shared computer, handing the machine on). Never call it on your own to fix an error, to get a new prompt, or as part of answering another question.",
         inputSchema: SignOutSchema,
     }, async () => {
         if (config.envAccessToken || config.envSessionCookie) {
             return text("Nothing was signed out. This server uses a credential from its configuration (D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE, set in your AI app's client configuration or a .env file), and sign_out cannot remove that. To stop using it, remove that setting and restart the app.");
         }
-        if (authRunner?.busy())
-            return text(IN_PROGRESS);
         const dropInMemory = () => {
             apiClient.clearCache();
             tokenManager.forgetSession();
         };
         try {
+            // This server's own sign-in first: stopping it also answers its waiting calls.
+            let cancelled = (await authRunner?.cancel()) ?? false;
+            if (await stopElsewhere(config.sessionDir))
+                cancelled = true;
             const { removed } = await clear(config.sessionDir);
             dropInMemory();
-            if (removed.length === 0)
-                return text(ALREADY_SIGNED_OUT);
+            if (removed.length === 0) {
+                return text(cancelled ? [CANCELLED, NOTHING_SAVED, NEXT_QUESTION].join("\n") : ALREADY_SIGNED_OUT);
+            }
             return text([
+                ...(cancelled ? [CANCELLED] : []),
                 "Signed out of Brightspace on this computer.",
                 `Removed: ${removed.join(", ")}`,
                 KEPT,
                 OTHER_APPS,
+                ...(cancelled ? [NEXT_QUESTION] : []),
                 NEXT_SIGN_IN,
                 LOCAL_ONLY,
             ].join("\n"));

package/build/tools/tool-helpers.js

@@ -94,13 +94,36 @@ export function errorResponse(message, kind) {
  */
 const MFA_SOLO_CALL = "Don't run other Brightspace calls in parallel until the sign-in completes: a batched " +
     "answer can reach the user too late to approve. Make one call at a time.";
+/**
+ * What a retry does to the prompt on the user's phone. Without this a model
+ * filled the gap itself, telling a user that a call timing out would make the
+ * server send a new push: the retry joins the background sign-in instead, and
+ * only a sign-in that is cancelled (sign_out) or left alone for ABANDON_MS
+ * (auth-runner.ts) is replaced.
+ */
+const MFA_SAME_PROMPT = "Calling again doesn't send a new prompt, and neither does a call timing out: the sign-in " +
+    "keeps waiting, for up to 5 minutes, on the prompt already sent.";
+/** Entra number match only: purdue-sso.ts asks for another request when one expires or is denied. */
+const MFA_NEW_NUMBER = "If Microsoft's number expires or is denied, the sign-in asks Microsoft for a new one by itself " +
+    "and the next answer shows it; always give the user the latest number.";
+/**
+ * Why a missed prompt cannot be skipped. Microsoft keeps a prompt open for up
+ * to 5 minutes and refuses another for the same account until then
+ * (UserAuthFailedDuplicateRequest, seen live on Purdue's tenant 2026-10-25),
+ * so cancelling the sign-in only throws away the one that could finish.
+ */
+const MFA_NO_FASTER = "Cancelling the sign-in (sign_out) doesn't get one sooner: Microsoft sends no other prompt to " +
+    "this account until the one already sent expires, up to 5 minutes after it was sent.";
 const AUTH_FAILURE_GUIDANCE = {
     browserInstall: PLAYWRIGHT_INSTALL_HINT,
     dependencyMissing: dependencyRepairHint(),
     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.`,
+    cooldown: "Automatic sign-in is paused because an MFA prompt went unanswered; the pause ends 5 minutes " +
+        "after that prompt was missed. Until then " +
+        "calls send no prompt and return this message; after that, the next call starts a new sign-in " +
+        "and sends a new prompt. " +
+        `To sign in now, run \`${AUTH_COMMAND}\` in a terminal (from your home folder); it shows the number to enter.`,
     unsupported: "This login needs something your AI client cannot supply, usually a code from an "
         + "authenticator app. " +
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) and sign in there.`,
@@ -108,7 +131,8 @@ const AUTH_FAILURE_GUIDANCE = {
         "password could not be read. Unlock your keychain or keyring, then try again.",
     transport: "Brightspace could not be reached to sign in. The saved session was kept. " +
         "Check your connection and try again in a few minutes.",
-    timeout: "The sign-in did not finish in time, usually a missed MFA prompt. " +
+    timeout: "The sign-in did not finish in time, usually a missed MFA prompt, and has stopped: the prompt it " +
+        "sent no longer works. The next call starts a new sign-in, or says automatic sign-in is paused. " +
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to complete it with the number visible.`,
     failed: `The sign-in did not complete. Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to see why, ` +
         "or `brightspace-setup` if your saved school or username is wrong.",
@@ -122,11 +146,22 @@ const AUTH_FAILURE_GUIDANCE = {
         "again right away without waiting for them to " +
         "confirm: each call waits up to 45 seconds for the approval and returns the result as soon " +
         "as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
-        MFA_SOLO_CALL,
+        `${MFA_SAME_PROMPT} ${MFA_NO_FASTER} ${MFA_SOLO_CALL}`,
+    cancelled: "The sign-in was cancelled before it finished (by sign_out, or its process was stopped), so " +
+        "the prompt or number from it no longer works. Calling this tool again starts a new sign-in. " +
+        "Microsoft keeps the cancelled prompt open for up to 5 minutes after sending it and sends this " +
+        "account no other until then, so a new number can take that long; give the user the new number " +
+        "when an answer carries one.",
+    mfaHeld: "Microsoft is still holding an earlier sign-in prompt for this account (one that was missed, or " +
+        "whose sign-in was cancelled) and won't send a new prompt until that one expires, up to 5 minutes " +
+        "after it was sent. There is nothing to approve right now, and the earlier number no longer works. " +
+        "The sign-in asks Microsoft again every minute. Tell the user that, then call this tool again " +
+        "right away: each call waits up to 45 seconds and returns the new number as soon as Microsoft " +
+        "sends it. If a prompt the user didn't start shows on their phone, they should deny it.",
     inProgress: "Brightspace sign-in is still starting in the background (opening the browser and the " +
         "school's login pages). Call this tool again right away: the next call picks up that " +
-        "sign-in and returns the number to approve as soon as one appears. Don't ask the user to " +
-        "do anything yet.",
+        "sign-in and returns the number to approve as soon as one appears. No prompt has been sent " +
+        "yet, and calling again doesn't start a second sign-in. Don't ask the user to do anything yet.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`
@@ -167,7 +202,7 @@ function mfaPendingMessage(error) {
             "tool again right away without waiting for them " +
             "to confirm: each call waits up to 45 seconds for the approval and returns the result as " +
             "soon as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
-            MFA_SOLO_CALL;
+            `${MFA_SAME_PROMPT} ${MFA_NEW_NUMBER} ${MFA_NO_FASTER} ${MFA_SOLO_CALL}`;
     }
     return AUTH_FAILURE_GUIDANCE[error.kind];
 }

package/build/utils/dev-activity.js

@@ -103,7 +103,7 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     if (["success", "error", "sessionExpired", "transport"].includes(fields.outcome ?? ""))
         record.outcome = fields.outcome;
     if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending",
-        "automaticPending", "inProgress"].includes(fields.reason ?? ""))
+        "automaticPending", "inProgress", "mfaHeld"].includes(fields.reason ?? ""))
         record.reason = fields.reason;
     if (AUTH_PHASES.includes(fields.phase ?? ""))
         record.phase = fields.phase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "5.1.20",
+  "version": "5.1.21",
   "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",