brightspace-mcp-server 5.1.43 → 5.2.0

package/build/tools/download-course-files.js

@@ -0,0 +1,86 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { DownloadCourseFilesSchema } from "./schemas.js";
+import { errorResponse, sanitizeError, withUpdateNotice } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+import { validateContentId } from "../utils/file-validator.js";
+import { SyncInputError, syncCourse } from "../sync/course-sync.js";
+import { summarizeSync } from "../sync/summary.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+/**
+ * Register download_course_files tool
+ */
+export function registerDownloadCourseFiles(server, apiClient) {
+    server.registerTool("download_course_files", {
+        title: "Download Course Files",
+        description: "Download every file in a course's Content area to a folder on the host computer, in sub-folders named after the course's modules. Use this when the user wants a whole course (or one module) saved, instead of calling download_file once per file. Ask the user where to save it before calling; never guess a directory. It is safe to run again: files already on disk are skipped by default, so a rerun fetches only what is new and never overwrites the user's annotated copies. Use dryRun first to preview a large course. The answer counts what was downloaded, skipped, failed and not attempted, and what was not a file (web links, embedded videos, broken items, locked items), so do not report those as missing. If the Brightspace session expires mid-run it stops with sign-in instructions and the files already saved are kept; sign in and call it again.",
+        inputSchema: DownloadCourseFilesSchema,
+    }, async (args, extra) => {
+        try {
+            log("DEBUG", "download_course_files tool called", { args });
+            const { courseId, downloadPath, existing, moduleId, dryRun, maxFiles, maxMinutes, maxTotalMB } = DownloadCourseFilesSchema.parse(args);
+            validateContentId(courseId);
+            // Same rules as download_file's disk mode: an absolute path to a directory that exists.
+            if (!path.isAbsolute(downloadPath)) {
+                return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)", "invalidInput");
+            }
+            try {
+                if (!(await fs.stat(downloadPath)).isDirectory()) {
+                    return errorResponse(`Download path is not a directory: ${downloadPath}`, "destination");
+                }
+            }
+            catch (error) {
+                if (error?.code === "ENOENT") {
+                    return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
+                }
+                throw error;
+            }
+            let result;
+            try {
+                // A client that sent a progress token sees each file as it is handled, and a
+                // client that cancels the call (or a deadline) ends the run cleanly.
+                const progressToken = extra?._meta?.progressToken;
+                result = await syncCourse(apiClient, {
+                    courseId,
+                    destination: downloadPath,
+                    existing,
+                    moduleId,
+                    dryRun,
+                    maxFiles,
+                    maxTotalBytes: maxTotalMB * 1024 * 1024,
+                    deadlineMs: maxMinutes * 60_000,
+                    signal: extra?.signal,
+                    onProgress: progressToken === undefined || typeof extra?.sendNotification !== "function"
+                        ? undefined
+                        : (event) => {
+                            void extra.sendNotification({
+                                method: "notifications/progress",
+                                params: {
+                                    progressToken,
+                                    progress: event.done,
+                                    total: event.total,
+                                    message: `${event.type} ${JSON.stringify(event.path)}`,
+                                },
+                            }).catch(() => { });
+                        },
+                });
+            }
+            catch (error) {
+                if (error instanceof SyncInputError)
+                    return errorResponse(error.message, "invalidInput");
+                throw error;
+            }
+            const response = withUpdateNotice([{ type: "text", text: summarizeSync(result) }]);
+            if (result.authError)
+                response.isError = true;
+            return response;
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/download-dropbox-submission-file.js

@@ -6,9 +6,10 @@
 import { ApiError } from "../api/index.js";
 import { DownloadDropboxSubmissionFileSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { log } from "../utils/logger.js";
 import { validateContentId, DISK_MAX_FILE_SIZE } from "../utils/file-validator.js";
-import { secureStreamDownload } from "../utils/download-helpers.js";
+import { secureStreamDownload, expectedLength } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -53,6 +54,10 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
                 }
                 throw error;
             }
+            const protectedReason = await sensitiveDestination(downloadPath);
+            if (protectedReason) {
+                return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+            }
             // Fetch submission metadata to get the file list and validate fileId.
             const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/`);
             let targetFile = null;
@@ -119,6 +124,7 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
                 originalFilename,
                 body: response.body,
                 maxBytes: DISK_MAX_FILE_SIZE,
+                expectedBytes: expectedLength(response),
             });
             log("INFO", `download_dropbox_submission_file: saved ${result.path} (${result.size} bytes, ${result.mime})`);
             return toolResponse({

package/build/tools/download-file.js

@@ -13,8 +13,9 @@ import { checkTopicAvailability } from "./topic-availability.js";
 // validated anything itself. Inline mode never writes to disk, so it calls
 // validateFileType directly to enforce the same magic-byte allowlist.
 import { validateContentId, validateFileType, nameForType, MAX_FILE_SIZE, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
-import { secureStreamDownload, readBodyCapped } from "../utils/download-helpers.js";
+import { secureStreamDownload, readBodyCapped, expectedLength } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { parseCoursePath, QUICKLINK_PATH } from "../utils/course-files.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
@@ -232,6 +233,7 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
         originalFilename,
         body: response.body,
         maxBytes: DISK_MAX_FILE_SIZE,
+        expectedBytes: expectedLength(response),
     });
     log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
     return toolResponse({
@@ -314,6 +316,10 @@ cookieRejectedMessage) {
                     }
                     throw error;
                 }
+                const protectedReason = await sensitiveDestination(downloadPath);
+                if (protectedReason) {
+                    return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+                }
             }
             // Determine download source
             if (coursePath !== undefined) {
@@ -416,26 +422,35 @@ export function parseContentDispositionFilename(disposition) {
     return null;
 }
 /**
- * Download a content file using topicId
+ * Request a content topic's file. Returns the response, or why the topic is
+ * not available: unreleased files can answer 403 or 404, and a release
+ * restriction is only explained when the metadata supports it, so every other
+ * failure is thrown intact. Shared with the course sync.
  */
-async function downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename) {
-    log("INFO", `Downloading content file: courseId=${courseId}, topicId=${topicId}`);
+export async function openContentTopic(apiClient, courseId, topicId, signal) {
     // Build download URL using D2L API path helper
     const apiPath = apiClient.le(courseId, `/content/topics/${topicId}/file`);
-    // Unreleased files can return 404 as well as 403. Only explain a release
-    // restriction when the metadata supports it; keep other failures intact.
-    let response;
     try {
-        response = await apiClient.getRaw(apiPath);
+        return { response: await apiClient.getRaw(apiPath, signal ? { signal } : undefined) };
     }
     catch (error) {
         if (error instanceof ApiError && (error.status === 403 || error.status === 404)) {
             const unavailable = await checkTopicAvailability(apiClient, courseId, topicId, error.status);
             if (unavailable)
-                return toolResponse(unavailable);
+                return { unavailable };
         }
         throw error;
     }
+}
+/**
+ * Download a content file using topicId
+ */
+async function downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename) {
+    log("INFO", `Downloading content file: courseId=${courseId}, topicId=${topicId}`);
+    const opened = await openContentTopic(apiClient, courseId, topicId);
+    if ("unavailable" in opened)
+        return toolResponse(opened.unavailable);
+    const { response } = opened;
     // Get filename from Content-Disposition header
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? "download";

package/build/tools/get-course-content.js

@@ -194,6 +194,12 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                 // Link topic — include URL
                 topic.url = item.Url ?? null;
             }
+            // An embedded video (D2L's ContentService type) has no file behind it.
+            // Said outright so it is not taken for a file that is missing.
+            if (typeof item.TypeIdentifier === 'string' && item.TypeIdentifier.toLowerCase() === 'contentservice') {
+                topic.embeddedMedia = true;
+                topic.note = 'Embedded media: download_file cannot fetch it. Open it in Brightspace, or use get_video_transcript for its transcript.';
+            }
             // HTML content — include body converted to markdown
             if (item.Description?.Html) {
                 topic.content = convertHtmlToMarkdown(item.Description.Html).markdown;

package/build/tools/get-syllabus.js

@@ -13,6 +13,7 @@ import { DownloadError } from "../utils/download-errors.js";
 import { MAX_FILE_SIZE } from "../utils/file-validator.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
 import { parseContentDispositionFilename } from "./download-file.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { log } from "../utils/logger.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -137,6 +138,10 @@ export function registerGetSyllabus(server, apiClient) {
                     }
                     throw error;
                 }
+                const protectedReason = await sensitiveDestination(downloadPath);
+                if (protectedReason) {
+                    return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+                }
             }
             // Fetch overview text
             let overview = null;

package/build/tools/index.js

@@ -15,6 +15,7 @@ export { registerGetAssignmentFiles } from "./get-assignment-files.js";
 export { registerGetAnnouncementFiles } from "./get-announcement-files.js";
 export { registerGetCourseContent } from "./get-course-content.js";
 export { registerDownloadFile, COURSE_FILE_NEEDS_COOKIE } from "./download-file.js";
+export { registerDownloadCourseFiles } from "./download-course-files.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";
 export { registerGetRoster } from "./get-roster.js";
 export { registerGetMyGroups } from "./get-my-groups.js";

package/build/tools/schemas.js

@@ -82,6 +82,24 @@ export const DownloadFileSchema = z.object({
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
 });
+export const DownloadCourseFilesSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to download every file from."),
+    downloadPath: z.string().min(1)
+        .describe("Absolute path to an existing directory on the HOST filesystem where the course is saved. The directory must already exist; it is not created for you, so create it first if needed. Folders named after the course's modules are created inside it. Ask the user where to save the course before calling this; never guess a directory."),
+    existing: z.enum(["skip", "replace", "keep_both"]).default("skip")
+        .describe("What to do with a file that is already on disk. skip (default): leave it alone, so running this again only fetches what is new and never overwrites the user's annotated copies. replace: download it again over the old one. keep_both: save the new copy as 'name (1).ext' beside it, unless a copy of the same size is already there."),
+    moduleId: z.coerce.number().int().positive().optional()
+        .describe("Only download this module and the modules inside it (a module id from get_course_content). Omit to download the whole course."),
+    dryRun: z.boolean().default(false)
+        .describe("List the files that would be downloaded without downloading anything or creating any folder. Use it first on a large course."),
+    maxFiles: z.coerce.number().int().min(1).max(5000).default(300)
+        .describe("Most files to download in one call (default 300). Files already on disk do not count. The rest are reported as not attempted: call again to continue, since existing files are skipped."),
+    maxMinutes: z.coerce.number().int().min(1).max(120).default(8)
+        .describe("Wall-clock limit for this call in minutes (default 8). When it passes, the call stops cleanly and reports the rest as not attempted; call it again to continue, since files already on disk are skipped. Raise it only if the client allows long tool calls."),
+    maxTotalMB: z.coerce.number().int().min(1).max(1048576).default(5120)
+        .describe("Most megabytes to download in one call (default 5120, i.e. 5 GB). The rest is reported as not attempted; call again to continue."),
+});
 export const GetSyllabusSchema = z.object({
     courseId: z.coerce.number().int().positive()
         .describe("Course ID to get syllabus for."),

package/build/tools/tool-helpers.js

@@ -114,7 +114,8 @@ const MFA_SAME_PROMPT = "Calling again doesn't send a new prompt, and neither do
     "keeps waiting, for up to 5 minutes, on the prompt already sent.";
 /** Entra number match only: purdue-sso.ts asks for another request when one expires or is denied. */
 const MFA_NEW_NUMBER = "If Microsoft's number expires or is denied, the sign-in asks Microsoft for a new one by itself " +
-    "and the next answer shows it; always give the user the latest number.";
+    "and the next answer shows it, with its own 5 minutes to approve (at most twice, so a sign-in can run up " +
+    "to 15 minutes in all); always give the user the latest number.";
 /**
  * Why a missed prompt cannot be skipped. Microsoft keeps a prompt open for up
  * to 5 minutes and refuses another for the same account until then
@@ -239,6 +240,11 @@ const DOWNLOAD_FAILURE_GUIDANCE = {
         "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.",
+    incomplete: "Download incomplete: the connection closed before the whole file arrived, so nothing was saved. " +
+        "Try again.",
+    empty: "The file is empty (0 bytes) on Brightspace, so nothing was saved.",
+    forbiddenDestination: "That folder is not an allowed place to save files: it is the home folder itself, a drive root, a hidden folder, a system folder or an application-data folder. " +
+        "Choose a folder such as ~/Documents/Brightspace, or have the person who runs the server add the folder to D2L_DOWNLOAD_ROOTS.",
 };
 /**
  * True when an error means the session itself is unusable, not that one

package/build/utils/download-helpers.js

@@ -12,6 +12,16 @@ import { pipeline } from "node:stream/promises";
 import { validateDownloadPath, validateFileType, validateFileTypeOfFile, nameForType, MAX_FILE_SIZE, } from "./file-validator.js";
 import { DownloadError } from "./download-errors.js";
 import { log } from "./logger.js";
+import { sensitiveDestination } from "./sensitive-paths.js";
+/**
+ * Every write to disk starts here, so the protected-destination rule is
+ * enforced once for all tools (see sensitiveDestination).
+ */
+async function assertAllowedDestination(targetDir) {
+    if (await sensitiveDestination(targetDir)) {
+        throw new DownloadError("forbiddenDestination", "Destination folder is not allowed");
+    }
+}
 /**
  * Resolve filename conflicts by appending (1), (2), etc.
  *
@@ -57,6 +67,7 @@ export async function resolveFilenameConflict(dir, filename) {
 export async function secureDownload(options) {
     const { targetDir, filename, data, allowedTypes } = options;
     log("DEBUG", `secureDownload: starting download of ${filename} to ${targetDir}`);
+    await assertAllowedDestination(targetDir);
     // Validate target directory exists and is a directory
     try {
         const stats = await fs.stat(targetDir);
@@ -102,6 +113,14 @@ export async function secureDownload(options) {
         mime,
     };
 }
+/** A planned name, checked to be exactly one safe path component and nothing else. */
+function verbatimComponent(targetDir, name) {
+    const unsafe = name === "" || name === "." || name === ".." || /[/\\\u0000]/.test(name) || path.basename(name) !== name || Buffer.byteLength(name) > 255;
+    const rel = path.relative(path.resolve(targetDir), path.resolve(targetDir, name));
+    if (unsafe || rel !== name)
+        throw new DownloadError("badFilename", "Invalid filename");
+    return name;
+}
 /**
  * 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
@@ -109,11 +128,18 @@ export async function secureDownload(options) {
  * type-checked there, and only then published under its final name; a refused or
  * failed download leaves nothing behind.
  *
+ * With `expectedBytes` (the response's Content-Length, see expectedLength), a
+ * body that ends short of it fails and leaves nothing behind: a dropped
+ * connection must not publish a truncated file that a later sync would take
+ * for the whole one.
+ *
  * @throws DownloadError("tooLarge") once the body passes maxBytes
+ * @throws DownloadError("incomplete") when fewer than expectedBytes arrive
  */
 export async function secureStreamDownload(options) {
-    const { targetDir, filename, originalFilename, body, maxBytes } = options;
-    const safeFilename = path.basename(validateDownloadPath(targetDir, filename));
+    const { targetDir, filename, originalFilename, body, maxBytes, expectedBytes, replaceExisting, replaceGuard, signal, verbatimName } = options;
+    await assertAllowedDestination(targetDir);
+    const safeFilename = verbatimName ? verbatimComponent(targetDir, filename) : path.basename(validateDownloadPath(targetDir, filename));
     const partialPath = path.join(targetDir, `.download-${randomUUID()}.part`);
     let size = 0;
     const limit = new Transform({
@@ -127,11 +153,34 @@ export async function secureStreamDownload(options) {
             }
         },
     });
+    const incomplete = () => new DownloadError("incomplete", `Download incomplete: ${size} of ${expectedBytes} bytes arrived`);
     try {
-        await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }));
+        try {
+            await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }), ...(signal ? [{ signal }] : []));
+        }
+        catch (error) {
+            // fetch reports a connection cut mid-body as a bare "terminated".
+            if (expectedBytes !== undefined && size < expectedBytes && !(error instanceof DownloadError)) {
+                throw incomplete();
+            }
+            throw error;
+        }
+        if (expectedBytes !== undefined && size < expectedBytes)
+            throw incomplete();
+        if (size === 0)
+            throw new DownloadError("empty", "File is empty (0 bytes)");
         const type = await validateFileTypeOfFile(partialPath, undefined, safeFilename, originalFilename);
         const { mime } = type;
-        const finalPath = await publishExclusively(partialPath, targetDir, nameForType(safeFilename, type));
+        const finalName = nameForType(safeFilename, type);
+        let finalPath;
+        const replaceTarget = path.join(targetDir, finalName);
+        if (replaceExisting && finalName === safeFilename && (!replaceGuard || (await replaceGuard(replaceTarget)))) {
+            finalPath = replaceTarget;
+            await fs.rename(partialPath, finalPath);
+        }
+        else {
+            finalPath = await publishExclusively(partialPath, targetDir, finalName);
+        }
         log("INFO", `Downloaded file to ${finalPath} (${size} bytes, ${mime})`);
         return { path: finalPath, size, mime };
     }
@@ -139,6 +188,20 @@ export async function secureStreamDownload(options) {
         await fs.rm(partialPath, { force: true });
     }
 }
+/**
+ * The byte count a response promises, or undefined when it promises none we
+ * can hold it to: no Content-Length, or a Content-Encoding, where fetch hands
+ * back the decoded body and the header counts the encoded one.
+ */
+export function expectedLength(response) {
+    const encoding = (response.headers.get("Content-Encoding") ?? "").trim().toLowerCase();
+    if (encoding && encoding !== "identity")
+        return undefined;
+    const header = response.headers.get("Content-Length");
+    if (header === null || !/^\d+$/.test(header.trim()))
+        return undefined;
+    return Number(header);
+}
 /**
  * Give a finished temporary file its final name without ever replacing an
  * existing file. resolveFilenameConflict only reports a name that was free a

package/build/utils/sensitive-paths.js

@@ -0,0 +1,237 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * Where a download may be written. The destination is chosen through an AI
+ * client, and the file and folder names inside it come from a course, so a
+ * destination that is the home folder, a hidden folder (where settings and
+ * credentials live), an application-data folder or a system folder would let
+ * a course plant files where they do real harm. Everything else is allowed:
+ * the user's folders, cloud-sync folders, temp folders, /srv, /data,
+ * /workspace, /opt, external drives.
+ *
+ * The rule is judged on the native real path, so a symbolic link into a
+ * refused place is refused. The person who runs the server can allow more
+ * with D2L_DOWNLOAD_ROOTS (see downloadRootsFromEnv); a tool argument cannot.
+ */
+import { lstat, readlink, realpath } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { log } from "./logger.js";
+let configured = {};
+/** Set the policy for this process. Only tests call it: production uses the defaults. */
+export function configureDestinationPolicy(policy) {
+    configured = policy;
+}
+// The native variant expands Windows 8.3 short names; fs/promises has none.
+const realpathNative = promisify(realpath.native);
+const lstatAsync = promisify(lstat);
+const readlinkAsync = promisify(readlink);
+const caseInsensitive = process.platform === "win32" || process.platform === "darwin";
+const fold = (p) => (caseInsensitive ? p.toLowerCase() : p);
+/** \\?\ and \\.\ paths skip Windows' own name handling, so they are not accepted. */
+const DEVICE_PREFIX = /^[\\/]{2}[?.][\\/]/;
+class LinkLoopError extends Error {
+}
+const MAX_LINK_DEPTH = 40;
+/**
+ * The native real path of `target` (8.3 names expanded on Windows). A part
+ * that does not exist yet is kept as written, but a dangling symbolic link is
+ * followed to where it points, so what is judged is where a write would land.
+ */
+async function resolveReal(target, depth = 0) {
+    if (depth > MAX_LINK_DEPTH)
+        throw new LinkLoopError();
+    let current = path.resolve(target);
+    const tail = [];
+    for (;;) {
+        try {
+            return path.join(await realpathNative(current), ...[...tail].reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ELOOP")
+                throw new LinkLoopError();
+            // "Not there yet" and "a folder above it that this user may not look into" (/root for a normal user)
+            // are judged by the nearest part that can be resolved, plus the rest of the path as written.
+            // Anything else is not guessed past: the caller gets the error and refuses.
+            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM" && code !== "ENOTDIR")
+                throw error;
+        }
+        const link = await lstatAsync(current).then((stat) => (stat.isSymbolicLink() ? stat : null), () => null);
+        if (link) {
+            const pointsAt = path.resolve(path.dirname(current), await readlinkAsync(current));
+            return path.join(await resolveReal(pointsAt, depth + 1), ...[...tail].reverse());
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(target);
+        tail.push(path.basename(current));
+        current = parent;
+    }
+}
+/** The components of `child` below `parent`, or null when it is not inside it. */
+function below(child, parent) {
+    const rel = path.relative(fold(parent), fold(child));
+    if (rel === "")
+        return [];
+    if (rel.split(path.sep)[0] === ".." || path.isAbsolute(rel))
+        return null;
+    // Original case, so a later check sees the real names.
+    return path.relative(parent, child).split(path.sep);
+}
+const components = (p) => path.relative(path.parse(p).root, p).split(path.sep).filter(Boolean);
+const lower = (s) => s.toLowerCase();
+const WINDOWS_SYSTEM_FOLDERS = new Set(["windows", "program files", "program files (x86)", "programdata", "system volume information", "$recycle.bin"]);
+const POSIX_SYSTEM_FOLDERS = ["/etc", "/usr", "/bin", "/sbin", "/System", "/Library", "/Applications", "/boot", "/dev", "/proc", "/sys", "/private/etc"];
+/** Temporary folders under /var (macOS keeps its per-user temp there), the only part of it that is allowed. */
+const VAR_TEMP_FOLDERS = ["/var/folders", "/var/tmp", "/private/var/folders", "/private/var/tmp"];
+const REFUSED_DEVICE = "it is a Windows device path (\\\\?\\ or \\\\.\\)";
+const REFUSED_ROOT = "it is the root of a drive";
+const REFUSED_HOME = "it is your home directory itself";
+/**
+ * True when any AppData folder in the path is not just the way to its own
+ * Local\Temp. AppData holds applications' data and the Startup folder; only
+ * Temp is allowed, and an AppData that appears again below a Temp folder (a
+ * fake home kept in Temp) is judged on its own.
+ */
+function appDataOutsideTemp(names) {
+    return names.some((name, i) => name === "appdata" && !(names[i + 1] === "local" && names[i + 2] === "temp"));
+}
+/** Why a real path is refused by the built-in rules, or null. `home` is a real path. */
+async function refusedByRules(real, home) {
+    const parts = components(real);
+    const hiddenPart = parts.find((part) => part.startsWith("."));
+    if (hiddenPart !== undefined)
+        return `its path goes through the hidden folder "${hiddenPart}", where settings and credentials live`;
+    const inHome = below(real, home);
+    if (process.platform === "darwin" && inHome && inHome.length > 0 && lower(inHome[0]) === "library") {
+        const allowed = (inHome.length >= 2 && lower(inHome[1]) === "cloudstorage") || (inHome.length >= 2 && lower(inHome[1]) === "mobile documents");
+        if (!allowed)
+            return "it is inside ~/Library, where applications keep their data (only ~/Library/CloudStorage and ~/Library/Mobile Documents are allowed)";
+    }
+    for (const system of POSIX_SYSTEM_FOLDERS) {
+        if (below(real, system) || below(real, await resolveReal(system)))
+            return `it is inside ${system}, a system folder`;
+    }
+    const first = parts[0] ?? "";
+    if (path.sep === "/" && /^lib(32|64|x32)?$/.test(first))
+        return `it is inside /${first}, a system folder`;
+    if (path.sep === "/" && (below(real, "/var") || below(real, "/private/var"))) {
+        if (!VAR_TEMP_FOLDERS.some((temp) => below(real, temp) || below(real, `/private${temp}`)))
+            return "it is inside /var, a system folder (only its temporary folders are allowed)";
+    }
+    if (path.sep === "/" && below(real, "/root") && !(below(home, "/root")))
+        return "it is inside /root, the administrator's home";
+    if (process.platform === "win32") {
+        const names = parts.map(lower);
+        if (WINDOWS_SYSTEM_FOLDERS.has(names[0] ?? ""))
+            return `it is inside ${parts[0]}, a Windows system folder`;
+        if (appDataOutsideTemp(names))
+            return "it is inside AppData, where applications keep their data and the Startup folder";
+    }
+    else {
+        // Windows drives seen from WSL: /mnt/c/Windows, /mnt/c/Users/<name>/AppData.
+        const wsl = /^\/mnt\/[a-z]\/(.+)$/i.exec(real.split(path.sep).join("/"));
+        if (wsl) {
+            const names = wsl[1].split("/").map(lower);
+            if (WINDOWS_SYSTEM_FOLDERS.has(names[0]))
+                return `it is inside a Windows system folder (${wsl[1].split("/")[0]})`;
+            if (appDataOutsideTemp(names))
+                return "it is inside a Windows AppData folder";
+        }
+    }
+    return null;
+}
+/**
+ * Why `dir` may not be a download destination, or null when it may. Refused:
+ * device paths, a drive root, the home folder itself, any path that goes
+ * through a hidden (dot) folder, ~/Library (except CloudStorage and Mobile
+ * Documents), system folders (/etc, /usr, /bin, /sbin, /System, /Library,
+ * /Applications, /boot, /dev, /proc, /sys, /lib*, /var apart from its temp
+ * folders, /root, and on Windows or under WSL Windows, Program Files,
+ * ProgramData and AppData). A destination inside a root listed in
+ * D2L_DOWNLOAD_ROOTS is allowed even where those rules would refuse it,
+ * but never a device path, a drive root or the home folder itself.
+ */
+export async function sensitiveDestination(dir, options = {}) {
+    if (DEVICE_PREFIX.test(dir))
+        return REFUSED_DEVICE;
+    const policy = { ...configured, ...options };
+    try {
+        const real = await resolveReal(dir);
+        if (DEVICE_PREFIX.test(real))
+            return REFUSED_DEVICE;
+        if (path.parse(real).root === real)
+            return REFUSED_ROOT;
+        const realHome = await resolveReal(policy.home ?? os.homedir());
+        if (fold(real) === fold(realHome))
+            return REFUSED_HOME;
+        const operatorRoots = [...(policy.allowRoots ?? []), ...(await downloadRootsFromEnv(undefined, policy.home))];
+        for (const root of operatorRoots) {
+            if (below(real, await resolveReal(root)))
+                return null;
+        }
+        return await refusedByRules(real, realHome);
+    }
+    catch (error) {
+        if (error instanceof LinkLoopError)
+            return "it involves a symbolic-link loop";
+        throw error;
+    }
+}
+const warnedRoots = new Set();
+/** Let the next check warn again about an ignored entry. For tests. */
+export function resetDownloadRootWarnings() {
+    warnedRoots.clear();
+}
+/**
+ * The extra allowed roots named by D2L_DOWNLOAD_ROOTS, a path.delimiter
+ * separated list, each resolved to its real path. It is read from the
+ * server's own environment, which a tool argument cannot set. A listed root
+ * overrides every rule above, even inside the home folder (a hidden or
+ * ~/Library folder the user really wants), except that an entry which is a
+ * relative path, a device path, a drive root, the home folder itself or a
+ * folder that holds the home folder is ignored with a warning.
+ */
+export async function downloadRootsFromEnv(value = process.env.D2L_DOWNLOAD_ROOTS, home = os.homedir()) {
+    const roots = [];
+    const realHome = await resolveReal(home);
+    for (const entry of (value ?? "").split(path.delimiter).map((e) => e.trim()).filter(Boolean)) {
+        let reason = null;
+        let real = entry;
+        if (!path.isAbsolute(entry))
+            reason = "it is not an absolute path";
+        else if (DEVICE_PREFIX.test(entry))
+            reason = "it is a Windows device path";
+        else {
+            try {
+                real = await resolveReal(entry);
+            }
+            catch {
+                reason = "it could not be resolved";
+            }
+            if (!reason && path.parse(real).root === real)
+                reason = "it is the root of a drive";
+            else if (!reason && fold(real) === fold(realHome))
+                reason = "it is your home folder itself";
+            else if (!reason && below(realHome, real))
+                reason = "it contains your home folder";
+        }
+        if (reason) {
+            if (!warnedRoots.has(entry)) {
+                warnedRoots.add(entry);
+                log("WARN", `[config] Ignoring D2L_DOWNLOAD_ROOTS entry ${JSON.stringify(entry)}: ${reason}.`);
+            }
+            continue;
+        }
+        roots.push(real);
+    }
+    return roots;
+}
+/** The refusal shown for a protected destination: the rule that refused it, and what to do. */
+export function sensitiveDestinationMessage(dir, reason) {
+    return `Cannot save into ${dir}: ${reason}. Choose a folder such as ~/Documents/Brightspace, or have the person who runs the server add the folder to D2L_DOWNLOAD_ROOTS.`;
+}

package/package.json

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