brightspace-mcp-server 5.1.18 → 5.1.20

package/build/api/client.js

@@ -7,7 +7,7 @@ import { DEFAULT_CACHE_TTLS } from "./types.js";
 import { TTLCache } from "./cache.js";
 import { TokenBucket } from "./rate-limiter.js";
 import { discoverVersions } from "./version-discovery.js";
-import { ApiError, RateLimitError, NetworkError } from "./errors.js";
+import { ApiError, CredentialRejectedError, RateLimitError, NetworkError } from "./errors.js";
 import { withRetry, isRetryableFailure, retryAfterMsFrom, parseRetryAfter, } from "./retry.js";
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
@@ -475,7 +475,9 @@ export class D2LApiClient {
             }
             log("WARN", "Auto-reauthentication did not produce a valid token");
         }
-        throw new ApiError(401, path, this.authExpiredMessage ?? `Session expired. Please re-authenticate via ${AUTH_COMMAND}.`);
+        if (this.authExpiredMessage)
+            throw new CredentialRejectedError(path, this.authExpiredMessage);
+        throw new ApiError(401, path, `Session expired. Please re-authenticate via ${AUTH_COMMAND}.`);
     }
     /**
      * Make one HTTP request. Authentication recovery is shared with raw downloads.

package/build/api/errors.js

@@ -17,6 +17,19 @@ export class ApiError extends AuthError {
         this.name = "ApiError";
     }
 }
+/**
+ * A 401 for a credential pasted into the environment (D2L_ACCESS_TOKEN or
+ * D2L_SESSION_COOKIE). No browser sign-in stands behind it, so the user is
+ * told how to replace the credential rather than to run the auth command.
+ */
+export class CredentialRejectedError extends ApiError {
+    guidance;
+    constructor(endpoint, guidance) {
+        super(401, endpoint, guidance);
+        this.guidance = guidance;
+        this.name = "CredentialRejectedError";
+    }
+}
 // Generic HTTP error (non-401/429) - semantic alias for ApiError
 export class HttpError extends ApiError {
     constructor(status, endpoint, message, responseBody, cause) {

package/build/api/index.js

@@ -12,5 +12,5 @@ export { discoverVersions } from "./version-discovery.js";
 export { TTLCache } from "./cache.js";
 export { TokenBucket } from "./rate-limiter.js";
 // Errors
-export { ApiError, RateLimitError, NetworkError } from "./errors.js";
+export { ApiError, CredentialRejectedError, RateLimitError, NetworkError } from "./errors.js";
 export { DEFAULT_CACHE_TTLS } from "./types.js";

package/build/auth/token-manager.js

@@ -5,6 +5,7 @@
  */
 import { SessionStore } from "./session-store.js";
 import { mintAccessToken } from "./token-mint.js";
+import { fetchXsrfToken } from "./xsrf-fetch.js";
 import { log } from "../utils/logger.js";
 import { TokenRefreshError } from "../api/errors.js";
 import { devActivity } from "../utils/dev-activity.js";
@@ -15,6 +16,8 @@ import { devActivity } from "../utils/dev-activity.js";
 const REFRESH_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
 /** Matches the tokenTtl default in the app config. */
 const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+/** How long a D2L_SESSION_COOKIE mint that failed in transit waits before trying again. */
+const ENV_MINT_RETRY_MS = 60 * 1000;
 /**
  * TokenManager manages token lifecycle with in-memory caching and disk persistence.
  * Handles expiry detection with a configurable refresh buffer.
@@ -25,8 +28,18 @@ export class TokenManager {
     baseUrl;
     tokenTtl;
     mint;
+    fetchXsrf;
     envAccessToken;
     envSessionCookie;
+    mintEnvCookie;
+    /** The Bearer JWT minted from envSessionCookie, memory only. */
+    envMinted = null;
+    /** The XSRF token that last minted successfully, reused for the hourly re-mint. */
+    envCsrfToken;
+    /** Set once the env cookie is known not to mint, so later calls skip straight to the passthrough. */
+    envMintDisabled = false;
+    envMintRetryAt = 0;
+    envMintInFlight = null;
     /** Single in-flight mint, so concurrent callers share one request. */
     mintInFlight = null;
     rejectedAccessToken = null;
@@ -53,8 +66,10 @@ 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.fetchXsrf = options.fetchXsrf ?? fetchXsrfToken;
         this.envAccessToken = options.envAccessToken;
         this.envSessionCookie = options.envSessionCookie;
+        this.mintEnvCookie = options.mintEnvCookie ?? false;
     }
     /**
      * Get the current token if valid, otherwise null.
@@ -72,6 +87,11 @@ export class TokenManager {
         // value again. (See D2LApiClient.tryAutoReauth / authExpiredMessage for
         // the user-facing "paste a fresh one" error this produces.)
         if (this.envAccessToken || this.envSessionCookie) {
+            if (!this.envAccessToken && this.mintEnvCookie && this.baseUrl) {
+                const minted = await this.envCookieBearer(rejectedAccessToken);
+                if (minted)
+                    return minted;
+            }
             const token = this.buildEnvToken();
             if (rejectedAccessToken && token.accessToken === rejectedAccessToken) {
                 log("DEBUG", "The env-provided credential was rejected; no replacement is available");
@@ -255,6 +275,75 @@ export class TokenManager {
             cookieHeader: this.envSessionCookie,
         };
     }
+    /**
+     * The Bearer JWT minted from envSessionCookie, minting one when there is
+     * none or it expired or was just rejected. Null means use the cookie
+     * passthrough instead, which also keeps the existing "paste a fresh one"
+     * error for a dead cookie.
+     */
+    async envCookieBearer(rejectedAccessToken) {
+        if (this.envMinted && rejectedAccessToken === this.envMinted.accessToken) {
+            log("DEBUG", "The JWT minted from D2L_SESSION_COOKIE was rejected; minting again");
+            this.envMinted = null;
+        }
+        if (this.envMinted && this.isValid(this.envMinted))
+            return this.envMinted;
+        if (this.envMintDisabled || Date.now() < this.envMintRetryAt)
+            return null;
+        this.envMintInFlight ??= this.runEnvMint().finally(() => {
+            this.envMintInFlight = null;
+        });
+        return this.envMintInFlight;
+    }
+    async runEnvMint() {
+        const baseUrl = this.baseUrl;
+        const cookieHeader = this.envSessionCookie;
+        let csrfToken = this.envCsrfToken;
+        if (!csrfToken) {
+            const xsrf = await this.fetchXsrf({ baseUrl, cookieHeader });
+            if (!xsrf.ok)
+                return this.envMintFailed(xsrf.reason, xsrf.detail);
+            csrfToken = xsrf.csrfToken;
+        }
+        let result;
+        try {
+            result = await this.mint({ baseUrl, cookieHeader, csrfToken });
+        }
+        catch (error) {
+            return this.envMintFailed("transport", error instanceof Error ? error.message : String(error));
+        }
+        if (!result.ok) {
+            // A stale XSRF token is one cause of a refused mint; read a fresh one next time.
+            this.envCsrfToken = undefined;
+            return this.envMintFailed(result.reason, result.detail);
+        }
+        const now = Date.now();
+        this.envCsrfToken = csrfToken;
+        this.envMinted = {
+            accessToken: result.accessToken,
+            tenantOrigin: this.baseUrl,
+            capturedAt: now,
+            expiresAt: now + this.tokenTtl * 1000,
+            source: "env",
+            cookieHeader,
+        };
+        log("INFO", "Minted a Bearer token from D2L_SESSION_COOKIE without a browser");
+        return this.envMinted;
+    }
+    /**
+     * A dead cookie or a page with no XSRF token will not mint later either, so
+     * stop trying; a transport failure is retried after ENV_MINT_RETRY_MS.
+     */
+    envMintFailed(reason, detail) {
+        if (reason === "transport") {
+            this.envMintRetryAt = Date.now() + ENV_MINT_RETRY_MS;
+        }
+        else {
+            this.envMintDisabled = true;
+        }
+        log("DEBUG", `Could not mint from D2L_SESSION_COOKIE (${reason}${detail ? `: ${detail}` : ""}); using the cookie as-is`);
+        return null;
+    }
     /**
      * Only use persisted session material, including updates from other processes.
      */

package/build/auth/xsrf-fetch.js

@@ -0,0 +1,76 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT: see LICENSE file for details.
+ */
+import { log } from "../utils/logger.js";
+/** Same marker token-mint.ts keys on: a dead session gets a 200 redirect stub. */
+const EXPIRED_MARKER = "/d2l/login?sessionExpired=1";
+/** Same identity the API client sends, see buildAuthHeaders in api/client.ts. */
+const USER_AGENT = "BrightspaceMCP/1.0 (Rohan Muppa; github.com/rohanmuppa/brightspace-mcp-server)";
+const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * Where a Brightspace page carries its XSRF token, most specific first.
+ *
+ * The browser path reads D2L.LP.Web.Authentication.Xsrf.GetXsrfToken(), whose
+ * value is the one the page also writes to localStorage as "XSRF.Token"
+ * (the same 32 characters). Measured against purdue.brightspace.com: the
+ * cookie-only HTML carries it in an inline
+ * `localStorage.setItem('XSRF.Token','...')`, so that is the first place to
+ * look; the meta tag is the browser path's own fallback.
+ */
+const XSRF_PATTERNS = [
+    /XSRF\.Token\\?["']\s*,\s*\\?["']([A-Za-z0-9_-]{16,})\\?["']/,
+    /<meta[^>]*name=["']d2l-xsrf-token["'][^>]*content=["']([A-Za-z0-9_-]{16,})["']/i,
+    /<meta[^>]*content=["']([A-Za-z0-9_-]{16,})["'][^>]*name=["']d2l-xsrf-token["']/i,
+];
+/** Pull the XSRF token out of a Brightspace page's HTML, or null when absent. */
+export function parseXsrfToken(html) {
+    for (const pattern of XSRF_PATTERNS) {
+        const match = pattern.exec(html);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Read the XSRF token the token mint needs from /d2l/home over plain HTTP,
+ * using only the session cookies. This is what lets a pasted
+ * D2L_SESSION_COOKIE be traded for a Bearer JWT without a browser.
+ */
+export async function fetchXsrfToken({ baseUrl, cookieHeader, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, }) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/d2l/home`;
+    let status;
+    let body;
+    let location;
+    try {
+        const response = await fetchImpl(url, {
+            method: "GET",
+            headers: { cookie: cookieHeader, "User-Agent": USER_AGENT, accept: "text/html" },
+            signal: AbortSignal.timeout(timeoutMs),
+            redirect: "manual",
+        });
+        status = response.status;
+        body = await response.text();
+        location = response.headers?.get("location") ?? null;
+    }
+    catch (error) {
+        return { ok: false, reason: "transport", detail: error instanceof Error ? error.message : String(error) };
+    }
+    if (status >= 500 || status === 429)
+        return { ok: false, reason: "transport", detail: `HTTP ${status}` };
+    // A dead session either redirects to the login page or answers 200 with the
+    // redirect stub. Either way the cookie is no good for minting.
+    if (status === 401 || body.includes(EXPIRED_MARKER) || (status >= 300 && status < 400 && location?.includes("/d2l/login"))) {
+        log("DEBUG", "The home page answered as a signed-out session");
+        return { ok: false, reason: "sessionExpired" };
+    }
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "transport", detail: `HTTP ${status}` };
+    const csrfToken = parseXsrfToken(body);
+    if (!csrfToken) {
+        log("DEBUG", "No XSRF token found in the home page HTML");
+        return { ok: false, reason: "notFound" };
+    }
+    return { ok: true, csrfToken };
+}

package/build/server.js

@@ -30,6 +30,7 @@ export function createRuntime(config, version) {
         tokenTtl: config.tokenTtl,
         envAccessToken: config.envAccessToken,
         envSessionCookie: config.envSessionCookie,
+        mintEnvCookie: true,
     });
     // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE are opt-in browser-free sign-in
     // escape hatches (Docker, headless Linux, WSL, hardware-key MFA

package/build/tools/get-announcements.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems } from "../api/paginate.js";
 import { GetAnnouncementsSchema, } from "./schemas.js";
-import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
@@ -150,6 +150,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
                     // answered, so the result says so instead of reporting zero
                     // announcements as if that were a real measurement.
                     if (isAuthUnavailable(error)) {
+                        throwIfCredentialRejected(error);
                         log("DEBUG", `get_announcements: sign-in pending for course ${courseId}`, error);
                         const notice = "Sign-in to Brightspace is still in progress, so announcements for this course " +
                             `could not be fetched yet. ${authPendingNotice(error)} Call get_announcements again ` +
@@ -250,6 +251,8 @@ export function registerGetAnnouncements(server, apiClient, config) {
             // always a bare array — a shape change would break every existing
             // caller — so a pending course adds a second content block carrying
             // the notice instead of changing content[0].
+            if (pending.length > 0)
+                throwIfCredentialRejected(pending[0].authError);
             if (!modifiedSince) {
                 if (pending.length === 0)
                     return arrayPage(announcements, pagination);

package/build/tools/get-assignments.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems, fetchAllObjects } from "../api/paginate.js";
 import { GetAssignmentsSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
@@ -892,6 +892,7 @@ export function registerGetAssignments(server, apiClient, config) {
                     // keep working — with authPending/notice added for callers that
                     // want to tell "no assignments" apart from "couldn't check".
                     if (isAuthUnavailable(error)) {
+                        throwIfCredentialRejected(error);
                         log("DEBUG", `get_assignments: sign-in pending for course ${courseId}`, error);
                         return toolResponse({
                             courseId,
@@ -983,6 +984,7 @@ export function registerGetAssignments(server, apiClient, config) {
                 ],
             };
             if (pending.length > 0) {
+                throwIfCredentialRejected(pending[0].authError);
                 response.authPending = true;
                 response.unavailableCourseIds = pending.map((c) => c.courseId);
                 response.notice =

package/build/tools/get-calendar-events.js

@@ -4,7 +4,7 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import { GetCalendarEventsSchema } from "./schemas.js";
-import { toolResponse, toolResponseWithNotice, errorResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, errorResponse, sanitizeError, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { resolveCourses } from "./resolve-courses.js";
 import { fetchCourseCalendarEvents } from "./calendar-events.js";
@@ -67,6 +67,7 @@ export function registerGetCalendarEvents(server, apiClient, config) {
             // which names which course ids are unavailable.
             const notices = [];
             if (pendingCourseIds.length > 0) {
+                throwIfCredentialRejected(firstAuthError);
                 notices.push("Sign-in to Brightspace is still in progress, so calendar events for " +
                     `${pendingCourseIds.length} course(s) (${pendingCourseIds.join(", ")}) could not be fetched ` +
                     `yet. ${authPendingNotice(firstAuthError)} Call get_calendar_events again once sign-in finishes.`);

package/build/tools/get-my-grades.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems, fetchAllObjects } from "../api/paginate.js";
 import { GetMyGradesSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable, authPendingNotice, } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected, } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { gradebookUrl, quizUrl } from "../utils/deep-links.js";
@@ -115,6 +115,7 @@ export function registerGetMyGrades(server, apiClient, config) {
                     // working — with authPending/notice added for callers that want
                     // to tell "no grades" apart from "couldn't check".
                     if (isAuthUnavailable(error)) {
+                        throwIfCredentialRejected(error);
                         log("DEBUG", `get_my_grades: sign-in pending for course ${courseId}`, error);
                         return toolResponse({
                             courseId,
@@ -260,6 +261,7 @@ export function registerGetMyGrades(server, apiClient, config) {
             };
             const notices = [];
             if (pending.length > 0) {
+                throwIfCredentialRejected(pending[0].authError);
                 response.authPending = true;
                 response.unavailableCourseIds = pending.map((c) => c.courseId);
                 notices.push("Sign-in to Brightspace is still in progress, so grades for " +

package/build/tools/get-roster.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllObjects } from "../api/paginate.js";
 import { GetRosterSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 // Purdue-specific role IDs. These are institution-specific values.
 // If using at another institution, you may need to adjust these.
@@ -80,6 +80,8 @@ export function registerGetRoster(server, apiClient) {
                     // roster that lost its TAs to a pending sign-in should still show
                     // the instructor it already has.
                     authFailure = [instructorResult, taResult].find((r) => r.status === "rejected" && isAuthUnavailable(r.reason));
+                    if (authFailure)
+                        throwIfCredentialRejected(authFailure.reason);
                     // Merge results
                     if (instructorResult.status === "fulfilled") {
                         allUsers.push(...instructorResult.value);
@@ -169,6 +171,7 @@ export function registerGetRoster(server, apiClient) {
                 // authPending/notice added for callers that want to tell "empty
                 // roster" apart from "couldn't check".
                 if (isAuthUnavailable(error)) {
+                    throwIfCredentialRejected(error);
                     log("DEBUG", `get_roster: sign-in pending for course ${courseId}`, error);
                     return toolResponse({
                         courseId,

package/build/tools/get-upcoming-due-dates.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllObjects } from "../api/paginate.js";
 import { GetUpcomingDueDatesSchema, } from "./schemas.js";
-import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice, throwIfCredentialRejected } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { quizUrl, discussionUrl } from "../utils/deep-links.js";
 import { assignmentLinkResolver } from "./assignment-links.js";
@@ -242,6 +242,7 @@ export function registerGetUpcomingDueDates(server, apiClient, config) {
             if (pendingCourseIds.length === 0) {
                 return toolResponse(upcoming);
             }
+            throwIfCredentialRejected(firstAuthError);
             return toolResponseWithNotice(upcoming, "Sign-in to Brightspace is still in progress, so upcoming due dates for " +
                 `${pendingCourseIds.length} course(s) (${pendingCourseIds.join(", ")}) could not be fetched ` +
                 `yet. ${authPendingNotice(firstAuthError)} Call get_upcoming_due_dates again once sign-in finishes.`);

package/build/tools/tool-helpers.js

@@ -5,7 +5,7 @@
  */
 import { ZodError } from "zod";
 import { ApiError, RateLimitError, NetworkError } from "../api/index.js";
-import { TokenRefreshError } from "../api/errors.js";
+import { CredentialRejectedError, TokenRefreshError } from "../api/errors.js";
 import { AuthProcessError } from "../auth/auth-runner.js";
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
@@ -226,6 +226,16 @@ export function authPendingNotice(error) {
     return "Authentication expired. Auto-reauthentication was attempted but failed. " +
         `Please run \`${AUTH_COMMAND}\` in your terminal, then try again.`;
 }
+/**
+ * A rejected pasted credential (D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE) never
+ * recovers by waiting, unlike a pending sign-in. Tools call this before
+ * reporting "sign-in is still in progress", so the whole call fails instead
+ * and sanitizeError tells the user how to replace the credential.
+ */
+export function throwIfCredentialRejected(error) {
+    if (error instanceof CredentialRejectedError)
+        throw error;
+}
 /**
  * Sanitize errors for user-friendly messages
  *
@@ -263,6 +273,9 @@ function describeError(error) {
         if (error.status === 404) {
             return errorResponse("Resource not found. The course or item may not exist, or you may not have access.");
         }
+        if (error instanceof CredentialRejectedError) {
+            return errorResponse(error.guidance);
+        }
         if (error.status === 401) {
             // A stale install is a common cause of sign-in failing, so this is the
             // one error worth attaching the update notice to.

package/package.json

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