brightspace-mcp-server 3.10.9 → 3.10.10

package/build/api/client.js

@@ -54,6 +54,43 @@ function isExpiredSessionRedirect(body, baseUrl) {
  * Braces are used because D2L paths never contain them, so a substitution can
  * never collide with a real path segment.
  */
+/**
+ * An abort signal that fires after `ms` without progress. Each touch() restarts
+ * the countdown, so a slow transfer that keeps moving is never cut off while a
+ * stalled one still fails.
+ */
+function idleTimeout(ms) {
+    const controller = new AbortController();
+    let timer;
+    const clear = () => clearTimeout(timer);
+    const touch = () => {
+        clear();
+        timer = setTimeout(() => controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError")), ms);
+    };
+    touch();
+    return { signal: controller.signal, touch, clear };
+}
+/** Restart the idle timer on every chunk of the body; stop it at the end. */
+function touchOnProgress(response, idle) {
+    if (!response.body) {
+        idle.clear();
+        return response;
+    }
+    const body = response.body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            idle.touch();
+            controller.enqueue(chunk);
+        },
+        flush() {
+            idle.clear();
+        },
+    }));
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
 const LP_VERSION = "{lp}";
 const LE_VERSION = "{le}";
 /**
@@ -429,12 +466,15 @@ export class D2LApiClient {
     async makeRawRequest(path, token) {
         const url = `${this.baseUrl}${path}`;
         const headers = this.buildAuthHeaders(token);
+        // A file can take far longer than timeoutMs to arrive. Time out on a
+        // stall rather than on total duration, for the headers and the body alike.
+        const idle = idleTimeout(this.timeoutMs);
         try {
             log("DEBUG", `Requesting GET ${path} (raw)`);
             const response = await fetch(url, {
                 method: "GET",
                 headers,
-                signal: AbortSignal.timeout(this.timeoutMs),
+                signal: idle.signal,
             });
             this.recordStatus(response.status);
             // Preserve cookie material for the shared HTTP refresh path.
@@ -473,6 +513,7 @@ export class D2LApiClient {
                 }
                 // A legitimate HTML page: hand back an equivalent response with the
                 // body we already consumed.
+                idle.clear();
                 return new Response(body, {
                     status: response.status,
                     statusText: response.statusText,
@@ -480,9 +521,10 @@ export class D2LApiClient {
                 });
             }
             // Return raw response for caller to process
-            return response;
+            return touchOnProgress(response, idle);
         }
         catch (error) {
+            idle.clear();
             // Re-throw our own errors
             if (error instanceof ApiError ||
                 error instanceof RateLimitError ||

package/build/tools/download-file.js

@@ -8,16 +8,35 @@ import { DownloadFileSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse, withUpdateNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { checkTopicAvailability } from "./topic-availability.js";
-// Path containment checks belong to secureDownload, which disk-mode downloads
+// Path containment checks belong to secureStreamDownload, which disk-mode downloads
 // go through; importing it here only made it look as though this file
 // validated anything itself. Inline mode never writes to disk, so it calls
 // validateFileType directly to enforce the same magic-byte allowlist.
 import { validateContentId, validateFileType, MAX_FILE_SIZE } from "../utils/file-validator.js";
-import { secureDownload } from "../utils/download-helpers.js";
+import { secureStreamDownload } from "../utils/download-helpers.js";
+import { DownloadError } from "../utils/download-errors.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
 import { officeDocumentText } from "../utils/zip-extract.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+/**
+ * Maximum bytes of a file disk mode will save. Disk downloads stream straight
+ * to the file, so memory no longer bounds them the way MAX_FILE_SIZE (50 MB)
+ * bounds inline mode; this only stops a runaway body filling the disk.
+ * Lecture decks and recordings routinely pass 50 MB.
+ */
+const DISK_MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024; // 2 GB
+/** The size cap for a download: inline mode buffers the file, disk mode streams it. */
+function maxFileSize(downloadPath) {
+    return downloadPath === undefined ? MAX_FILE_SIZE : DISK_MAX_FILE_SIZE;
+}
+/** The refusal for a file over its mode's cap, pointing inline callers at disk mode. */
+function tooLargeResponse(bytes, downloadPath) {
+    const hint = downloadPath === undefined
+        ? " Provide an absolute downloadPath to save it to disk instead."
+        : "";
+    return errorResponse(`File too large (${Math.round(bytes / 1024 / 1024)}MB). Maximum allowed: ${maxFileSize(downloadPath) / 1024 / 1024}MB.${hint}`);
+}
 /**
  * Maximum bytes of a file we'll embed inline in a tool response. Base64
  * encoding (for images) adds ~33% overhead, so this stays well under typical
@@ -94,8 +113,8 @@ async function respondInline(buffer, originalFilename, customFilename) {
     if (buffer.length > INLINE_MAX_SIZE) {
         return errorResponse(`File too large for inline delivery (${Math.round(buffer.length / 1024 / 1024)}MB, inline max ${INLINE_MAX_SIZE / 1024 / 1024}MB). Provide an absolute downloadPath to save it to disk instead.`);
     }
-    // Enforces the same magic-byte allowlist as disk mode (secureDownload calls
-    // validateFileType internally); inline mode never writes to disk, so it has
+    // Enforces the same magic-byte allowlist as disk mode (secureStreamDownload calls
+    // validateFileTypeOfFile internally); inline mode never writes to disk, so it has
     // to call this itself. Throws DownloadError on an unsupported or
     // undetectable type, handled by the caller's sanitizeError.
     const { mime } = await validateFileType(buffer, undefined, effectiveFilename);
@@ -179,20 +198,35 @@ async function respondInline(buffer, originalFilename, customFilename) {
     return withUpdateNotice(content);
 }
 /**
- * Finish a download once the bytes are in hand: write to disk when
+ * Finish a download once the response is in hand: stream it to disk when
  * `downloadPath` is given (unchanged response shape, plus a new `mode: "disk"`
- * field), otherwise return the file inline in the tool response.
+ * field), otherwise buffer it and return the file inline in the tool response.
  */
-async function finishDownload(buffer, originalFilename, downloadPath, customFilename, sourceLabel) {
+async function finishDownload(response, originalFilename, downloadPath, customFilename, sourceLabel) {
+    // Check Content-Length BEFORE reading the body (prevent memory exhaustion)
+    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+    if (contentLength > maxFileSize(downloadPath)) {
+        return tooLargeResponse(contentLength, downloadPath);
+    }
     if (downloadPath === undefined) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        // Double-check actual size
+        if (buffer.length > MAX_FILE_SIZE) {
+            return tooLargeResponse(buffer.length, downloadPath);
+        }
         return respondInline(buffer, originalFilename, customFilename);
     }
     const effectiveFilename = customFilename || originalFilename;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
+    if (!response.body) {
+        throw new DownloadError("undetectableType", "File is empty (0 bytes)");
+    }
+    // Streams to disk with path traversal prevention, file type validation,
+    // conflict resolution, and the disk size cap
+    const result = await secureStreamDownload({
         targetDir: downloadPath,
         filename: effectiveFilename,
-        data: buffer,
+        body: response.body,
+        maxBytes: DISK_MAX_FILE_SIZE,
     });
     log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
     return toolResponse({
@@ -314,23 +348,12 @@ async function downloadContentFile(apiClient, courseId, topicId, downloadPath, c
         }
         throw error;
     }
-    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
-    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
-    if (contentLength > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     // Get filename from Content-Disposition header
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? "download";
     log("DEBUG", `Content-Disposition filename: ${filename}`);
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    if (buffer.length > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     const originalFilename = filename;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Content file");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Content file");
 }
 /**
  * Download a submission/feedback file using folderId + fileId
@@ -368,22 +391,16 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
         return errorResponse(`File ID ${fileId} not found in submission. Available files: ${available.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
     }
     // Check file size before downloading
-    if (file.Size > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    if (file.Size > maxFileSize(downloadPath)) {
+        return tooLargeResponse(file.Size, downloadPath);
     }
     // D2L file download URL pattern for submission files
     // GET /d2l/api/le/(version)/(orgUnitId)/dropbox/folders/(folderId)/submissions/(submissionId)/files/(fileId)/download
     const downloadApiPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/${submission.Id}/files/${fileId}/download`);
     // Fetch file
     const response = await apiClient.getRaw(downloadApiPath);
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    if (buffer.length > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     const originalFilename = file.FileName;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Submission file");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Submission file");
 }
 /**
  * Download an announcement attachment using newsId + fileId
@@ -396,24 +413,13 @@ async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downl
     if (!file) {
         return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
     }
-    if (file.Size > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    if (file.Size > maxFileSize(downloadPath)) {
+        return tooLargeResponse(file.Size, downloadPath);
     }
     // GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)
     const response = await apiClient.getRaw(apiClient.le(courseId, `/news/${newsId}/attachments/${fileId}`));
-    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
-    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
-    if (contentLength > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? file.FileName;
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    if (buffer.length > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     const originalFilename = filename;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Announcement attachment");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Announcement attachment");
 }

package/build/tools/tool-helpers.js

@@ -133,6 +133,8 @@ const DOWNLOAD_FAILURE_GUIDANCE = {
         "Pass customFilename to choose one yourself.",
     pathTraversal: "The name Brightspace gave this file pointed outside the download " +
         "directory and was refused. Pass customFilename to choose one yourself.",
+    tooLarge: "The file is larger than the download size limit. " +
+        "Open it from Brightspace in a browser instead.",
 };
 /**
  * True when an error means the session itself is unusable, not that one

package/build/utils/download-helpers.js

@@ -4,8 +4,13 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import fs from "node:fs/promises";
+import { createWriteStream } from "node:fs";
 import path from "node:path";
-import { validateDownloadPath, validateFileType, MAX_FILE_SIZE } from "./file-validator.js";
+import { randomUUID } from "node:crypto";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { validateDownloadPath, validateFileType, validateFileTypeOfFile, MAX_FILE_SIZE, } from "./file-validator.js";
+import { DownloadError } from "./download-errors.js";
 import { log } from "./logger.js";
 /**
  * Resolve filename conflicts by appending (1), (2), etc.
@@ -97,3 +102,42 @@ export async function secureDownload(options) {
         mime,
     };
 }
+/**
+ * secureDownload for a response body that is streamed to disk rather than
+ * held in memory, so a file's size is bounded by `maxBytes` instead of by
+ * MAX_FILE_SIZE. The body is written to a hidden temporary file in targetDir,
+ * type-checked there, and only then renamed to its final name; a refused or
+ * failed download leaves nothing behind.
+ *
+ * @throws DownloadError("tooLarge") once the body passes maxBytes
+ */
+export async function secureStreamDownload(options) {
+    const { targetDir, filename, body, maxBytes } = options;
+    const safeFilename = path.basename(validateDownloadPath(targetDir, filename));
+    const partialPath = path.join(targetDir, `.download-${randomUUID()}.part`);
+    let size = 0;
+    const limit = new Transform({
+        transform(chunk, _encoding, callback) {
+            size += chunk.length;
+            if (size > maxBytes) {
+                callback(new DownloadError("tooLarge", `File exceeds ${maxBytes} bytes`));
+            }
+            else {
+                callback(null, chunk);
+            }
+        },
+    });
+    try {
+        await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }));
+        const { mime } = await validateFileTypeOfFile(partialPath, undefined, safeFilename);
+        const resolvedFilename = await resolveFilenameConflict(targetDir, safeFilename);
+        const finalPath = path.join(targetDir, resolvedFilename);
+        await fs.rename(partialPath, finalPath);
+        log("INFO", `Downloaded file to ${finalPath} (${size} bytes, ${mime})`);
+        return { path: finalPath, size, mime };
+    }
+    catch (error) {
+        await fs.rm(partialPath, { force: true });
+        throw error;
+    }
+}

package/build/utils/file-validator.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import fs from "node:fs/promises";
 import path from "node:path";
 import sanitizeFilename from "sanitize-filename";
 import { DownloadError } from "./download-errors.js";
@@ -21,12 +22,12 @@ import { DownloadError } from "./download-errors.js";
  */
 // file-type v21 is ESM-only and costs ~50ms; defer the import to first use
 // since validateFileType is already async.
-let fileTypeFromBufferPromise;
-function getFileTypeFromBuffer() {
-    if (!fileTypeFromBufferPromise) {
-        fileTypeFromBufferPromise = import("file-type").then((m) => m.fileTypeFromBuffer);
+let fileTypePromise;
+function getFileType() {
+    if (!fileTypePromise) {
+        fileTypePromise = import("file-type");
     }
-    return fileTypeFromBufferPromise;
+    return fileTypePromise;
 }
 const CFB_MIME = "application/x-cfb";
 const CFB_EXTENSION_MIMES = {
@@ -147,33 +148,61 @@ export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES
         throw new DownloadError("undetectableType", "File is empty (0 bytes)");
     }
     // Try magic byte detection first
-    const fileTypeFromBuffer = await getFileTypeFromBuffer();
+    const { fileTypeFromBuffer } = await getFileType();
     const detected = await fileTypeFromBuffer(buffer);
-    if (detected) {
-        if (detected.mime === XML_MIME) {
-            const ext = filename ? path.extname(filename).toLowerCase() : "";
-            const resolved = XML_EXTENSION_MIMES[ext];
-            if (resolved && allowedTypes.includes(resolved)) {
-                return { mime: resolved, ext: ext.slice(1) };
-            }
-            // Anything else falls through to the allowlist check, which refuses
-            // application/xml the way it always has.
-        }
-        if (detected.mime === CFB_MIME) {
-            const ext = filename ? path.extname(filename).toLowerCase() : "";
-            const resolved = CFB_EXTENSION_MIMES[ext];
-            if (resolved && allowedTypes.includes(resolved)) {
-                return { mime: resolved, ext: ext.slice(1) };
-            }
-            throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
+    if (detected)
+        return allowDetectedType(detected, allowedTypes, filename);
+    return allowTextType(buffer, allowedTypes);
+}
+/**
+ * validateFileType for a file already on disk, so a download streamed there
+ * is never read back into memory whole. Magic bytes are read from the file
+ * itself; only a file with none, the text fallback's case, is read in, and
+ * only when it is within MAX_FILE_SIZE.
+ */
+export async function validateFileTypeOfFile(filePath, allowedTypes = ALLOWED_MIME_TYPES, filename) {
+    const { size } = await fs.stat(filePath);
+    if (size === 0) {
+        throw new DownloadError("undetectableType", "File is empty (0 bytes)");
+    }
+    const { fileTypeFromFile } = await getFileType();
+    const detected = await fileTypeFromFile(filePath);
+    if (detected)
+        return allowDetectedType(detected, allowedTypes, filename);
+    if (size > MAX_FILE_SIZE) {
+        throw new DownloadError("undetectableType", "Could not determine file type or type not allowed");
+    }
+    return allowTextType(await fs.readFile(filePath), allowedTypes);
+}
+/** The allowlist decision for a type file-type recognised from magic bytes. */
+function allowDetectedType(detected, allowedTypes, filename) {
+    if (detected.mime === XML_MIME) {
+        const ext = filename ? path.extname(filename).toLowerCase() : "";
+        const resolved = XML_EXTENSION_MIMES[ext];
+        if (resolved && allowedTypes.includes(resolved)) {
+            return { mime: resolved, ext: ext.slice(1) };
         }
-        if (!allowedTypes.includes(detected.mime)) {
-            throw new DownloadError("unsupportedType", `File type '${detected.mime}' not allowed`, detected.mime);
+        // Anything else falls through to the allowlist check, which refuses
+        // application/xml the way it always has.
+    }
+    if (detected.mime === CFB_MIME) {
+        const ext = filename ? path.extname(filename).toLowerCase() : "";
+        const resolved = CFB_EXTENSION_MIMES[ext];
+        if (resolved && allowedTypes.includes(resolved)) {
+            return { mime: resolved, ext: ext.slice(1) };
         }
-        return { mime: detected.mime, ext: detected.ext };
+        throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
+    }
+    if (!allowedTypes.includes(detected.mime)) {
+        throw new DownloadError("unsupportedType", `File type '${detected.mime}' not allowed`, detected.mime);
     }
-    // Fallback for text-based files with no magic-byte signature: accept if the
-    // buffer decodes as UTF-8 (rejecting binaries and NUL bytes), then sniff HTML.
+    return { mime: detected.mime, ext: detected.ext };
+}
+/**
+ * Fallback for text-based files with no magic-byte signature: accept if the
+ * buffer decodes as UTF-8 (rejecting binaries and NUL bytes), then sniff HTML.
+ */
+function allowTextType(buffer, allowedTypes) {
     if (!buffer.includes(0)) {
         let decoded = null;
         try {

package/package.json

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