brightspace-mcp-server 3.9.0 → 3.9.2

package/README.md

@@ -111,6 +111,8 @@ Claude Desktop uses a separate configuration, which the setup wizard can update
 
 </details>
 
+Building against this server or opening a PR? See [STABILITY.md](STABILITY.md) for what's safe to rely on and what counts as a breaking change.
+
 **Running from a source checkout or fork?** When a newer release is published, the server tells a source checkout to `git pull` and `npm run build` rather than to install the npm package. For a fork you maintain, set `D2L_NO_UPDATE_CHECK=1` in the server's environment to turn off upstream update notices.
 
 ## Session Expired?
@@ -129,6 +131,35 @@ npx -y brightspace-mcp-server@latest auth
 
 Run it from your home folder — macOS blocks `npx` from Documents, Desktop, or Downloads without Files and Folders permission (`EPERM`). Grant access in System Settings → Privacy & Security → Files and Folders, or run elsewhere.
 
+## No browser? Paste a session cookie or token
+
+The normal setup drives a real (usually hidden) browser through sign-in, which doesn't work in Docker, headless Linux, WSL without a display, or on a tenant whose MFA requires a hardware security key. Two environment variables skip the browser entirely; set one and leave the normal setup untouched:
+
+- **`D2L_SESSION_COOKIE`** — the `d2lSessionVal` and `d2lSecureSessionVal` cookies from a browser tab where you're already signed in to Brightspace. In Chrome DevTools: open your Brightspace site, **F12 → Application → Cookies**, find `d2lSessionVal` and `d2lSecureSessionVal`, and set the variable to either form:
+  ```bash
+  export D2L_SESSION_COOKIE="d2lSessionVal=<value>; d2lSecureSessionVal=<value>"
+  # or just the two values, in that order:
+  export D2L_SESSION_COOKIE="<d2lSessionVal>;<d2lSecureSessionVal>"
+  ```
+- **`D2L_ACCESS_TOKEN`** — a pre-issued Bearer token (an admin-issued Valence token, or one minted by a TA script):
+  ```bash
+  export D2L_ACCESS_TOKEN="<token>"
+  ```
+
+Set either in your MCP client's `env` config instead of a shell export if you're not running the server from a terminal. If both are set, `D2L_ACCESS_TOKEN` wins.
+
+If this is a Docker or other headless setup with no `~/.brightspace-mcp/config.json` on disk, also set **`D2L_BASE_URL`** to your school's Brightspace URL — with no config file to read it from, the server otherwise defaults to Purdue's.
+
+**The catch:** neither one renews itself. A pasted session cookie dies at D2L's own idle timeout (the same timeout that would eventually log you out in a browser), and a pre-issued token dies whenever it expires or is revoked. When that happens the server does **not** fall back to a browser login — it answers with an error telling you to paste a fresh value. There's no in-between: this is a deliberate escape hatch for environments that can't run a browser at all, not a way to skip typing your password once.
+
+## Troubleshooting
+
+**Where to find logs:** MCP clients log the server's stderr themselves. On **macOS**, Claude Desktop writes to `~/Library/Logs/Claude/mcp*.log` (one file per server, plus `mcp.log` for the client itself). On **Windows**, it's `%APPDATA%\Claude\logs`. Other clients vary — check their own logs or output panel for the `brightspace-mcp-server` process.
+
+**Works in a terminal but not in the client:** the client launches the server as its own subprocess, which doesn't inherit your shell's environment. Common causes: the native credential store is locked (a GUI app started before you unlocked your keyring or logged into macOS won't get a Keychain prompt the way a terminal does), `HOME` or `PATH` differ for GUI-launched processes versus your shell, or `npx` resolves a different cached version than the one on your `PATH`. To check, run the exact registered command (`npx -y brightspace-mcp-server@latest`, or `cmd /c npx -y brightspace-mcp-server@latest` on Windows) from a fresh terminal with no extra environment set, and compare.
+
+**Which version am I running:** ask the assistant anything that calls `get_server_info` — it reports the running version, Node runtime, and config/session paths with no network call. If you're on a source checkout instead of the published npm package, that version comes from the local `build/` output, so it only reflects your latest `npm run build`, not what's on npm.
+
 ## What You Can Ask About
 
 | Topic | Examples |

package/build/api/client.js

@@ -76,6 +76,7 @@ export class D2LApiClient {
     cacheTTLs;
     timeoutMs;
     onAuthExpired;
+    authExpiredMessage;
     retryConfig;
     versions = null;
     /** Single in-flight discovery, so concurrent first requests share one fetch. */
@@ -119,6 +120,7 @@ export class D2LApiClient {
         this.tokenManager = options.tokenManager;
         this.timeoutMs = options.timeoutMs ?? 30_000;
         this.onAuthExpired = options.onAuthExpired;
+        this.authExpiredMessage = options.authExpiredMessage;
         this.retryConfig = options.retry ?? {};
         // Merge user-provided TTLs with defaults
         this.cacheTTLs = { ...DEFAULT_CACHE_TTLS, ...options.cacheTTLs };
@@ -351,7 +353,7 @@ export class D2LApiClient {
             }
             log("WARN", "Auto-reauthentication did not produce a valid token");
         }
-        throw new ApiError(401, path, `Session expired. Please re-authenticate via ${AUTH_COMMAND}.`);
+        throw new ApiError(401, path, this.authExpiredMessage ?? `Session expired. Please re-authenticate via ${AUTH_COMMAND}.`);
     }
     /**
      * Make one HTTP request. Authentication recovery is shared with raw downloads.

package/build/auth/token-manager.js

@@ -24,6 +24,8 @@ export class TokenManager {
     baseUrl;
     tokenTtl;
     mint;
+    envAccessToken;
+    envSessionCookie;
     /** Single in-flight mint, so concurrent callers share one request. */
     mintInFlight = null;
     rejectedAccessToken = null;
@@ -35,6 +37,8 @@ export class TokenManager {
         this.baseUrl = options.baseUrl ? new URL(options.baseUrl).origin : undefined;
         this.tokenTtl = options.tokenTtl ?? DEFAULT_TOKEN_TTL_SECONDS;
         this.mint = options.mint ?? mintAccessToken;
+        this.envAccessToken = options.envAccessToken;
+        this.envSessionCookie = options.envSessionCookie;
     }
     /**
      * Get the current token if valid, otherwise null.
@@ -44,6 +48,21 @@ export class TokenManager {
     async getToken(rejectedAccessToken) {
         if (rejectedAccessToken)
             this.rejectedAccessToken = rejectedAccessToken;
+        // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE bypass disk, mint, and the browser
+        // entirely: every call hands back the same env-derived token. The only
+        // way this "expires" is Brightspace rejecting it, which the caller
+        // reports back as rejectedAccessToken — at that point there is nothing
+        // fresher to offer, so this returns null rather than the same rejected
+        // value again. (See D2LApiClient.tryAutoReauth / authExpiredMessage for
+        // the user-facing "paste a fresh one" error this produces.)
+        if (this.envAccessToken || this.envSessionCookie) {
+            const token = this.buildEnvToken();
+            if (rejectedAccessToken && token.accessToken === rejectedAccessToken) {
+                log("DEBUG", "The env-provided credential was rejected; no replacement is available");
+                return null;
+            }
+            return token;
+        }
         // Check memory cache first
         if (this.cachedToken && this.isUsable(this.cachedToken)) {
             log("DEBUG", "Returning cached token");
@@ -69,6 +88,36 @@ export class TokenManager {
         log("DEBUG", "No valid token available");
         return null;
     }
+    /**
+     * Build the token for D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE;
+     * D2L_ACCESS_TOKEN wins when both are set. expiresAt is pushed far into the
+     * future: a pasted credential has no known lifetime, and isValid()'s
+     * refresh-buffer check must never be the thing that discards it — only
+     * Brightspace actually rejecting it (a 401) should.
+     */
+    buildEnvToken() {
+        const now = Date.now();
+        const FAR_FUTURE_MS = 10 * 365 * 24 * 60 * 60 * 1000; // 10 years
+        if (this.envAccessToken) {
+            return {
+                accessToken: this.envAccessToken,
+                tenantOrigin: this.baseUrl,
+                capturedAt: now,
+                expiresAt: now + FAR_FUTURE_MS,
+                source: "env",
+            };
+        }
+        return {
+            // Reuses the client's existing "cookie:" passthrough (see
+            // D2LApiClient.buildAuthHeaders) instead of minting a Bearer JWT.
+            accessToken: `cookie:${this.envSessionCookie}`,
+            tenantOrigin: this.baseUrl,
+            capturedAt: now,
+            expiresAt: now + FAR_FUTURE_MS,
+            source: "env",
+            cookieHeader: this.envSessionCookie,
+        };
+    }
     /**
      * Only use persisted session material, including updates from other processes.
      */

package/build/index.js

@@ -67,18 +67,33 @@ else {
                 sessionDir: config.sessionDir,
                 baseUrl: config.baseUrl,
                 tokenTtl: config.tokenTtl,
+                envAccessToken: config.envAccessToken,
+                envSessionCookie: config.envSessionCookie,
             });
-            // Create AuthRunner for auto-reauthentication
-            const authRunner = new AuthRunner({
-                onProgress: (message) => {
-                    void server.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
-                },
-            });
+            // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE are opt-in browser-free sign-in
+            // escape hatches (Docker, headless Linux, WSL, hardware-key MFA
+            // tenants). When either is set, AuthRunner is never created: there is
+            // no stored credential to drive a browser login from, and a rejected
+            // pasted credential should fail with a clear "paste a fresh one"
+            // message rather than spawning auth-cli.
+            const envAuthActive = Boolean(config.envAccessToken || config.envSessionCookie);
+            const authRunner = envAuthActive
+                ? undefined
+                : new AuthRunner({
+                    onProgress: (message) => {
+                        void server.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
+                    },
+                });
             // Create D2L API Client with auto-reauth support
             const apiClient = new D2LApiClient({
                 baseUrl: config.baseUrl,
                 tokenManager,
-                onAuthExpired: () => authRunner.run(),
+                onAuthExpired: authRunner ? () => authRunner.run() : undefined,
+                authExpiredMessage: config.envAccessToken
+                    ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
+                    : config.envSessionCookie
+                        ? "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set."
+                        : undefined,
             });
             // Nothing here reaches Brightspace. API versions are discovered by the
             // first request that needs them, and the first request with no saved

package/build/utils/config.js

@@ -49,6 +49,12 @@ export async function loadConfig() {
     const activeOnly = envBoolean(process.env.D2L_ACTIVE_ONLY, "D2L_ACTIVE_ONLY")
         ?? store?.activeOnly
         ?? true;
+    // D2L_ACCESS_TOKEN beats D2L_SESSION_COOKIE beats the normal stored-credential
+    // browser flow; both are validated whenever present regardless of which one
+    // wins, so a typo in the losing variable still fails loudly at startup.
+    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.");
@@ -70,6 +76,8 @@ export async function loadConfig() {
         username,
         password,
         campus: process.env.D2L_CAMPUS || store?.campus,
+        envAccessToken,
+        envSessionCookie,
         courseFilter: {
             includeCourseIds,
             excludeCourseIds,
@@ -115,6 +123,76 @@ function envBoolean(value, source) {
     console.error(`[config] Ignoring ${source}=${JSON.stringify(value)}: expected true or false`);
     return undefined;
 }
+/** CR, LF, or NUL in a header value enables request smuggling / header injection. */
+const CONTROL_CHAR_PATTERN = /[\r\n\0]/;
+/**
+ * Validate a pasted auth secret (D2L_SESSION_COOKIE or D2L_ACCESS_TOKEN).
+ * Unlike positiveSeconds/envBoolean above, a bad value here is never silently
+ * ignored: both env vars exist specifically to skip the browser, so a typo
+ * must fail loudly at startup rather than fall back to a sign-in flow the
+ * user deliberately avoided. Returns undefined only when the variable is
+ * genuinely unset (absent or empty), matching the other env helpers' treatment
+ * of "".
+ *
+ * The CR/LF/NUL check is adapted from the injection guard in
+ * JhostinAleck/brightspace-mcp (MIT), AccessToken.ts:10-19. Surrounding
+ * whitespace is rejected rather than trimmed: a trailing newline or space is
+ * exactly the kind of thing a terminal paste or `export FOO=$(cat file)`
+ * leaves behind, and silently stripping it would hide the mistake instead of
+ * surfacing it.
+ */
+export function readEnvSecret(value, varName) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (CONTROL_CHAR_PATTERN.test(value)) {
+        throw new Error(`${varName} contains a carriage return, line feed, or NUL character. Paste the value as a single line with no embedded newlines.`);
+    }
+    if (value !== value.trim()) {
+        throw new Error(`${varName} has leading or trailing whitespace. Remove it and try again.`);
+    }
+    return value;
+}
+const D2L_SESSION_VAL = "d2lSessionVal";
+const D2L_SECURE_SESSION_VAL = "d2lSecureSessionVal";
+const SESSION_COOKIE_FORMAT_ERROR = 'D2L_SESSION_COOKIE must be either "d2lSessionVal=...; d2lSecureSessionVal=..." ' +
+    "(the cookie header copied from a logged-in browser) or the two cookie values " +
+    "separated by a semicolon, in that order (d2lSessionVal;d2lSecureSessionVal).";
+/**
+ * Normalize D2L_SESSION_COOKIE into the "d2lSessionVal=...; d2lSecureSessionVal=..."
+ * header D2L's API expects. Accepts a full cookie-header fragment (extra
+ * cookies alongside the two named ones are ignored, order doesn't matter) or
+ * the two raw values separated by a semicolon with no cookie names, in which
+ * case the first is d2lSessionVal and the second d2lSecureSessionVal.
+ */
+export function parseSessionCookieEnv(raw) {
+    const segments = raw.split(";").map((part) => part.trim()).filter((part) => part.length > 0);
+    const named = {};
+    // The form is decided by whether a segment is NAMED d2lSessionVal/
+    // d2lSecureSessionVal (its name before the first "="), not by whether any
+    // "=" appears at all -- the two-raw-values form's second value can itself
+    // contain "=" (base64 padding), which must not be mistaken for a name.
+    let anyNamed = false;
+    for (const segment of segments) {
+        const eq = segment.indexOf("=");
+        if (eq === -1)
+            continue;
+        const name = segment.slice(0, eq).trim();
+        if (name === D2L_SESSION_VAL || name === D2L_SECURE_SESSION_VAL) {
+            anyNamed = true;
+            named[name] = segment.slice(eq + 1).trim();
+        }
+    }
+    if (anyNamed) {
+        if (named[D2L_SESSION_VAL] && named[D2L_SECURE_SESSION_VAL]) {
+            return `${D2L_SESSION_VAL}=${named[D2L_SESSION_VAL]}; ${D2L_SECURE_SESSION_VAL}=${named[D2L_SECURE_SESSION_VAL]}`;
+        }
+    }
+    else if (segments.length === 2) {
+        const [sessionVal, secureSessionVal] = segments;
+        return `${D2L_SESSION_VAL}=${sessionVal}; ${D2L_SECURE_SESSION_VAL}=${secureSessionVal}`;
+    }
+    throw new Error(SESSION_COOKIE_FORMAT_ERROR);
+}
 function expandTilde(filePath) {
     if (filePath.startsWith("~")) {
         return path.join(os.homedir(), filePath.slice(1));

package/package.json

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