brightspace-mcp-server 3.11.6 → 3.11.7

package/build/auth/auth-phases.js

@@ -0,0 +1,21 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+/**
+ * The browser sign-in stages whose durations the automatic child reports to
+ * the server (issue #182). A fixed list, so a stage name is never arbitrary
+ * child output by the time it reaches the dev activity log.
+ */
+export const AUTH_PHASES = ["launch", "navigation", "silentSso", "credentials", "approvalWait", "token"];
+const PHASE_MARKER = new RegExp(`^AUTH_PHASE:(${AUTH_PHASES.join("|")}):(\\d{1,9})$`);
+/** The stdout line the automatic child prints when a stage ends. */
+export function formatPhaseMarker(phase, elapsedMs) {
+    return `AUTH_PHASE:${phase}:${Math.max(0, Math.round(elapsedMs))}`;
+}
+/** The stage and duration from a whole stdout line, or null for anything else. */
+export function parsePhaseMarker(line) {
+    const match = PHASE_MARKER.exec(line);
+    return match ? { phase: match[1], elapsedMs: Number(match[2]) } : null;
+}

package/build/auth/auth-runner.js

@@ -10,6 +10,7 @@ import { log } from "../utils/logger.js";
 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";
 /**
  * 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
@@ -31,12 +32,13 @@ const KILL_GRACE_MS = 5000;
  */
 const MFA_POLL_MS = 45000;
 /**
- * The latest a polling caller is answered, counted from when it called run().
+ * The latest any caller is answered, counted from when it called run().
  * Browser launch and the SSO pages can take half a minute before the
- * challenge even appears, so the poll is cut short to fit this budget. It
- * stays under the 60-second request timeout MCP clients commonly apply, so a
- * client that never shows the mid-call notice still gets the number in the
- * answer.
+ * challenge even appears, so the poll is cut short to fit this budget, and a
+ * sign-in that has not reached MFA by then answers "still signing in" while
+ * it keeps running. It stays under the 60-second request timeout MCP clients
+ * commonly apply, so a client that never shows the mid-call notice still gets
+ * the number in the answer.
  */
 const CALL_BUDGET_MS = 55000;
 /** How long to poll after a challenge seen elapsedMs into the call. */
@@ -44,11 +46,12 @@ function pollWindowMs(elapsedMs) {
     return Math.min(MFA_POLL_MS, CALL_BUDGET_MS - elapsedMs);
 }
 /**
- * The only two lines auth-cli.ts is allowed to hand back as structured data.
- * Deliberately strict (whole line, 1-3 digits or the literal word) so this
- * can never become a channel for arbitrary child-process text to reach a
- * tool response — anything that doesn't match exactly is just another log
- * line.
+ * The only two lines auth-cli.ts is allowed to hand back as structured data
+ * for a tool response; parsePhaseMarker adds stage timings for the dev
+ * activity log only. Deliberately strict (whole line, 1-3 digits or the
+ * literal word) so this can never become a channel for arbitrary
+ * child-process text to reach a tool response — anything that doesn't match
+ * exactly is just another log line.
  */
 const MFA_NUMBER_MARKER = /^MFA_NUMBER:(\d{1,3})$/;
 const MFA_PENDING_MARKER = /^MFA_PENDING$/;
@@ -75,6 +78,19 @@ export class AuthProcessError extends AuthError {
         this.name = "AuthProcessError";
     }
 }
+/**
+ * Settle with work's outcome, or with inProgress once CALL_BUDGET_MS has
+ * passed since startedAt. Only the caller stops waiting: work carries on.
+ */
+function withinCallBudget(work, startedAt) {
+    return new Promise((resolve, reject) => {
+        const budgetTimer = setTimeout(() => {
+            reject(new AuthProcessError("inProgress", "Sign-in is still running in the background. Try again."));
+        }, Math.max(0, CALL_BUDGET_MS - (Date.now() - startedAt)));
+        budgetTimer.unref?.();
+        work.then((value) => { clearTimeout(budgetTimer); resolve(value); }, (error) => { clearTimeout(budgetTimer); reject(error); });
+    });
+}
 /** Chromium can lead a separate process group, so a forced stop needs its PID. */
 function descendantPids(parentPid) {
     const rows = execFileSync("ps", ["-eo", "pid=,ppid="], {
@@ -185,12 +201,14 @@ export class AuthRunner {
      * and the first call itself keeps waiting the same way. Either way an
      * approval within the window completes the caller's original request; past
      * it, the caller gets the same mfaPending answer again and is expected to
-     * call once more.
+     * call once more. No caller waits past CALL_BUDGET_MS: a sign-in still
+     * short of its challenge by then answers inProgress and keeps running for
+     * the next call to join.
      */
     async run(onChallenge) {
         const startedAt = Date.now();
         try {
-            return await this.runOnce(startedAt);
+            return await withinCallBudget(this.runOnce(startedAt), startedAt);
         }
         catch (error) {
             const childDone = this.childDone;
@@ -440,7 +458,11 @@ export class AuthRunner {
             // immediately, without killing the child — see the class doc comment.
             forwardLines(child.stdout, (line) => {
                 const numberMarker = MFA_NUMBER_MARKER.exec(line);
-                if (numberMarker) {
+                const phaseMarker = parsePhaseMarker(line);
+                if (phaseMarker) {
+                    devActivity("auth_phase", phaseMarker);
+                }
+                else if (numberMarker) {
                     numberMatch = numberMarker[1];
                     publishChallenge(numberMatch);
                 }

package/build/auth/browser-auth.js

@@ -51,12 +51,37 @@ export class BrowserAuth {
     ssoFlow;
     stateStore;
     cooldown;
+    onPhase;
+    /** When the current login first reported an MFA challenge; splits credentials from approvalWait. */
+    challengeSeenAt;
     constructor(config, options = {}) {
         this.config = config;
-        this.ssoFlow = createSSOFlow(config, options.requestMfaCode, options.onMfaChallenge);
+        this.onPhase = options.onPhase;
+        const { onMfaChallenge } = options;
+        this.ssoFlow = createSSOFlow(config, options.requestMfaCode, onMfaChallenge && ((number) => {
+            this.challengeSeenAt ??= Date.now();
+            onMfaChallenge(number);
+        }));
         this.stateStore = new BrowserStateStore(config.sessionDir);
         this.cooldown = new AuthCooldown(config.sessionDir);
     }
+    /** Report a stage that ran from startedAt to endedAt; a listener failure never interrupts sign-in. */
+    phaseEnded(phase, startedAt, endedAt = Date.now()) {
+        try {
+            this.onPhase?.(phase, endedAt - startedAt);
+        }
+        catch { /* Reporting must not interrupt authentication. */ }
+    }
+    /** Run one stage and report its duration however it ends. */
+    async timed(phase, work) {
+        const startedAt = Date.now();
+        try {
+            return await work();
+        }
+        finally {
+            this.phaseEnded(phase, startedAt);
+        }
+    }
     static isWSLOrDocker() {
         try {
             if (/microsoft|wsl/i.test(readFileSync("/proc/version", "utf8")))
@@ -100,6 +125,7 @@ export class BrowserAuth {
         let interrupted = false;
         let state;
         let stateSaved = false;
+        let tokenStartedAt;
         const closeOnSignal = () => {
             interrupted = true;
             void browser?.close().catch(() => { });
@@ -112,7 +138,7 @@ export class BrowserAuth {
                 args.push("--no-sandbox", "--disable-setuid-sandbox");
             // Use Playwright's own timeout, which cleans up an unsuccessful launch.
             try {
-                browser = await chromium.launch({ headless: this.config.headless, timeout: 60000, args });
+                browser = await this.timed("launch", () => chromium.launch({ headless: this.config.headless, timeout: 60000, args }));
             }
             catch (launchError) {
                 // Keep the remedy attached to the failure. Without this the hint is
@@ -142,6 +168,7 @@ export class BrowserAuth {
             // away newly renewed Entra or Brightspace cookies.
             await this.saveBrowserState(await context.storageState());
             stateSaved = true;
+            tokenStartedAt = Date.now();
             const material = await this.harvestSessionMaterial(page, context);
             let token = null;
             if (material.cookieHeader && material.csrfToken) {
@@ -182,6 +209,8 @@ export class BrowserAuth {
             throw error;
         }
         finally {
+            if (tokenStartedAt !== undefined)
+                this.phaseEnded("token", tokenStartedAt);
             process.removeListener("SIGINT", closeOnSignal);
             process.removeListener("SIGTERM", closeOnSignal);
             if (page && listener)
@@ -327,10 +356,10 @@ export class BrowserAuth {
         let navigationError;
         let response;
         try {
-            response = await page.goto(`${this.config.baseUrl}/d2l/home`, {
+            response = await this.timed("navigation", () => page.goto(`${this.config.baseUrl}/d2l/home`, {
                 waitUntil: "domcontentloaded",
                 timeout: INITIAL_NAVIGATION_TIMEOUT_MS,
-            });
+            }));
         }
         catch (error) {
             // Brightspace Bar tolerates a navigation timeout because SAML may keep
@@ -347,7 +376,7 @@ export class BrowserAuth {
         if (response && (response.status() >= 500 || response.status() === 429)) {
             throw new BrowserAuthTransportError(`Brightspace temporarily returned HTTP ${response.status()}. Saved state is preserved.`);
         }
-        if (await this.awaitSilentSSO(page)) {
+        if (await this.timed("silentSso", () => this.awaitSilentSSO(page))) {
             log("INFO", "Saved session is active");
             return true;
         }
@@ -368,6 +397,8 @@ export class BrowserAuth {
             }
             throw new BrowserAuthTransportError("The sign-in page has not settled on a supported login challenge. Retry shortly; saved state is preserved.", navigationError === undefined ? undefined : { cause: navigationError });
         }
+        const loginStartedAt = Date.now();
+        this.challengeSeenAt = undefined;
         try {
             if (!await this.ssoFlow.login(page)) {
                 throw new UnsupportedAuthenticationError("The identity provider could not complete automatic sign-in.");
@@ -378,6 +409,14 @@ export class BrowserAuth {
                 await this.cooldown.recordMfaFailure();
             throw error;
         }
+        finally {
+            if (this.challengeSeenAt === undefined)
+                this.phaseEnded("credentials", loginStartedAt);
+            else {
+                this.phaseEnded("credentials", loginStartedAt, this.challengeSeenAt);
+                this.phaseEnded("approvalWait", this.challengeSeenAt);
+            }
+        }
         if (!await this.hasLiveSession(page)) {
             throw new BrowserAuthError("Sign-in did not produce a verified Brightspace session.", "session_validation");
         }

package/build/auth-cli.js

@@ -10,6 +10,7 @@ import { BrowserAuth, TokenManager } from "./auth/index.js";
 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 { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
@@ -63,7 +64,11 @@ async function main() {
         const onMfaChallenge = automatic
             ? (number) => console.log(number ? `MFA_NUMBER:${number}` : "MFA_PENDING")
             : undefined;
-        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge }).authenticate({
+        // Stage timings for the server's dev activity log, same stdout channel.
+        const onPhase = automatic
+            ? (phase, elapsedMs) => console.log(formatPhaseMarker(phase, elapsedMs))
+            : undefined;
+        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase }).authenticate({
             automatic,
             onAuthenticated: async (token) => {
                 await tokenManager.setToken(token);

package/build/tools/tool-helpers.js

@@ -102,6 +102,10 @@ const AUTH_FAILURE_GUIDANCE = {
         "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.",
+    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 " +
+        "one appears. Don't ask the user to do anything yet.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`

package/build/utils/dev-activity.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { AUTH_PHASES } from "../auth/auth-phases.js";
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -23,7 +24,7 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     if (!directory)
         return;
     if (!["tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
-        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished"].includes(event))
+        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished", "auth_phase"].includes(event))
         return;
     const at = new Date().toISOString();
     const record = { at, runId, pid: process.pid, event };
@@ -37,6 +38,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
         record.outcome = fields.outcome;
     if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending"].includes(fields.reason ?? ""))
         record.reason = fields.reason;
+    if (AUTH_PHASES.includes(fields.phase ?? ""))
+        record.phase = fields.phase;
     try {
         mkdirSync(directory, { recursive: true, mode: 0o700 });
         const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);

package/package.json

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