brightspace-mcp-server 3.7.2 → 3.7.3

package/README.md

@@ -105,6 +105,8 @@ 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

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

@@ -68,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

@@ -62,6 +62,8 @@ export class DuoMfaHandler {
     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;
     }
@@ -147,14 +149,15 @@ export class DuoMfaHandler {
             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);
             }
         }

package/build/auth/purdue-sso.js

@@ -28,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";
@@ -229,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))
@@ -236,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);
@@ -243,21 +301,46 @@ 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.
@@ -276,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)

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.2",
+  "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",