brightspace-mcp-server 3.7.14 → 3.8.1

package/README.md

@@ -99,7 +99,7 @@ There's no login step — asking a question signs you in.
 
 **Normal days:** tokens renew over HTTPS, and a background browser silently replays your saved Microsoft session (silent SSO) if it lapses.
 
-**When MFA is asked:** the number to approve shows up right in the tool's response, and sign-in finishes in the background — approve it, call the tool again, and use the newest number if one goes stale. TOTP apps (Google Authenticator, etc.) get prompted via the terminal; visible-browser mode opens a window instead, though automatic recovery during a tool call still runs headless unless you set `D2L_HEADLESS=false`. On Duo, sign-in auto-answers "Is this your device?" with **yes**, since a headless run has nobody to click it — this also makes Duo remember the device, so skip it on shared machines. Set `D2L_DUO_PASSCODE` to swap the push for a typed passcode.
+**When MFA is asked:** the number to approve shows up right in the tool's response, and sign-in finishes in the background — approve it, call the tool again, and use the newest number if one goes stale. TOTP apps (Google Authenticator, etc.) get prompted via the terminal; visible-browser mode opens a window instead, though automatic recovery during a tool call still runs headless unless you set `D2L_HEADLESS=false`. On Duo, sign-in auto-answers "Is this your device?" with **yes**, since a headless run has nobody to click it — this also makes Duo remember the device, so skip it on shared machines. Set `D2L_DUO_PASSCODE` to swap the push for a typed passcode. On Microsoft's MFA page the server ticks "Don't ask again" when your school offers it, so later sign-ins can skip the second factor; how long that lasts is the school's setting, not the server's (`D2L_REMEMBER_MFA=false` turns this off, and `get_server_info` shows whether it was offered).
 
 **If it gets stuck:** a missed MFA approval pauses automatic sign-in for 5 minutes. This retries immediately, takes over a stuck sign-in, or asks for a code:
 
@@ -123,7 +123,7 @@ Run it from your home folder — macOS blocks `npx` from Documents, Desktop, or
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
 | Video transcripts | "What did the professor say about pinch-off in Tuesday's lecture recording?" · "Summarize last week's BoilerCast video" — works for Kaltura and YouTube embeds; other platforms report that they aren't supported yet |
-| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, and whether a credential is stored, without contacting Brightspace or revealing secrets |
+| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, and what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, or not offered), without contacting Brightspace or revealing secrets |
 | Calendar | "When is my midterm?" · "What's on my calendar this week?" · "Is lab cancelled on Thursday?" — reads exams, labs, review sessions, and deadlines instructors put only on the course calendar |
 | Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, graded discussion topics (any topic with a due date), and course calendar events such as exams and labs |
 

package/build/auth/browser-auth.js

@@ -10,6 +10,7 @@ import { log } from "../utils/logger.js";
 import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError } from "./sso-flow.js";
 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 { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
@@ -95,12 +96,14 @@ export class BrowserAuth {
         let page;
         let listener;
         let interrupted = false;
+        let state;
+        let stateSaved = false;
         const closeOnSignal = () => {
             interrupted = true;
             void browser?.close().catch(() => { });
         };
         try {
-            const state = await this.stateStore.load();
+            state = await this.stateStore.load();
             const { chromium } = await import("playwright");
             const args = ["--disable-blink-features=AutomationControlled"];
             if (BrowserAuth.isWSLOrDocker())
@@ -135,7 +138,8 @@ export class BrowserAuth {
             // Persist the verified browser state before token acquisition. Token
             // minting can fail independently, and a temporary outage must not throw
             // away newly renewed Entra or Brightspace cookies.
-            await this.stateStore.save(await context.storageState());
+            await this.saveBrowserState(await context.storageState());
+            stateSaved = true;
             const material = await this.harvestSessionMaterial(page, context);
             let token = null;
             if (material.cookieHeader && material.csrfToken) {
@@ -161,6 +165,11 @@ export class BrowserAuth {
             log("INFO", "Browser authentication complete");
             return { ...token, ...material, tenantOrigin: new URL(this.config.baseUrl).origin };
         }
+        catch (error) {
+            if (context && !stateSaved)
+                await this.keepNewerMicrosoftState(context, state);
+            throw error;
+        }
         finally {
             process.removeListener("SIGINT", closeOnSignal);
             process.removeListener("SIGTERM", closeOnSignal);
@@ -170,6 +179,30 @@ export class BrowserAuth {
             await browser?.close().catch(() => { });
         }
     }
+    /** Save the browser state and what Microsoft remembered in it. */
+    async saveBrowserState(state) {
+        await this.stateStore.save(state);
+        await recordMicrosoftSession(this.config.sessionDir, state, this.ssoFlow.rememberMfaResult?.())
+            .catch(() => log("WARN", "Could not record the Microsoft sign-in summary; saved sign-in state is unaffected."));
+    }
+    /**
+     * A run can fail after Entra already renewed its cookies (an MFA timeout,
+     * a token-mint outage, a Brightspace redirect stall). Keep that renewal
+     * when it is strictly newer than the saved jar; otherwise the saved state
+     * is left untouched. Never masks the original failure.
+     */
+    async keepNewerMicrosoftState(context, previous) {
+        try {
+            const current = await context.storageState();
+            if (!hasNewerEntraState(previous, current))
+                return;
+            await this.saveBrowserState(current);
+            log("INFO", "Sign-in failed, but Microsoft's renewed sign-in state was kept");
+        }
+        catch {
+            log("DEBUG", "Could not keep Microsoft's renewed sign-in state after a failed sign-in");
+        }
+    }
     /**
      * Run the token extraction strategy chain, cheapest to most invasive.
      * Each strategy validates against /users/whoami before returning.

package/build/auth/browser-state-store.js

@@ -8,6 +8,7 @@ import * as path from "node:path";
 import { SessionStoreError } from "../utils/errors.js";
 import { NativeCredentialStoreError } from "./credential-store.js";
 import { readEncryptedRecord, saveEncryptedRecord, trashFile } from "./encrypted-store.js";
+export const BROWSER_STATE_FILE = "storage-state.encrypted.json";
 function validState(value) {
     const state = value;
     return !!state && Array.isArray(state.cookies) && Array.isArray(state.origins)
@@ -25,7 +26,7 @@ export class BrowserStateStore {
     constructor(sessionDir, options = {}) {
         this.sessionDir = sessionDir;
         this.options = options;
-        this.file = path.join(sessionDir, "storage-state.encrypted.json");
+        this.file = path.join(sessionDir, BROWSER_STATE_FILE);
         this.legacyFile = path.join(sessionDir, "storage-state.json");
     }
     storeError(action, error) {

package/build/auth/microsoft-session.js

@@ -0,0 +1,83 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT. See LICENSE file for details.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { writeFileAtomic } from "../utils/atomic-write.js";
+import { BROWSER_STATE_FILE } from "./browser-state-store.js";
+const SUMMARY_FILE = "microsoft-session.json";
+const ENTRA_HOST = "login.microsoftonline.com";
+const ENTRA_COOKIES = new Set(["ESTSAUTH", "ESTSAUTHPERSISTENT", "ESTSAUTHLIGHT"]);
+const OUTCOMES = ["ticked", "already", "absent", "unknown"];
+/** Latest expiry of each Entra sign-in cookie in a jar. */
+function entraExpiries(state) {
+    const expiries = new Map();
+    for (const cookie of state?.cookies ?? []) {
+        if (!ENTRA_COOKIES.has(cookie.name) || cookie.domain.replace(/^\./, "") !== ENTRA_HOST)
+            continue;
+        expiries.set(cookie.name, Math.max(cookie.expires, expiries.get(cookie.name) ?? -Infinity));
+    }
+    return expiries;
+}
+/**
+ * True when the current jar holds an Entra sign-in cookie the previous one
+ * lacked, or one that now expires later. A jar with no Entra cookies is never
+ * newer, so a failed run cannot replace saved state with an empty one.
+ */
+export function hasNewerEntraState(previous, current) {
+    const before = entraExpiries(previous);
+    return [...entraExpiries(current)].some(([name, expires]) => {
+        const old = before.get(name);
+        return old === undefined || expires > old;
+    });
+}
+function validSummary(value) {
+    const summary = value;
+    return !!summary && summary.version === 1
+        && (summary.persistentExpires === null || Number.isFinite(summary.persistentExpires))
+        && (summary.rememberMfa === null || (OUTCOMES.includes(summary.rememberMfa?.outcome) && typeof summary.rememberMfa.at === "string"));
+}
+async function readSummary(sessionDir) {
+    try {
+        const summary = JSON.parse(await fs.readFile(path.join(sessionDir, SUMMARY_FILE), "utf8"));
+        return validSummary(summary) ? summary : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record what Microsoft remembered in a browser state that was just saved.
+ * A login that never reached the MFA page keeps the last recorded outcome.
+ */
+export async function recordMicrosoftSession(sessionDir, state, rememberMfa) {
+    const summary = {
+        version: 1,
+        persistentExpires: entraExpiries(state).get("ESTSAUTHPERSISTENT") ?? null,
+        rememberMfa: rememberMfa ?? (await readSummary(sessionDir))?.rememberMfa ?? null,
+    };
+    await fs.mkdir(sessionDir, { recursive: true, mode: 0o700 });
+    await writeFileAtomic(path.join(sessionDir, SUMMARY_FILE), JSON.stringify(summary), { mode: 0o600 });
+}
+/** The summary for saved browser state, or undefined when there is none. */
+export async function readMicrosoftSession(sessionDir, now = Date.now()) {
+    try {
+        await fs.access(path.join(sessionDir, BROWSER_STATE_FILE));
+    }
+    catch {
+        return undefined;
+    }
+    const summary = await readSummary(sessionDir);
+    if (!summary)
+        return undefined;
+    const expires = summary.persistentExpires;
+    const staySignedIn = expires !== null && (expires === -1 || expires * 1000 > now);
+    return {
+        staySignedIn,
+        staySignedInExpires: staySignedIn && expires > 0 ? new Date(expires * 1000).toISOString() : null,
+        rememberMfa: summary.rememberMfa?.outcome ?? "unknown",
+        rememberMfaAt: summary.rememberMfa?.at ?? null,
+    };
+}

package/build/auth/purdue-sso.js

@@ -24,6 +24,22 @@ const FIELD_POLL_MS = 250;
 const NUMBER_MATCH_SELECTOR = "#idRichContext_DisplaySign";
 const MFA_CODE_SELECTORS = ["#idTxtBx_SAOTCC_OTC", 'input[name="otc"]'];
 const MFA_CODE_SUBMIT_SELECTORS = ["#idSubmit_SAOTCC_Continue", "#idSIButton9"];
+/**
+ * Entra's "Don't ask again for N days" checkbox: the number-match page's id
+ * first, then the verification-code page's, then the label text for a tenant
+ * that renames both. "Stay signed in?" only keeps the session; this box is
+ * what lets the tenant skip the second factor, and the page navigates the
+ * instant the phone approves, so it is ticked before the challenge is
+ * announced or a code is asked for.
+ */
+const REMEMBER_MFA_SELECTORS = ["#idChkBx_SAOTCAS_TD", "#idChkBx_SAOTCC_TD"];
+const REMEMBER_MFA_LABEL = /don.t ask again/i;
+const REMEMBER_MFA_LOG = {
+    ticked: "ticked",
+    already: "already checked",
+    absent: "not offered by tenant",
+    unknown: "could not be ticked",
+};
 /** How often to look for the number while waiting on MFA. */
 const NUMBER_MATCH_POLL_MS = 2000;
 /** A person has to find their phone, unlock it, and read a prompt. */
@@ -80,6 +96,8 @@ export class PurdueSSOFlow {
     accountHintSubmitted = false;
     /** One authenticator code per login. See submitMfaCode. */
     mfaCodeSubmitted = false;
+    /** Set once per login, the first time Entra's MFA page is handled. */
+    rememberMfa;
     duoMfa;
     constructor(config) {
         this.config = config;
@@ -91,6 +109,10 @@ export class PurdueSSOFlow {
     hasCredentials() {
         return Boolean(this.config.username && this.config.password);
     }
+    /** What Entra's "Don't ask again" checkbox did, once its MFA page has appeared. */
+    rememberMfaResult() {
+        return this.rememberMfa;
+    }
     async prepareLogin(page) {
         await this.handleCampusSelector(page);
     }
@@ -306,6 +328,7 @@ export class PurdueSSOFlow {
                     await page.locator("#idDiv_SAOTCAS_Title").first().isVisible().catch(() => false) ||
                     await page.locator("#idDiv_SAOTCC_Title").first().isVisible().catch(() => false);
                 if (challengeVisible && !challenged) {
+                    await this.rememberMfaDevice(page);
                     challenged = true;
                     log("WARN", "Waiting up to 5 minutes for Microsoft MFA approval on your device.");
                     this.config.onMfaChallenge?.(number);
@@ -430,6 +453,7 @@ export class PurdueSSOFlow {
         if (!this.config.requestMfaCode) {
             throw new UnsupportedAuthenticationError(`This MFA method requires a code. Run \`${AUTH_COMMAND}\` in a terminal to enter it.`);
         }
+        await this.rememberMfaDevice(page);
         this.mfaCodeSubmitted = true;
         const code = await this.config.requestMfaCode();
         if (!/^\d{6,8}$/.test(code))
@@ -443,6 +467,39 @@ export class PurdueSSOFlow {
         log("INFO", "Authenticator code submitted");
         return true;
     }
+    /**
+     * Tick Entra's "Don't ask again" box, once per login and never in a loop.
+     * An already-checked box is left alone so this can never untick it.
+     */
+    async rememberMfaDevice(page) {
+        if (this.rememberMfa || this.config.rememberMfa === false)
+            return;
+        if (new URL(page.url()).hostname !== "login.microsoftonline.com")
+            return;
+        // A nicety, never a reason to fail sign-in: any surprise is "unknown".
+        let outcome;
+        try {
+            let box = await this.firstVisible(page, REMEMBER_MFA_SELECTORS);
+            if (!box) {
+                const labelled = page.getByLabel(REMEMBER_MFA_LABEL).first();
+                if (await labelled.isVisible().catch(() => false))
+                    box = labelled;
+            }
+            if (!box)
+                outcome = "absent";
+            else if (await box.isChecked())
+                outcome = "already";
+            else {
+                await box.check({ timeout: 5_000 });
+                outcome = "ticked";
+            }
+        }
+        catch {
+            outcome = "unknown";
+        }
+        this.rememberMfa = { outcome, at: new Date().toISOString() };
+        log("INFO", `Entra remember-MFA checkbox: ${REMEMBER_MFA_LOG[outcome]}`);
+    }
     async firstVisible(page, selectors) {
         for (const selector of selectors) {
             const target = page.locator(selector).first();

package/build/auth/sso-flow.js

@@ -42,6 +42,7 @@ export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
         password: config.password,
         baseUrl: config.baseUrl,
         headless: config.headless,
+        rememberMfa: config.rememberMfa,
         requestMfaCode,
         onMfaChallenge,
     };

package/build/auth/suny-sso.js

@@ -55,6 +55,7 @@ export class SunySSOFlow {
             password: config.password,
             baseUrl: `https://${SUNY_BRIGHTSPACE_HOST}`,
             headless: config.headless,
+            rememberMfa: config.rememberMfa,
             requestMfaCode: config.requestMfaCode,
             onMfaChallenge: config.onMfaChallenge,
         });
@@ -62,6 +63,9 @@ export class SunySSOFlow {
     hasCredentials() {
         return this.defaultFlow.hasCredentials();
     }
+    rememberMfaResult() {
+        return this.defaultFlow.rememberMfaResult();
+    }
     async prepareLogin(page) {
         await this.startSamlLogin(page);
         await this.selectCampus(page);

package/build/auth/western-sso.js

@@ -19,6 +19,9 @@ export class WesternSSOFlow {
     hasCredentials() {
         return this.common.hasCredentials();
     }
+    rememberMfaResult() {
+        return this.common.rememberMfaResult();
+    }
     async prepareLogin(page) {
         await this.startWesternLogin(page);
     }

package/build/tools/get-server-info.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import { readMicrosoftSession } from "../auth/microsoft-session.js";
 import { getConfigStorePath } from "../utils/config-store.js";
 import { GetServerInfoSchema } from "./schemas.js";
 import { toolResponse } from "./tool-helpers.js";
@@ -11,22 +12,28 @@ import { toolResponse } from "./tool-helpers.js";
  *
  * Answers from the startup config alone: no network call, so it can never
  * trigger a sign-in. hasStoredCredential reflects the keychain lookup made at
- * startup, which is the credential this process actually holds. Nothing
- * secret — password, username, token, cookie — is ever included.
+ * startup, which is the credential this process actually holds.
+ * microsoftSession comes from the plain summary saved beside the browser
+ * state and is omitted when there is no saved state. Nothing secret —
+ * password, username, token, cookie — is ever included.
  */
 export function registerGetServerInfo(server, config, version) {
     server.registerTool("get_server_info", {
         title: "Get Server Info",
-        description: "Report which version of the Brightspace MCP server is running, the Node.js runtime, platform, config file path, session state directory, configured school URL, and whether a credential is stored. Use this for troubleshooting or when the user asks which version they have. Never contacts Brightspace and never returns secrets.",
+        description: "Report which version of the Brightspace MCP server is running, the Node.js runtime, platform, config file path, session state directory, configured school URL, whether a credential is stored, and (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in and the Don't ask again MFA checkbox. Use this for troubleshooting or when the user asks which version they have. Never contacts Brightspace and never returns secrets.",
         inputSchema: GetServerInfoSchema,
-    }, async () => toolResponse({
-        version,
-        node: process.version,
-        platform: process.platform,
-        arch: process.arch,
-        configPath: getConfigStorePath(),
-        sessionStatePath: config.sessionDir,
-        schoolUrl: config.baseUrl,
-        hasStoredCredential: config.password !== undefined,
-    }));
+    }, async () => {
+        const microsoftSession = await readMicrosoftSession(config.sessionDir);
+        return toolResponse({
+            version,
+            node: process.version,
+            platform: process.platform,
+            arch: process.arch,
+            configPath: getConfigStorePath(),
+            sessionStatePath: config.sessionDir,
+            schoolUrl: config.baseUrl,
+            hasStoredCredential: config.password !== undefined,
+            ...(microsoftSession && { microsoftSession }),
+        });
+    });
 }

package/build/utils/config.js

@@ -29,6 +29,8 @@ export async function loadConfig() {
     const headless = envBoolean(process.env.D2L_HEADLESS, "D2L_HEADLESS")
         ?? store?.headless
         ?? true;
+    // Ask Microsoft to skip the second factor for its "Don't ask again" window.
+    const rememberMfa = envBoolean(process.env.D2L_REMEMBER_MFA, "D2L_REMEMBER_MFA") ?? true;
     // Resolve tokenTtl: env > store > default (3600)
     const tokenTtl = positiveSeconds(process.env.D2L_TOKEN_TTL, "D2L_TOKEN_TTL")
         ?? positiveSeconds(store?.tokenTtl, "tokenTtl in config.json")
@@ -62,6 +64,7 @@ export async function loadConfig() {
         legacyBrowserStateMigrated: legacyMigration?.browserState === "encrypted",
         tokenTtl,
         headless,
+        rememberMfa,
         username,
         password,
         campus: process.env.D2L_CAMPUS || store?.campus,

package/package.json

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