brightspace-mcp-server 3.13.2 → 3.13.4

package/README.md

@@ -124,6 +124,8 @@ sits beside your password, so on **this** computer your two factors become one.
 anyone who only has your password, and it changes nothing for your other devices. Full enrollment
 steps: [docs/sign-in.md](docs/sign-in.md#answering-code-challenges-without-your-phone).
 
+**To sign out early** (on a shared computer, say), run `npx -y brightspace-mcp-server@latest auth --logout`. 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. An AI app that is already running can keep answering until its current access token expires; restart the app to drop it 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.
+
 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).
 
 ## Something not working?

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

@@ -9,6 +9,8 @@ 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";
+/** Plaintext browser state from before encryption; load() still adopts it if present. */
+export const LEGACY_BROWSER_STATE_FILE = "storage-state.json";
 function validState(value) {
     const state = value;
     return !!state && Array.isArray(state.cookies) && Array.isArray(state.origins)
@@ -27,7 +29,7 @@ export class BrowserStateStore {
         this.sessionDir = sessionDir;
         this.options = options;
         this.file = path.join(sessionDir, BROWSER_STATE_FILE);
-        this.legacyFile = path.join(sessionDir, "storage-state.json");
+        this.legacyFile = path.join(sessionDir, LEGACY_BROWSER_STATE_FILE);
     }
     storeError(action, error) {
         if (error instanceof NativeCredentialStoreError)

package/build/auth/logout.js

@@ -0,0 +1,122 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * `auth --logout`: end the saved Brightspace session on this computer early.
+ *
+ * This is a local sign-out only. It deletes the files that let the next tool
+ * call skip the browser, so that call does a full sign-in. It does not log out
+ * of Microsoft or D2L on their servers, and it leaves the saved password,
+ * config.json, and every credential-store entry (including the session
+ * encryption key, which the next sign-in reuses) exactly as they were.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
+import { BROWSER_STATE_FILE, LEGACY_BROWSER_STATE_FILE } from "./browser-state-store.js";
+import { MICROSOFT_SESSION_FILE } from "./microsoft-session.js";
+import { authLockPath } from "./mfa-challenge.js";
+import { SESSION_FILE, SessionStore } from "./session-store.js";
+import { AUTH_COMMAND } from "../utils/commands.js";
+import { resolveSessionLocation } from "../utils/config.js";
+/** Browser state files other than the session token itself, in the order they are deleted. */
+const BROWSER_STATE_FILES = [BROWSER_STATE_FILE, LEGACY_BROWSER_STATE_FILE, MICROSOFT_SESSION_FILE];
+class RemoveError extends Error {
+    file;
+    constructor(file, cause) {
+        super(`Could not remove ${file}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.file = file;
+        this.name = "RemoveError";
+    }
+}
+async function removeIfPresent(file) {
+    try {
+        await fs.unlink(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new RemoveError(path.basename(file), error);
+    }
+}
+/**
+ * Delete the saved session files in one account's session directory.
+ *
+ * `sessionDir` is the resolved directory: `accounts/<hash>/` when a username
+ * is configured, the session root otherwise. Siblings, other accounts, and
+ * the pre-account files above `accounts/` are never this account's session
+ * and are not touched. The plaintext `storage-state.json` a version 1 install
+ * left behind is included because loading browser state would re-adopt it.
+ *
+ * Holds the sign-in lock for the duration, in a mode that neither takes over
+ * a live sign-in nor can be taken over, and throws AuthenticationInProgressError
+ * without deleting anything if one is running. It also waits out any session
+ * write already in flight rather than racing it.
+ */
+export async function clearSavedSession(sessionDir) {
+    // Taking the lock creates its parent directory; there is nothing to clear
+    // (and nothing to create) when there is no directory at all.
+    try {
+        await fs.access(sessionDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { removed: [] };
+        throw error;
+    }
+    const release = await acquireProcessLock(authLockPath(sessionDir), { mode: "exclusive" });
+    try {
+        const removed = [];
+        if (await new SessionStore(sessionDir).remove())
+            removed.push(SESSION_FILE);
+        for (const name of BROWSER_STATE_FILES) {
+            if (await removeIfPresent(path.join(sessionDir, name)))
+                removed.push(name);
+        }
+        return { removed };
+    }
+    finally {
+        await release();
+    }
+}
+const KEPT = "Kept: your saved password, config.json, and any authenticator or credential-store entries.";
+const MEMORY_NOTE = "A running Brightspace MCP server may still hold an access token in memory until it expires. Restart your AI client to drop it right away.";
+const LOCAL_ONLY = "This only clears files on this computer. It does not sign you out of Microsoft or Brightspace on their servers.";
+/**
+ * The `auth --logout` command. Resolves to the process exit code: 0 when the
+ * session was cleared or there was nothing to clear, 2 when a sign-in is in
+ * progress (the same code `auth` uses for that), 1 for anything else.
+ */
+export async function runLogout(options = {}) {
+    const print = options.print ?? ((line) => console.error(line));
+    try {
+        const sessionDir = options.sessionDir ?? resolveSessionLocation().sessionDir;
+        const { removed } = await clearSavedSession(sessionDir);
+        if (removed.length === 0) {
+            print("No saved Brightspace session was found on this computer, so there is nothing to clear.");
+        }
+        else {
+            print("Signed out of Brightspace on this computer.");
+            print(`Removed: ${removed.join(", ")}`);
+            print(KEPT);
+            print(`The next Brightspace request, or \`${AUTH_COMMAND}\`, will do a full sign-in.`);
+        }
+        print(MEMORY_NOTE);
+        print(LOCAL_ONLY);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof AuthenticationInProgressError) {
+            print("Not signed out: a sign-in is in progress. Nothing was deleted.");
+            print("Wait for it to finish (or cancel it), then run this command again.");
+            return 2;
+        }
+        if (error instanceof RemoveError) {
+            print(`Sign-out is incomplete. ${error.message}`);
+            print("Close anything that may be using that file, then run this command again to finish.");
+            return 1;
+        }
+        print(`Could not clear the saved session: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}

package/build/auth/microsoft-session.js

@@ -7,7 +7,8 @@ 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";
+/** The plain summary, relative to its session directory. */
+export const MICROSOFT_SESSION_FILE = "microsoft-session.json";
 const ENTRA_HOST = "login.microsoftonline.com";
 const ENTRA_COOKIES = new Set(["ESTSAUTH", "ESTSAUTHPERSISTENT", "ESTSAUTHLIGHT"]);
 const OUTCOMES = ["ticked", "already", "absent", "unknown", "off"];
@@ -41,7 +42,7 @@ function validSummary(value) {
 }
 async function readSummary(sessionDir) {
     try {
-        const summary = JSON.parse(await fs.readFile(path.join(sessionDir, SUMMARY_FILE), "utf8"));
+        const summary = JSON.parse(await fs.readFile(path.join(sessionDir, MICROSOFT_SESSION_FILE), "utf8"));
         return validSummary(summary) ? summary : undefined;
     }
     catch {
@@ -59,7 +60,7 @@ export async function recordMicrosoftSession(sessionDir, state, rememberMfa) {
         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 });
+    await writeFileAtomic(path.join(sessionDir, MICROSOFT_SESSION_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()) {

package/build/auth/session-store.js

@@ -12,6 +12,8 @@ import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.j
 import { hasSessionEncryptionKey, NativeCredentialStoreError } from "./credential-store.js";
 import { decrypt, readEncryptedRecord, saveEncryptedRecord, trashFile } from "./encrypted-store.js";
 const DEFAULT_SESSION_DIR = path.join(os.homedir(), ".d2l-session");
+/** The saved access token, relative to its session directory. */
+export const SESSION_FILE = "session.json";
 function validTenantOrigin(origin) {
     if (origin === undefined)
         return true;
@@ -47,7 +49,7 @@ export class SessionStore {
     constructor(sessionDir = DEFAULT_SESSION_DIR, options = {}) {
         this.options = options;
         this.sessionDir = sessionDir;
-        this.sessionFilePath = path.join(sessionDir, "session.json");
+        this.sessionFilePath = path.join(sessionDir, SESSION_FILE);
     }
     async withWriteLock(operation) {
         await fs.mkdir(this.sessionDir, { recursive: true, mode: 0o700 });
@@ -212,6 +214,31 @@ export class SessionStore {
             this.storeError("clear", error);
         }
     }
+    /**
+     * Delete the saved session without decrypting it, so a damaged file or a
+     * locked credential store cannot keep someone signed in. Permanent rather
+     * than moved to Trash: a session that was signed out on purpose should not
+     * stay recoverable. The encryption key stays in the credential store for the
+     * next sign-in. Resolves true when a file was removed.
+     */
+    async remove() {
+        try {
+            return await this.withWriteLock(async () => {
+                try {
+                    await fs.unlink(this.sessionFilePath);
+                    return true;
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        return false;
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            this.storeError("remove", error);
+        }
+    }
     /** Prevent a slow mint from replacing credentials saved by a newer login. */
     async saveIfCurrent(token, expected) {
         try {

package/build/auth-cli.js

@@ -13,6 +13,7 @@ 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 } 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";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
@@ -35,6 +36,12 @@ async function requestMfaCode() {
     }
 }
 async function main() {
+    // Local and offline: no banner, no update check, no hand-off to a newer
+    // release. It only deletes this machine's saved session files.
+    if (process.argv.includes("--logout")) {
+        process.exitCode = await runLogout();
+        return;
+    }
     const automatic = process.argv.includes("--automatic");
     // If this copy is stale, hand off to the current release instead of running
     // our own out-of-date sign-in code. No prompt, no user action.

package/build/utils/commands.js

@@ -17,6 +17,8 @@
 export const PACKAGE_NAME = "brightspace-mcp-server";
 /** Re-authenticate. Always runs the current published release. */
 export const AUTH_COMMAND = `npx -y ${PACKAGE_NAME}@latest auth`;
+/** End the saved Brightspace session on this computer. Always runs the current published release. */
+export const LOGOUT_COMMAND = `npx -y ${PACKAGE_NAME}@latest auth --logout`;
 /** Re-run the setup wizard. Always runs the current published release. */
 export const SETUP_COMMAND = `npx -y ${PACKAGE_NAME}@latest setup`;
 /** Diagnose a broken setup. Always runs the current published release. */

package/build/utils/config.js

@@ -12,13 +12,15 @@ import { resolveStoredPassword } from "./secure-config.js";
 import { getStoredTotpUri } from "../auth/credential-store.js";
 import { normalizeTotpEnrollment } from "../auth/totp.js";
 import { migrateLegacyState } from "../auth/legacy-state.js";
-export async function loadConfig() {
-    dotenv.config({ quiet: true });
-    // A corrupt or permission-denied config.json must not take the whole server
-    // down at startup: env vars alone are a complete, if less convenient,
-    // configuration. The failure is still surfaced loudly (never silent) so a
-    // broken file doesn't masquerade as "no config.json was ever created".
-    // Idea from lmgveerhoek's fork (MIT).
+/**
+ * The saved settings, or null when there are none to use. A corrupt or
+ * permission-denied config.json must not take the whole server down at
+ * startup: env vars alone are a complete, if less convenient, configuration.
+ * The failure is still surfaced loudly (never silent) so a broken file doesn't
+ * masquerade as "no config.json was ever created".
+ * Idea from lmgveerhoek's fork (MIT).
+ */
+function readConfigStore() {
     let store = null;
     let storeLoadError;
     if (configStoreExists()) {
@@ -39,12 +41,43 @@ export async function loadConfig() {
     else {
         console.error("[config] No config.json found, using environment variables");
     }
-    // Resolve sessionDir: env > store > default
+    return store;
+}
+/**
+ * Which school and account this configuration signs in as, and where that
+ * account's session lives (env > store > default for each). Shared by
+ * loadConfig and by commands that need only the location, such as
+ * `auth --logout`, so they can never disagree about where a session is.
+ */
+function resolveAccountLocation(store) {
     const sessionRoot = process.env.D2L_SESSION_DIR
         ? expandTilde(process.env.D2L_SESSION_DIR)
         : store?.sessionDir
             ? expandTilde(store.sessionDir)
             : path.join(os.homedir(), ".d2l-session");
+    const configuredUrl = new URL(process.env.D2L_BASE_URL || store?.baseUrl || "https://purdue.brightspace.com");
+    if (configuredUrl.protocol !== "https:" || configuredUrl.username || configuredUrl.password) {
+        throw new Error("The Brightspace URL must be an HTTPS school URL without embedded credentials.");
+    }
+    const baseUrl = configuredUrl.origin;
+    const username = process.env.D2L_USERNAME || store?.username;
+    // A new account must never inherit another account's cookies, even at the same school.
+    return { baseUrl, username, sessionRoot, sessionDir: accountSessionDirectory(sessionRoot, baseUrl, username) };
+}
+/**
+ * Where the configured account keeps its saved session. Unlike loadConfig it
+ * reads no password and migrates nothing, so it works when the credential
+ * store is locked. `sessionDir` holds the account's files; `sessionRoot` is
+ * the directory above any `accounts/<hash>/` layer.
+ */
+export function resolveSessionLocation() {
+    dotenv.config({ quiet: true });
+    const { sessionDir, sessionRoot } = resolveAccountLocation(readConfigStore());
+    return { sessionDir, sessionRoot };
+}
+export async function loadConfig() {
+    dotenv.config({ quiet: true });
+    const store = readConfigStore();
     // Code-entry and other interactive MFA methods need a visible browser.
     const headless = envBoolean(process.env.D2L_HEADLESS, "D2L_HEADLESS")
         ?? store?.headless
@@ -89,12 +122,7 @@ export async function loadConfig() {
     const envAccessToken = readEnvSecret(process.env.D2L_ACCESS_TOKEN, "D2L_ACCESS_TOKEN");
     const rawSessionCookie = readEnvSecret(process.env.D2L_SESSION_COOKIE, "D2L_SESSION_COOKIE");
     const envSessionCookie = rawSessionCookie ? parseSessionCookieEnv(rawSessionCookie) : undefined;
-    const configuredUrl = new URL(process.env.D2L_BASE_URL || store?.baseUrl || "https://purdue.brightspace.com");
-    if (configuredUrl.protocol !== "https:" || configuredUrl.username || configuredUrl.password) {
-        throw new Error("The Brightspace URL must be an HTTPS school URL without embedded credentials.");
-    }
-    const baseUrl = configuredUrl.origin;
-    const username = process.env.D2L_USERNAME || store?.username;
+    const { baseUrl, username, sessionRoot, sessionDir } = resolveAccountLocation(store);
     const password = passwordless ? undefined : await resolveStoredPassword(baseUrl, username, store);
     // Opt-in: only an enrollment the user deliberately saved makes the Entra
     // sign-in answer a verification-code challenge itself. With none, every MFA
@@ -110,8 +138,6 @@ export async function loadConfig() {
         // that reports a locked or missing store, loudly, for the credential the
         // server genuinely cannot work without.
         : username ? (await getStoredTotpUri(baseUrl, username).catch(() => null)) ?? undefined : undefined;
-    // A new account must never inherit another account's cookies, even at the same school.
-    const sessionDir = accountSessionDirectory(sessionRoot, baseUrl, username);
     const legacyMigration = sessionDir !== sessionRoot ? await migrateLegacyState(sessionRoot) : undefined;
     return {
         baseUrl,

package/package.json

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