brightspace-mcp-server 3.11.12 → 3.11.13

package/build/auth/auth-lock.js

@@ -38,8 +38,15 @@ async function renameThroughContention(from, to) {
     }
     return false;
 }
+/**
+ * The MFA challenge the lock owner's sign-in is showing, published inside the
+ * lock directory so it lives and dies with the lock (see mfa-challenge.ts).
+ */
+export const CHALLENGE_FILE = "challenge.json";
 export class AuthenticationInProgressError extends Error {
     code = "AUTH_IN_PROGRESS";
+    /** The owner's MFA challenge, when the caller looked it up (see BrowserAuth.authenticate). */
+    challenge;
     constructor() {
         super("Authentication already in progress. Retry after the current authentication finishes.");
         this.name = "AuthenticationInProgressError";
@@ -89,6 +96,7 @@ export const lockOps = {
 /** Remove only our fixed metadata names, after the directory was retired. */
 async function cleanRetired(lockPath) {
     await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });
+    await fs.unlink(path.join(lockPath, CHALLENGE_FILE)).catch(() => { });
     await cleanChild(path.join(lockPath, "reclaim.lock"));
     await fs.rmdir(lockPath).catch(() => { });
 }

package/build/auth/auth-runner.js

@@ -11,6 +11,7 @@ import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { devActivity } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
+import { authLockPath, challengeRelayedAt } from "./mfa-challenge.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
@@ -41,6 +42,25 @@ const MFA_POLL_MS = 45000;
  * the number in the answer.
  */
 const CALL_BUDGET_MS = 55000;
+/**
+ * How long a background sign-in past its MFA challenge keeps running once
+ * nobody is waiting on it (issue #199). The answer carrying the number can be
+ * cancelled, or held in a parallel batch the user never sees; the child then
+ * kept its browser and the cross-process lock for the whole 5-minute MFA
+ * window, and every server sharing the session was stuck behind it. A user
+ * who did see the number calls again, which polls for another MFA_POLL_MS, so
+ * the same span without any caller (in this process, or relaying the number
+ * from another one) means nobody is approving.
+ */
+const ABANDON_MS = MFA_POLL_MS;
+/**
+ * Milliseconds until a background sign-in counts as abandoned; zero or less
+ * means it already is. A caller still waiting keeps it alive outright;
+ * otherwise the clock runs from the latest moment anyone attended to it.
+ */
+function abandonDelayMs(waiting, attendedAt, now) {
+    return waiting > 0 ? ABANDON_MS : attendedAt + ABANDON_MS - now;
+}
 /** How long to poll after a challenge seen elapsedMs into the call. */
 function pollWindowMs(elapsedMs) {
     return Math.min(MFA_POLL_MS, CALL_BUDGET_MS - elapsedMs);
@@ -179,15 +199,21 @@ export class AuthRunner {
     pendingChallenge = null;
     /** Resolves on the next marker from the current child; null between children. */
     challengeSignal = null;
+    /** Callers inside run() right now. */
+    waiting = 0;
+    /** When the last caller left run(). */
+    lastAttendedAt = 0;
     scriptPath;
     timeoutMs;
     onProgress;
+    sessionDir;
     constructor(options = {}) {
         // Resolve paths relative to this file's compiled location (build/auth/auth-runner.js)
         const thisDir = path.dirname(fileURLToPath(import.meta.url));
         this.scriptPath = path.resolve(thisDir, "..", "auth-cli.js");
         this.timeoutMs = options.timeoutMs ?? AUTH_TIMEOUT_MS;
         this.onProgress = options.onProgress;
+        this.sessionDir = options.sessionDir;
     }
     /**
      * Authenticate, joining the login this process already started if there is
@@ -206,6 +232,16 @@ export class AuthRunner {
      * the next call to join.
      */
     async run(onChallenge) {
+        this.waiting += 1;
+        try {
+            return await this.attend(onChallenge);
+        }
+        finally {
+            this.waiting -= 1;
+            this.lastAttendedAt = Date.now();
+        }
+    }
+    async attend(onChallenge) {
         const startedAt = Date.now();
         try {
             return await withinCallBudget(this.runOnce(startedAt), startedAt);
@@ -333,6 +369,8 @@ export class AuthRunner {
             // against double cleanup.
             let childFinished = false;
             let numberMatch;
+            let challengeSeen = false;
+            let abandonTimer;
             let killTimer;
             const kill = (signal) => {
                 try {
@@ -400,8 +438,30 @@ export class AuthRunner {
             // joinBackgroundChild. Idempotent on the "already known" question, but
             // a later number still overwrites a numberless pendingChallenge so a
             // fresh joiner sees it — see MFA_PENDING_MARKER's own comment.
+            // Once the child is past its challenge, stop it when nobody is waiting
+            // on it any more (see ABANDON_MS). 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. The dead owner
+            // leaves a stale lock the next sign-in reclaims.
+            const watchAttention = () => {
+                if (childFinished)
+                    return;
+                const relayedAt = this.sessionDir ? challengeRelayedAt(authLockPath(this.sessionDir)) ?? 0 : 0;
+                const delayMs = abandonDelayMs(this.waiting, Math.max(this.lastAttendedAt, relayedAt), Date.now());
+                if (delayMs > 0) {
+                    abandonTimer = setTimeout(watchAttention, delayMs);
+                    abandonTimer.unref?.();
+                    return;
+                }
+                log("WARN", "Stopping a background sign-in nobody is waiting on; its MFA prompt went unanswered");
+                kill("SIGKILL");
+                finishChild(new AuthProcessError("timeout", `The sign-in was stopped because nobody approved its MFA prompt. Try again, or run ${AUTH_COMMAND}.`));
+            };
             const publishChallenge = (matched) => {
+                challengeSeen = true;
                 const firstChallenge = this.pendingChallenge === null;
+                if (firstChallenge)
+                    watchAttention();
                 if (firstChallenge)
                     devActivity("mfa_observed", { elapsedMs: Date.now() - started });
                 if (firstChallenge || matched) {
@@ -424,6 +484,8 @@ export class AuthRunner {
                 clearTimeout(timer);
                 if (killTimer)
                     clearTimeout(killTimer);
+                if (abandonTimer)
+                    clearTimeout(abandonTimer);
                 process.off("exit", onExit);
                 const answeredEarly = callerSettled;
                 settleCaller(error);
@@ -500,6 +562,10 @@ export class AuthRunner {
                         6: ["transport", "Brightspace authentication is temporarily unavailable because of a network or server failure. Your saved session was preserved. Try again later."],
                         7: mfaPendingFailure(numberMatch),
                     };
+                    // Busy, but the owning sign-in's challenge came through: the caller
+                    // was told what to approve, so answer with that, not "busy".
+                    if (code === 2 && challengeSeen)
+                        failures[2] = mfaPendingFailure(numberMatch);
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
                     finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined));

package/build/auth/browser-auth.js

@@ -3,7 +3,6 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT: see LICENSE file for details.
  */
-import * as path from "node:path";
 import { readFileSync, accessSync } from "node:fs";
 import { BrowserAuthError } from "../utils/errors.js";
 import { log } from "../utils/logger.js";
@@ -11,7 +10,8 @@ import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError } from
 import { isDuoPrompt } from "./duo-mfa.js";
 import { BrowserStateStore } from "./browser-state-store.js";
 import { hasNewerEntraState, recordMicrosoftSession } from "./microsoft-session.js";
-import { acquireProcessLock } from "./auth-lock.js";
+import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
+import { authLockPath, publishChallenge, relayChallenge } from "./mfa-challenge.js";
 import { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
 import { isMissingBrowserError, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
@@ -54,12 +54,19 @@ export class BrowserAuth {
     onPhase;
     /** When the current login first reported an MFA challenge; splits credentials from approvalWait. */
     challengeSeenAt;
+    lockPath;
+    /** The latest challenge write, awaited before the lock is released so none lands after it. */
+    publishing = Promise.resolve();
     constructor(config, options = {}) {
         this.config = config;
         this.onPhase = options.onPhase;
         const { onMfaChallenge } = options;
+        this.lockPath = authLockPath(config.sessionDir);
         this.ssoFlow = createSSOFlow(config, options.requestMfaCode, onMfaChallenge && ((number) => {
             this.challengeSeenAt ??= Date.now();
+            // Other server processes sharing this session cannot see our caller's
+            // tool response; the lock directory is where they look instead.
+            this.publishing = this.publishing.then(() => publishChallenge(this.lockPath, number)).catch(() => { });
             onMfaChallenge(number);
         }));
         this.stateStore = new BrowserStateStore(config.sessionDir);
@@ -101,7 +108,13 @@ export class BrowserAuth {
         }
     }
     async authenticate(options = {}) {
-        const release = await acquireProcessLock(path.join(this.config.sessionDir, ".auth.lock"), { mode: options.automatic ? "automatic" : "explicit" });
+        const release = await acquireProcessLock(this.lockPath, { mode: options.automatic ? "automatic" : "explicit" }).catch(async (error) => {
+            // Hand back the number the owner is showing, so this caller's user can
+            // approve that sign-in instead of being told only to wait for it.
+            if (error instanceof AuthenticationInProgressError)
+                error.challenge = await relayChallenge(this.lockPath);
+            throw error;
+        });
         try {
             // Even a cookie-only SAML redirect can issue an MFA push. Suppress all
             // automatic browser attempts during cooldown; HTTP token refresh runs
@@ -114,6 +127,7 @@ export class BrowserAuth {
             return token;
         }
         finally {
+            await this.publishing;
             await release();
         }
     }

package/build/auth/mfa-challenge.js

@@ -0,0 +1,61 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * The MFA challenge a sign-in is showing, shared with every process that
+ * shares its session store (issue #199).
+ *
+ * Several server processes, one per open MCP client, can share one session
+ * directory, and only the one holding the sign-in lock can sign in. The number
+ * to enter used to reach the user only through the one tool call that started
+ * that sign-in. The owner now writes its challenge into the lock directory, so
+ * it disappears with the lock, and a contender reads it back and relays it.
+ * Relaying touches the file, which tells the owner's server that someone is
+ * still waiting on the sign-in (see AuthRunner's abandonment check).
+ */
+import * as fs from "node:fs/promises";
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import { CHALLENGE_FILE } from "./auth-lock.js";
+/** Same bound the auth child's stdout marker enforces: 1-3 digits and nothing else. */
+const NUMBER_MATCH = /^\d{1,3}$/;
+export function authLockPath(sessionDir) {
+    return path.join(sessionDir, ".auth.lock");
+}
+/** Record the challenge this process's sign-in is showing. Call only while holding the lock. */
+export async function publishChallenge(lockPath, numberMatch) {
+    const challenge = numberMatch && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
+    await fs.writeFile(path.join(lockPath, CHALLENGE_FILE), JSON.stringify(challenge), { mode: 0o600 });
+}
+/**
+ * The challenge the lock owner is showing, or undefined when it has published
+ * none. Marks the challenge as just relayed, so the owner keeps waiting.
+ */
+export async function relayChallenge(lockPath) {
+    const file = path.join(lockPath, CHALLENGE_FILE);
+    let challenge;
+    try {
+        challenge = JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof challenge !== "object" || challenge === null)
+        return undefined;
+    const now = new Date();
+    await fs.utimes(file, now, now).catch(() => { });
+    const numberMatch = challenge.numberMatch;
+    return typeof numberMatch === "string" && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
+}
+/** When the lock's challenge was last published or relayed, or undefined when there is none. */
+export function challengeRelayedAt(lockPath) {
+    try {
+        return statSync(path.join(lockPath, CHALLENGE_FILE)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The stdout marker AuthRunner parses for a challenge. */
+export function challengeMarker(numberMatch) {
+    return numberMatch ? `MFA_NUMBER:${numberMatch}` : "MFA_PENDING";
+}

package/build/auth-cli.js

@@ -11,6 +11,8 @@ import { MfaApprovalError } from "./auth/sso-flow.js";
 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 { challengeMarker } from "./auth/mfa-challenge.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
@@ -62,7 +64,7 @@ async function main() {
         // seconds instead of waiting out the whole approval window. Stdout only
         // — the parent parses stdout for structured markers, never stderr.
         const onMfaChallenge = automatic
-            ? (number) => console.log(number ? `MFA_NUMBER:${number}` : "MFA_PENDING")
+            ? (number) => console.log(challengeMarker(number))
             : undefined;
         // Stage timings for the server's dev activity log, same stdout channel.
         const onPhase = automatic
@@ -88,7 +90,12 @@ async function main() {
         // where they were scraped — can cross the process boundary as data
         // rather than free-form text.
         if (error instanceof MfaApprovalError && error.numberMatch) {
-            console.log(`MFA_NUMBER:${error.numberMatch}`);
+            console.log(challengeMarker(error.numberMatch));
+        }
+        // Another process's sign-in holds the lock and is showing a challenge:
+        // pass it on, so this caller can tell its user what to approve.
+        if (automatic && error instanceof AuthenticationInProgressError && error.challenge) {
+            console.log(challengeMarker(error.challenge.numberMatch));
         }
         process.exitCode = error instanceof NativeCredentialStoreError ? 5
             : code === "AUTH_IN_PROGRESS" ? 2

package/build/index.js

@@ -86,6 +86,7 @@ else {
             const authRunner = envAuthActive
                 ? undefined
                 : new AuthRunner({
+                    sessionDir: config.sessionDir,
                     onProgress: (message) => {
                         void server.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
                     },

package/build/tools/tool-helpers.js

@@ -82,6 +82,13 @@ export function errorResponse(message) {
  * nothing is derived from the caught message, so a child process cannot put
  * words in the response. The full error still goes to the log.
  */
+/**
+ * Issue #199: a client running calls in a parallel batch can hold the answer
+ * carrying the number until the whole batch finishes, and the user never sees
+ * it in time. Ask the model to relay it on its own and call one tool at a time.
+ */
+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.";
 const AUTH_FAILURE_GUIDANCE = {
     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.`,
@@ -101,7 +108,8 @@ const AUTH_FAILURE_GUIDANCE = {
     mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo). " +
         "Tell the user that, then call this 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.",
+        "as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
+        MFA_SOLO_CALL,
     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 joins the same " +
         "sign-in, so it sends no second MFA prompt, and returns the number to approve as soon as " +
@@ -119,7 +127,8 @@ function authFailureMessage(error) {
         return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes. ` +
             "Tell the user that number, then call this 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.";
+            "soon as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
+            MFA_SOLO_CALL;
     }
     return AUTH_FAILURE_GUIDANCE[error.kind];
 }

package/package.json

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