brightspace-mcp-server 3.8.2 → 3.8.4

package/README.md

@@ -6,7 +6,7 @@ Talk to your Brightspace courses with AI. Ask about grades, due dates, quizzes,
 
 This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects your AI to D2L Brightspace so it can pull your grades, assignments, syllabus, and course content on demand.
 
-Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow, SUNY campus selection, Western University, and TU Delft NetID via SURFconext. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
+Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow, SUNY campus selection, Western University, TU Delft NetID via SURFconext, and CUNY Login. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/RohanMuppa/brightspace-mcp-server/main/docs/how-it-works.svg" alt="Architecture diagram" width="100%">
@@ -28,7 +28,7 @@ Paste this into Claude Code, Cursor, Windsurf, Copilot, Codex, or any AI coding
 ```
 Install brightspace-mcp-server for me by following
 https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
-(use --purdue at Purdue, --suny at SUNY, or --tudelft at TU Delft).
+(use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, or --cuny at CUNY).
 ```
 
 **Option 2: Run it yourself**
@@ -58,6 +58,16 @@ npx -y brightspace-mcp-server@latest setup --tudelft
 
 Use your NetID rather than your student email address. The TU Delft flow is headless NetID username and password sign-in only, including automatic re-authentication when the saved session expires; it does not support MFA or any other interactive step. If your account requires one, [open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) — that tenant isn't supported yet.
 
+CUNY students can add `--cuny`. Sign in with your full CUNY Login address
+(`firstname.lastname01@login.cuny.edu`); authentication asks in the terminal
+for the 6-digit code from your authenticator app. CUNY asks for that code on
+every full sign-in, so when your Brightspace session ends, run
+`npx -y brightspace-mcp-server@latest auth` in a terminal again:
+
+```bash
+npx -y brightspace-mcp-server@latest setup --cuny
+```
+
 The wizard saves your password in the native credential store and asks how you'll complete MFA: wait for approval or number matching, enter a terminal code from Google Authenticator or another app, or use a visible browser for other interactive methods. It can also configure Claude Desktop, Cursor, Codex Desktop and CLI, and Claude Code when installed — restart your AI client when it finishes.
 
 Any other D2L school: run `setup` without a flag and paste your Brightspace URL (for example `https://yourschool.brightspace.com`).

package/build/auth/browser-auth.js

@@ -26,7 +26,9 @@ const SILENT_SSO = {
     // get past this gate otherwise.
     emailFields: ["input[type=email]", "input[name=loginfmt]", "input[name=j_username]", "input#signinid"],
     credentialFields: ['input#username', 'input#userName', 'input[type="password"]'],
-    mfaChallenges: ["#idRichContext_DisplaySign", "#idDiv_SAOTCAS_Title", "#idDiv_SAOTCC_Title"],
+    // Entra's number match and code prompts, then CUNY Login's authenticator-code
+    // field (cuny-sso.ts CUNY_TOTP_SELECTOR).
+    mfaChallenges: ["#idRichContext_DisplaySign", "#idDiv_SAOTCAS_Title", "#idDiv_SAOTCC_Title", '[id="otpValue|input"]'],
     campusSaml: 'a[href*="/d2l/lp/auth/saml/initiate-login"]',
     kmsiCheckbox: "#KmsiCheckboxField",
     kmsiTitle: "Stay signed in?",

package/build/auth/cuny-sso.js

@@ -0,0 +1,216 @@
+/** CUNY login entry point. Licensed under MIT; see LICENSE. */
+import { BrowserAuthError } from "../utils/errors.js";
+import { log } from "../utils/logger.js";
+import { AUTH_COMMAND, SETUP_COMMAND } from "../utils/commands.js";
+import { MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
+/** All CUNY campuses share one Brightspace tenant behind CUNY Login (Oracle OAM). */
+const CUNY_BRIGHTSPACE_HOST = "brightspace.cuny.edu";
+const CUNY_LOGIN_HOST = "ssologin.cuny.edu";
+/**
+ * Oracle JET generates the authenticator-code field's id with a pipe in it,
+ * which is not valid in an `#id` selector, so match the attribute instead.
+ * browser-auth.ts lists the same selector so a run that resumes on this page
+ * is recognized as an MFA challenge.
+ */
+export const CUNY_TOTP_SELECTOR = '[id="otpValue|input"]';
+const SELECTORS = {
+    // The visible field takes the full @login.cuny.edu address. CUNY's own
+    // submit handler copies the short name into a hidden #CUNYLoginUsername,
+    // so that hidden field is left for the page to fill.
+    username: "#CUNYLoginUsernameDisplay",
+    password: "#CUNYLoginPassword",
+    submit: "#submit",
+    // Only rendered on the reload OAM serves after rejecting the password.
+    serverError: "#serverError",
+    totp: CUNY_TOTP_SELECTOR,
+};
+const POLL_MS = 500;
+/** CUNY parks on a processing page for about ten seconds before the code challenge. */
+const CHALLENGE_TIMEOUT_MS = 60_000;
+/** A person has to find their authenticator and read a code. */
+const MFA_TIMEOUT_MS = 5 * 60 * 1000;
+/** True for the shared CUNY Brightspace instance. */
+export function isCunyBrightspace(baseUrl) {
+    try {
+        return new URL(baseUrl).hostname.toLowerCase() === CUNY_BRIGHTSPACE_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compare hosts, not substrings: the SAML round trip carries other hosts in its query. */
+function isCunyLogin(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" && parsed.hostname.toLowerCase() === CUNY_LOGIN_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+/** A rejected code reloads the challenge with `?emsg=Entered+TOTP+is+incorrect.` */
+function hasErrorMessage(url) {
+    try {
+        return new URL(url).searchParams.has("emsg");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Login flow for CUNY Brightspace.
+ *
+ * Brightspace federates by SAML to CUNY Login at ssologin.cuny.edu, an Oracle
+ * Access Manager page rather than Entra, Shibboleth, or Duo:
+ *
+ *   /d2l/login → /oamfed/idp/samlv20 (username + password)
+ *     → /oaa/authnui (a "Processing Request" page, roughly ten seconds)
+ *     → /oaa-totp-factor/rui/index.html (authenticator code) → /d2l/home
+ *
+ * Its username field is a plain text input, which none of the default flow's
+ * username selectors match, and its code challenge is an Oracle JET page the
+ * default MFA loop does not know. The code itself still comes from a person,
+ * through the same terminal prompt or visible browser every other code-based
+ * MFA uses.
+ */
+export class CunySSOFlow {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    hasCredentials() {
+        return Boolean(this.config.username && this.config.password);
+    }
+    async login(page) {
+        try {
+            log("INFO", "Starting CUNY Login sign-in flow");
+            await this.completeLogin(page);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof BrowserAuthError)
+                throw error;
+            throw new UnsupportedAuthenticationError("CUNY Login could not complete automatic sign-in. Check saved credentials and your authenticator settings.", error);
+        }
+    }
+    /**
+     * Poll the page and answer whichever CUNY Login step is on screen. A run
+     * can hand over mid-flow (awaitSilentSSO also stops on the code page), so
+     * no step is assumed to come first.
+     */
+    async completeLogin(page) {
+        // A visible browser may be answering a different CUNY MFA method by hand.
+        let deadline = Date.now() + (this.config.headless === false ? MFA_TIMEOUT_MS : CHALLENGE_TIMEOUT_MS);
+        let credentialsSubmitted = false;
+        let challenged = false;
+        /** The challenge URL a code was submitted from; a reload away from it with ?emsg= is a rejection. */
+        let codeSubmittedFrom = null;
+        let announced = false;
+        while (Date.now() < deadline) {
+            if (await this.isAuthenticated(page)) {
+                log("INFO", "Login successful - verified Brightspace home");
+                return;
+            }
+            // Never type the CUNY password into anything but CUNY Login itself.
+            if (isCunyLogin(page.url())) {
+                if (await this.isVisible(page, SELECTORS.serverError)) {
+                    throw new BrowserAuthError(`CUNY Login rejected the saved username or password. Run \`${SETUP_COMMAND} --cuny\` to update them.`, "credentials");
+                }
+                if (await this.isVisible(page, SELECTORS.totp)) {
+                    if (!challenged) {
+                        challenged = true;
+                        deadline = Date.now() + MFA_TIMEOUT_MS;
+                    }
+                    if (this.config.headless === false) {
+                        // The person at the window types the code and can retry a typo
+                        // there, so a rejection is theirs to answer, not a failure here.
+                        if (!announced) {
+                            announced = true;
+                            log("WARN", "Enter the code from your authenticator app in the CUNY Login window. Waiting up to 5 minutes.");
+                            this.config.onMfaChallenge?.(null);
+                        }
+                    }
+                    else {
+                        const url = page.url();
+                        if (codeSubmittedFrom !== null && url !== codeSubmittedFrom && hasErrorMessage(url)) {
+                            throw new MfaApprovalError(new Error("CUNY Login rejected the authenticator code."));
+                        }
+                        if (codeSubmittedFrom === null) {
+                            codeSubmittedFrom = url;
+                            await this.submitCode(page);
+                        }
+                    }
+                }
+                else if (!credentialsSubmitted && await this.isVisible(page, SELECTORS.username)) {
+                    // CUNY Login asks for a code on every full sign-in and does not
+                    // re-federate Brightspace from its own cookies, so a headless run with
+                    // no terminal (the MCP server's background re-authentication) can
+                    // never finish. Stop before the password is sent: otherwise every tool
+                    // call after the session ends posts it again, and a stale saved
+                    // password would keep counting toward a CUNY lockout.
+                    if (this.config.headless !== false && !this.config.requestMfaCode)
+                        throw this.codePromptUnavailable();
+                    credentialsSubmitted = true;
+                    await this.enterCredentials(page);
+                }
+            }
+            await page.waitForTimeout(POLL_MS);
+        }
+        if (challenged)
+            throw new MfaApprovalError();
+        throw new UnsupportedAuthenticationError("CUNY Login did not reach the authenticator-code challenge or Brightspace. If your default CUNY MFA method is not an authenticator app, set D2L_HEADLESS=false and finish sign-in in the browser.");
+    }
+    async enterCredentials(page) {
+        if (!this.config.username)
+            throw new BrowserAuthError("Username is required for SSO login", "credentials");
+        if (!this.config.password)
+            throw new BrowserAuthError("Password is required for SSO login", "credentials");
+        log("INFO", "Entering CUNY Login credentials");
+        await page.locator(SELECTORS.username).first().fill(this.config.username);
+        await page.locator(SELECTORS.password).first().fill(this.config.password);
+        // OAM answers the POST with a full navigation, which can detach the button.
+        await page.locator(SELECTORS.submit).first().click().catch(() => { });
+    }
+    codePromptUnavailable() {
+        return new UnsupportedAuthenticationError(`CUNY Login requires an authenticator code. Run \`${AUTH_COMMAND}\` in a terminal to enter it.`);
+    }
+    /** Feed CUNY's code challenge from the terminal prompt. */
+    async submitCode(page) {
+        if (!this.config.requestMfaCode)
+            throw this.codePromptUnavailable();
+        const code = (await this.config.requestMfaCode()).replace(/\s/g, "");
+        if (!/^\d{6,8}$/.test(code))
+            throw new UnsupportedAuthenticationError("The MFA code must contain 6-8 digits.");
+        await page.locator(SELECTORS.totp).first().fill(code);
+        // Oracle JET gives the Verify button no id; its label is the stable handle.
+        const verify = page.getByRole("button", { name: /^\s*verify\s*$/i }).first();
+        if (await verify.isVisible().catch(() => false))
+            await verify.click().catch(() => { });
+        else
+            await page.locator(SELECTORS.totp).first().press("Enter");
+        log("INFO", "Authenticator code submitted");
+    }
+    async isVisible(page, selector) {
+        return page.locator(selector).first().isVisible().catch(() => false);
+    }
+    /** The login shell also exposes D2L.LP, so verify origin and home as well. */
+    async isAuthenticated(page) {
+        try {
+            const expected = new URL(this.config.baseUrl ?? `https://${CUNY_BRIGHTSPACE_HOST}`);
+            const current = new URL(page.url());
+            if (current.origin !== expected.origin || !/^\/d2l\/home(?:\/|$)/.test(current.pathname))
+                return false;
+            const cookies = await page.context().cookies(expected.origin);
+            if (!cookies.some(cookie => cookie.name === "d2lSessionVal" && Boolean(cookie.value)))
+                return false;
+            return await page.evaluate(() => {
+                const d2l = window.D2L;
+                return Boolean(d2l?.LP);
+            });
+        }
+        catch {
+            // Redirects can replace the execution context mid-check. Keep polling.
+            return false;
+        }
+    }
+}

package/build/auth/index.js

@@ -7,6 +7,7 @@ export { BrowserAuth } from "./browser-auth.js";
 export { PurdueSSOFlow } from "./purdue-sso.js";
 export { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
 export { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
+export { CunySSOFlow, isCunyBrightspace } from "./cuny-sso.js";
 export { createSSOFlow } from "./sso-flow.js";
 export { TokenManager } from "./token-manager.js";
 export { SessionStore } from "./session-store.js";

package/build/auth/purdue-sso.js

@@ -318,6 +318,12 @@ export class PurdueSSOFlow {
         let resendNotFoundWarned = false;
         try {
             while (Date.now() < deadline) {
+                // A verified session outranks whatever challenge controls linger on
+                // screen: answering them would prompt or announce for nothing.
+                if (await this.isAuthenticated(page)) {
+                    log("INFO", "Login successful - verified Brightspace home");
+                    return;
+                }
                 if (await this.duoMfa.handle(page))
                     challenged = true;
                 if (await this.submitMfaCode(page))
@@ -349,10 +355,6 @@ export class PurdueSSOFlow {
                     numberVanishedAt = null;
                     resendNotFoundWarned = false;
                 }
-                if (await this.isAuthenticated(page)) {
-                    log("INFO", "Login successful - verified Brightspace home");
-                    return;
-                }
                 // Fix 2: Entra's number-match request itself times out (or the user
                 // taps Deny) well before the 5-minute budget above. Once that has
                 // happened, ask Entra for another one instead of polling a dead

package/build/auth/sso-flow.js

@@ -7,6 +7,7 @@ import { PurdueSSOFlow } from "./purdue-sso.js";
 import { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
 import { WesternSSOFlow, isWesternBrightspace } from "./western-sso.js";
 import { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
+import { CunySSOFlow, isCunyBrightspace } from "./cuny-sso.js";
 import { BrowserAuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 export class UnsupportedAuthenticationError extends BrowserAuthError {
@@ -55,5 +56,8 @@ export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
     if (isWesternBrightspace(config.baseUrl)) {
         return new WesternSSOFlow(credentials);
     }
+    if (isCunyBrightspace(config.baseUrl)) {
+        return new CunySSOFlow(credentials);
+    }
     return new PurdueSSOFlow(credentials);
 }

package/build/setup.js

@@ -52,9 +52,16 @@ export const SCHOOL_PRESETS = {
         mfaNote: "Approve the sign-in request from your MFA app.",
         usernameHint: "Use your full sign-in address if your Western account requires it.",
     },
+    cuny: {
+        name: "CUNY",
+        baseUrl: "https://brightspace.cuny.edu",
+        usernameLabel: "CUNY Login username",
+        mfaNote: "Type the 6-digit code from your authenticator app when prompted.",
+        usernameHint: "Use your full CUNY Login address, e.g. firstname.lastname01@login.cuny.edu",
+    },
 };
 /**
- * Pick the school preset named by `--purdue`, `--suny`, `--western`, etc.
+ * Pick the school preset named by `--purdue`, `--suny`, `--western`, `--cuny`, etc.
  *
  * Own properties only: a bare index would make `--constructor` or
  * `--__proto__` resolve to something off `Object.prototype` and hand the

package/package.json

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