brightspace-mcp-server 4.0.2 → 4.0.4

package/build/auth/credential-store.js

@@ -8,6 +8,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
+import { canonicalUsername } from "./username.js";
 const SERVICE = "brightspace-mcp-server";
 const LINUX_GUIDANCE = "Linux requires secret-tool and an unlocked Secret Service. Install libsecret-tools (Debian/Ubuntu) or your distribution's libsecret tools, unlock the desktop keyring, then retry. Temporary kernel key storage is not supported.";
 export class NativeCredentialStoreError extends Error {
@@ -158,63 +159,87 @@ export const nativeCredentialBackend = {
         }
     },
 };
-function passwordAccount(baseUrl, username) {
-    const identity = JSON.stringify([new URL(baseUrl).origin, username]);
-    return `password:${createHash("sha256").update(identity).digest("hex")}`;
+/**
+ * Where one of an account's secrets lives, canonical key first. Releases up to
+ * 4.0.0 hashed the username exactly as given, so that key follows as a legacy
+ * one to read from and clean up. The authenticator enrollment uses a separate
+ * `totp:` prefix so the seed can never be returned where a password is
+ * expected, and the same username rules so one account's two secrets live or
+ * die together. A Purdue-fork enrollment saved under the lowercased email is
+ * already the canonical key. TOTP idea from ElliotDrel/brightspace-mcp-server
+ * (branch codex/purdue-totp).
+ */
+function accountKeys(prefix, baseUrl, username) {
+    const origin = new URL(baseUrl).origin;
+    const key = (name) => `${prefix}:${createHash("sha256").update(JSON.stringify([origin, name])).digest("hex")}`;
+    const canonical = key(canonicalUsername(username));
+    const exact = key(username);
+    return exact === canonical ? [canonical] : [canonical, exact];
 }
 /**
- * The authenticator enrollment's own account, derived exactly like
- * passwordAccount (same origin + username, same casing rules) so one account's
- * two secrets live or die together, under a separate `totp:` prefix so the
- * seed can never be returned where a password is expected.
- * Idea from ElliotDrel/brightspace-mcp-server (branch codex/purdue-totp).
+ * Read a secret under its canonical key, falling back to a legacy key. A
+ * legacy secret is copied to the canonical key and removed only once the copy
+ * reads back intact; a store that refuses any step keeps the legacy entry,
+ * and the secret is returned either way.
  */
-function totpAccount(baseUrl, username) {
-    const identity = JSON.stringify([new URL(baseUrl).origin, username]);
-    return `totp:${createHash("sha256").update(identity).digest("hex")}`;
+async function getSecret(prefix, baseUrl, username, backend) {
+    const [canonical, ...legacy] = accountKeys(prefix, baseUrl, username);
+    const current = await backend.getPassword(SERVICE, canonical);
+    if (current !== null)
+        return current;
+    for (const account of legacy) {
+        const value = await backend.getPassword(SERVICE, account);
+        if (value === null)
+            continue;
+        try {
+            await backend.setPassword(SERVICE, canonical, value);
+            if (await backend.getPassword(SERVICE, canonical) === value)
+                await backend.deletePassword(SERVICE, account);
+        }
+        catch {
+            // Migration is best effort; the legacy entry still answers next time.
+        }
+        return value;
+    }
+    return null;
+}
+async function setSecret(prefix, baseUrl, username, value, backend, unverified) {
+    const [account] = accountKeys(prefix, baseUrl, username);
+    await backend.setPassword(SERVICE, account, value);
+    if (await backend.getPassword(SERVICE, account) !== value)
+        throw new NativeCredentialStoreError(unverified);
+}
+/** Remove the secret under every key it may sit under. Safe when none was saved. */
+async function deleteSecret(prefix, baseUrl, username, backend, kept) {
+    for (const account of accountKeys(prefix, baseUrl, username)) {
+        // Some native stores raise on deleting an entry that does not exist.
+        if (await backend.getPassword(SERVICE, account) === null)
+            continue;
+        await backend.deletePassword(SERVICE, account);
+        if (await backend.getPassword(SERVICE, account) !== null)
+            throw new NativeCredentialStoreError(kept);
+    }
 }
 /** The account's saved authenticator enrollment, or null when none was saved. */
 export async function getStoredTotpUri(baseUrl, username, backend = nativeCredentialBackend) {
-    return backend.getPassword(SERVICE, totpAccount(baseUrl, username));
+    return getSecret("totp", baseUrl, username, backend);
 }
 export async function setStoredTotpUri(baseUrl, username, uri, backend = nativeCredentialBackend) {
-    const account = totpAccount(baseUrl, username);
-    await backend.setPassword(SERVICE, account, uri);
-    if (await backend.getPassword(SERVICE, account) !== uri) {
-        throw new NativeCredentialStoreError("The authenticator enrollment could not be verified in the native credential store. Existing configuration was preserved.");
-    }
+    await setSecret("totp", baseUrl, username, uri, backend, "The authenticator enrollment could not be verified in the native credential store. Existing configuration was preserved.");
 }
 /** Remove an account's saved authenticator enrollment. Safe when none was saved. */
 export async function deleteStoredTotpUri(baseUrl, username, backend = nativeCredentialBackend) {
-    const account = totpAccount(baseUrl, username);
-    // Some native stores raise on deleting an entry that does not exist.
-    if (await backend.getPassword(SERVICE, account) === null)
-        return;
-    await backend.deletePassword(SERVICE, account);
-    if (await backend.getPassword(SERVICE, account) !== null) {
-        throw new NativeCredentialStoreError("The saved authenticator enrollment could not be removed from the native credential store.");
-    }
+    await deleteSecret("totp", baseUrl, username, backend, "The saved authenticator enrollment could not be removed from the native credential store.");
 }
 export async function getStoredPassword(baseUrl, username, backend = nativeCredentialBackend) {
-    return backend.getPassword(SERVICE, passwordAccount(baseUrl, username));
+    return getSecret("password", baseUrl, username, backend);
 }
 export async function setStoredPassword(baseUrl, username, password, backend = nativeCredentialBackend) {
-    const account = passwordAccount(baseUrl, username);
-    await backend.setPassword(SERVICE, account, password);
-    if (await backend.getPassword(SERVICE, account) !== password) {
-        throw new NativeCredentialStoreError("The saved password could not be verified in the native credential store. Existing configuration was preserved.");
-    }
+    await setSecret("password", baseUrl, username, password, backend, "The saved password could not be verified in the native credential store. Existing configuration was preserved.");
 }
 /** Remove an account's saved password, so passwordless sign-in leaves none behind. */
 export async function deleteStoredPassword(baseUrl, username, backend = nativeCredentialBackend) {
-    const account = passwordAccount(baseUrl, username);
-    // Some native stores raise on deleting an entry that does not exist.
-    if (await backend.getPassword(SERVICE, account) === null)
-        return;
-    await backend.deletePassword(SERVICE, account);
-    if (await backend.getPassword(SERVICE, account) !== null) {
-        throw new NativeCredentialStoreError("The saved password could not be removed from the native credential store. Existing configuration was preserved.");
-    }
+    await deleteSecret("password", baseUrl, username, backend, "The saved password could not be removed from the native credential store. Existing configuration was preserved.");
 }
 function decodeKey(value) {
     if (!/^[a-f0-9]{64}$/i.test(value)) {

package/build/auth/microsoft-session.js

@@ -7,6 +7,15 @@ 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 STAY_SIGNED_IN_NOTE = "Stay signed in keeps the Microsoft sign-in only; your school can still ask for 2FA on a new sign-in.";
+/** One sentence for each Don't ask again outcome, after STAY_SIGNED_IN_NOTE. */
+const REMEMBER_MFA_NOTES = {
+    ticked: "\"Don't ask again\" was ticked, so Microsoft may skip 2FA for a while; your school decides how long.",
+    already: "\"Don't ask again\" was already on, so Microsoft may skip 2FA for a while; your school decides how long.",
+    absent: "Your school's sign-in page didn't offer \"Don't ask again\", so 2FA is asked whenever your school requires it.",
+    unknown: "Whether \"Don't ask again\" applied isn't known yet; it is recorded at the next sign-in that reaches 2FA.",
+    off: "\"Don't ask again\" is off. To be asked less often, rerun setup and pick \"Less often\" (or set D2L_REMEMBER_MFA=true).",
+};
 /** The plain summary, relative to its session directory. */
 export const MICROSOFT_SESSION_FILE = "microsoft-session.json";
 const ENTRA_HOST = "login.microsoftonline.com";
@@ -80,5 +89,6 @@ export async function readMicrosoftSession(sessionDir, now = Date.now()) {
         staySignedInExpires: staySignedIn && expires > 0 ? new Date(expires * 1000).toISOString() : null,
         rememberMfa: summary.rememberMfa?.outcome ?? "unknown",
         rememberMfaAt: summary.rememberMfa?.at ?? null,
+        note: `${STAY_SIGNED_IN_NOTE} ${REMEMBER_MFA_NOTES[summary.rememberMfa?.outcome ?? "unknown"]}`,
     };
 }

package/build/auth/username.js

@@ -0,0 +1,15 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT. See LICENSE file for details.
+ */
+/**
+ * The form of a username that names its account. An email address (a
+ * Microsoft Entra or Google sign-in) is case-insensitive, so it is lowercased;
+ * a plain username keeps its case, because a school may treat it as
+ * case-sensitive. Surrounding whitespace is never part of anyone's name.
+ */
+export function canonicalUsername(username) {
+    const trimmed = username.trim();
+    return trimmed.includes("@") ? trimmed.toLowerCase() : trimmed;
+}

package/build/setup/config.js

@@ -5,6 +5,7 @@
  *
  * The settings setup saves, shared by the wizard, prepare and sign-in.
  */
+import { canonicalUsername } from "../auth/username.js";
 import { configStoreExists, loadConfigStore } from "../utils/config-store.js";
 // ── URL validation ─────────────────────────────────────────────────
 export function normalizeUrl(input) {
@@ -50,6 +51,16 @@ export function sameSchool(stored, chosen) {
         return false;
     }
 }
+/**
+ * The username to save: the typed one in canonical form, unless it names the
+ * account already saved. That one keeps its saved spelling, because releases
+ * up to 4.0.0 keyed its password, enrollment and session directory on the
+ * exact case, and only that spelling still derives those legacy keys.
+ */
+export function savedUsername(saved, typed) {
+    const canonical = canonicalUsername(typed);
+    return saved !== undefined && canonicalUsername(saved) === canonical ? saved : canonical;
+}
 /**
  * Merge the wizard's answers over the settings already saved.
  *
@@ -68,7 +79,7 @@ export function buildConfigToSave(existing, answers) {
     const config = {
         ...carried,
         baseUrl: answers.baseUrl,
-        username: answers.username,
+        username: savedUsername(carried?.username, answers.username),
         // Always the freshly typed one: a carried v1 plaintext password would
         // otherwise be the value written to the native store.
         password: answers.password,

package/build/setup/prepare.js

@@ -180,7 +180,7 @@ export async function runPrepare(args, overrides = {}) {
         delete config.password;
         delete config.totpUri;
         const notes = [];
-        if (carried?.username && args.username && carried.username !== args.username) {
+        if (carried?.username && args.username && carried.username !== config.username) {
             notes.push(`was ${carried.username}; sign-in starts fresh for the new account`);
         }
         if (!username)
@@ -214,7 +214,7 @@ export async function runPrepare(args, overrides = {}) {
         }
         if (username) {
             try {
-                const token = await deps.getSessionToken(baseUrl, sessionDirFor(deps.env, config, baseUrl, username));
+                const token = await deps.getSessionToken(baseUrl, sessionDirFor(deps.env, config, baseUrl, config.username));
                 signedIn = Boolean(token);
             }
             catch {

package/build/setup.js

@@ -21,7 +21,7 @@ import { askShortcutQuestion } from "./utils/two-factor-shortcuts.js";
 import { DOCTOR_COMMAND, prepareCommand, signInCommand } from "./utils/commands.js";
 import { serverCommand } from "./utils/mcp-client-cli.js";
 import { parseSetupArgs, SETUP_USAGE } from "./setup/args.js";
-import { buildConfigToSave, isValidUrl, normalizeUrl, readExistingConfig, sameSchool } from "./setup/config.js";
+import { buildConfigToSave, isValidUrl, normalizeUrl, readExistingConfig, sameSchool, savedUsername } from "./setup/config.js";
 import { detectMcpClients, isChatGPTInstalled } from "./setup/clients.js";
 import { presetForBaseUrl } from "./setup/presets.js";
 import { formatPrepare, runPrepare } from "./setup/prepare.js";
@@ -254,7 +254,9 @@ async function interactive(args) {
     }
     let preset = args.preset ?? (baseUrl ? presetForBaseUrl(baseUrl)?.preset : undefined);
     const carried = baseUrl && saved && sameSchool(saved.baseUrl, baseUrl) ? saved : null;
-    const knownUsername = args.username ?? (mode === "sign-in" ? carried?.username : undefined);
+    const knownUsername = args.username !== undefined
+        ? savedUsername(carried?.username, args.username)
+        : mode === "sign-in" ? carried?.username : undefined;
     let passwordSaved = false;
     if (mode === "sign-in" && baseUrl && knownUsername) {
         try {
@@ -341,6 +343,8 @@ async function interactive(args) {
     else {
         console.log(dim(`  Username: ${username}`));
     }
+    // The saved spelling of the same account still finds what 4.0.0 saved.
+    username = savedUsername(saved && sameSchool(saved.baseUrl, baseUrl) ? saved.username : undefined, username);
     console.log("");
     // ── Step 3: Password (hidden) ────────────────────────────────────
     let keepPassword = false;

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

@@ -57,7 +57,7 @@ export function registerGetServerInfo(server, config, version, apiClient, readSi
     server.registerTool("get_server_info", {
         title: "Get Server Info",
         annotations: { readOnlyHint: true },
-        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, the server's local timezone and UTC offset, (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in and the Don't ask again MFA checkbox, (when signed in) the account's uniqueName/displayName as signedInAs, and this process's request counters (requests: responses by status class, network errors, cache hits/misses, coalesced joins, and token refreshes). Use this for troubleshooting, when the user asks which version they have, or what timezone/account dates are being computed against. 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, the server's local timezone and UTC offset, (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in (which keeps the Microsoft sign-in but does not by itself skip 2FA) and the Don't ask again MFA checkbox, with a plain-language note on what that means for 2FA to relay to the user, (when signed in) the account's uniqueName/displayName as signedInAs, and this process's request counters (requests: responses by status class, network errors, cache hits/misses, coalesced joins, and token refreshes). Use this for troubleshooting, when the user asks which version they have, or what timezone/account dates are being computed against. Never contacts Brightspace and never returns secrets.",
         inputSchema: GetServerInfoSchema,
     }, async () => {
         const [microsoftSession, signedInAs] = await Promise.all([

package/build/utils/config.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { createHash } from "node:crypto";
@@ -10,6 +11,7 @@ import dotenv from "dotenv";
 import { configStoreExists, getConfigStorePath, loadConfigStore } from "./config-store.js";
 import { resolveStoredPassword } from "./secure-config.js";
 import { getStoredTotpUri } from "../auth/credential-store.js";
+import { canonicalUsername } from "../auth/username.js";
 import { normalizeTotpEnrollment } from "../auth/totp.js";
 import { migrateLegacyState } from "../auth/legacy-state.js";
 /**
@@ -165,8 +167,14 @@ export async function loadConfig() {
 export function accountSessionDirectory(root, baseUrl, username) {
     if (!username)
         return root;
-    const account = createHash("sha256").update(JSON.stringify([new URL(baseUrl).origin, username])).digest("hex");
-    return path.join(root, "accounts", account);
+    const origin = new URL(baseUrl).origin;
+    const directory = (name) => path.join(root, "accounts", createHash("sha256").update(JSON.stringify([origin, name])).digest("hex"));
+    const canonical = directory(canonicalUsername(username));
+    // Releases up to 4.0.0 named the directory after the username exactly as
+    // given. Its encryption key is tied to that path, so a session already
+    // saved there keeps being used rather than stranded.
+    const legacy = directory(username);
+    return legacy !== canonical && !fs.existsSync(canonical) && fs.existsSync(legacy) ? legacy : canonical;
 }
 /**
  * A token lifetime must be a whole, positive number of seconds. NaN, zero, a

package/package.json

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