canvas-parent-mcp 2.1.2 → 2.1.4

package/dist/client.js

@@ -1,7 +1,9 @@
-import { writeFile, stat } from 'fs/promises';
+import { constants as fsConstants } from 'fs';
+import { lstat, open, stat } from 'fs/promises';
 import { createSessionCache, reportCacheWriteFailure } from './session-cache.js';
-import { dirname } from 'path';
-import { createOAuth2Refresher, parseLinkHeader } from '@chrischall/mcp-utils';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { homedir } from 'os';
+import { assertPathWithinRoots, createOAuth2Refresher, expandPath, parseLinkHeader, readEnvVar, } from '@chrischall/mcp-utils';
 import { CookieSessionManager } from '@chrischall/mcp-utils/session';
 import { sessionLogin as defaultSessionLogin } from './session-login.js';
 // Re-export the fleet-shared RFC 5988 Link parser so existing importers
@@ -19,6 +21,8 @@ export class CanvasClient {
      * what keeps the path alive once the browser cookie lapses.
      */
     refreshSession;
+    /** Explicit download root; when unset, resolved per call (see {@link downloadRoot}). */
+    outputDir;
     auth;
     /** Lazily-built shared refresh_token exchanger (oauth mode only). */
     oauthRefresh = null;
@@ -34,6 +38,7 @@ export class CanvasClient {
      */
     constructor(account, opts = {}) {
         this.account = account;
+        this.outputDir = opts.outputDir;
         this.sessionLoginFn = opts.sessionLogin ?? defaultSessionLogin;
         this.refreshSession = opts.refreshSession ?? null;
         this.auth = new CookieSessionManager({
@@ -78,24 +83,44 @@ export class CanvasClient {
         }
         return out;
     }
+    /**
+     * Download a Canvas file to disk.
+     *
+     * Both inputs arrive from tool arguments, which a prompt injection in
+     * classmate/teacher-authored Canvas content can steer, so both are pinned
+     * BEFORE any credential is attached:
+     *  - `path` must resolve to the configured Canvas origin (https, same host —
+     *    the `https://canvas@evil/` userinfo trick parses to a foreign host and is
+     *    refused) and name a `/files/<id>` resource. Only the initial request is
+     *    pinned: Canvas legitimately redirects to its file store, and fetch
+     *    strips Authorization/Cookie on a cross-origin redirect.
+     *  - `destinationPath` must lie inside the download root (see
+     *    {@link downloadRoot}), checked through symlinks; a relative path is
+     *    resolved against that root.
+     */
     async download(path, destinationPath, opts = {}) {
+        const url = this.pinDownloadUrl(path);
+        const dest = this.confineDestination(destinationPath);
+        // lstat, not stat: a symlink at the final component is refused outright
+        // rather than judged by whatever it points at.
         let destStat = null;
         try {
-            destStat = await stat(destinationPath);
+            destStat = await lstat(dest);
         }
         catch { /* not present, ok */ }
+        if (destStat?.isSymbolicLink())
+            throw new InvalidPathError(destinationPath, 'is a symlink');
         if (destStat?.isDirectory())
             throw new InvalidPathError(destinationPath);
         if (destStat && !opts.overwrite)
             throw new FileExistsError(destinationPath);
-        const parent = dirname(destinationPath);
+        const parent = dirname(dest);
         try {
             await stat(parent);
         }
         catch {
             throw new ParentDirectoryMissingError(parent);
         }
-        const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
         const res = await this.authedFetch(url, {});
         if (res.status === 401)
             throw new TokenExpiredError(this.account.mode);
@@ -104,13 +129,54 @@ export class CanvasClient {
         if (!res.ok)
             throw new Error(`Canvas download ${res.status} for ${path}`);
         const buf = new Uint8Array(await res.arrayBuffer());
-        await writeFile(destinationPath, buf);
+        await writeConfined(dest, destinationPath, buf, opts.overwrite === true);
         return {
-            path: destinationPath,
+            path: dest,
             bytes: buf.byteLength,
             contentType: res.headers.get('content-type') ?? 'application/octet-stream',
         };
     }
+    /**
+     * The directory downloads are confined to: the constructor's `outputDir`,
+     * else `CANVAS_OUTPUT_DIR`, else `~/Downloads`. Read per call so an env
+     * change needs no client rebuild.
+     */
+    downloadRoot() {
+        return expandPath(this.outputDir ?? readEnvVar('CANVAS_OUTPUT_DIR') ?? join(homedir(), 'Downloads'));
+    }
+    confineDestination(destinationPath) {
+        const root = this.downloadRoot();
+        // `~` expands to home; any other relative path is anchored at the root
+        // (not the process cwd, which for a desktop-launched server is often `/`).
+        const candidate = destinationPath.startsWith('~') || isAbsolute(destinationPath)
+            ? expandPath(destinationPath)
+            : resolve(root, destinationPath);
+        try {
+            assertPathWithinRoots(candidate, [root]);
+        }
+        catch {
+            throw new DownloadDestinationRejectedError(destinationPath, root);
+        }
+        return candidate;
+    }
+    pinDownloadUrl(path) {
+        const raw = /^[a-z][a-z0-9+.-]*:/i.test(path) ? path : `${this.account.baseUrl}${path}`;
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            throw new DownloadUrlRejectedError(path, 'not a valid URL');
+        }
+        const origin = new URL(this.account.baseUrl).origin;
+        if (parsed.protocol !== 'https:' || parsed.origin !== origin || parsed.username || parsed.password) {
+            throw new DownloadUrlRejectedError(path, `must be an https URL on ${origin}`);
+        }
+        if (!/\/files\/[^/]+/.test(parsed.pathname)) {
+            throw new DownloadUrlRejectedError(path, 'must name a Canvas file (a /files/<id> path)');
+        }
+        return parsed.href;
+    }
     async doRawRequest(path, opts) {
         const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
         const accept = opts.responseType === 'text'
@@ -269,10 +335,63 @@ export class CanvasUnreachableError extends Error {
         this.name = 'CanvasUnreachableError';
     }
 }
+export class DownloadUrlRejectedError extends Error {
+    url;
+    constructor(url, reason) {
+        super(`DownloadUrlRejected: ${reason}; use the \`url\` from canvas_list_course_files. Got: ${url}`);
+        this.url = url;
+        this.name = 'DownloadUrlRejectedError';
+    }
+}
+export class DownloadDestinationRejectedError extends Error {
+    path;
+    root;
+    constructor(path, root) {
+        super(`DownloadDestinationRejected: destinationPath must be inside ${root} ` +
+            `(set CANVAS_OUTPUT_DIR to change it). Got: ${path}`);
+        this.path = path;
+        this.root = root;
+        this.name = 'DownloadDestinationRejectedError';
+    }
+}
+/**
+ * Write a download to its (already confined) destination without ever
+ * following a symlink at the final path component (fleet-audit#925). The
+ * pre-flight lstat in download() is separated from this write by a network
+ * fetch, so a link can be planted in between; O_NOFOLLOW makes the open itself
+ * refuse it (ELOOP), and O_EXCL (without overwrite) refuses anything that
+ * appeared at all. New files are created owner-only (0600): they are a
+ * student's school records.
+ */
+async function writeConfined(dest, requested, buf, overwrite) {
+    // O_NOFOLLOW is POSIX-only: on Windows it is undefined, which `|` coerces to 0.
+    const { O_WRONLY, O_CREAT, O_TRUNC, O_EXCL, O_NOFOLLOW } = fsConstants;
+    const flags = O_WRONLY | O_CREAT | O_NOFOLLOW | (overwrite ? O_TRUNC : O_EXCL);
+    let handle;
+    try {
+        handle = await open(dest, flags, 0o600);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ELOOP')
+            throw new InvalidPathError(requested, 'is a symlink');
+        if (code === 'EEXIST')
+            throw new FileExistsError(requested);
+        if (code === 'EISDIR')
+            throw new InvalidPathError(requested);
+        throw e;
+    }
+    try {
+        await handle.writeFile(buf);
+    }
+    finally {
+        await handle.close();
+    }
+}
 export class InvalidPathError extends Error {
     path;
-    constructor(path) {
-        super(`InvalidPath: destinationPath must be a filename, not a directory: ${path}`);
+    constructor(path, reason = 'must be a filename, not a directory') {
+        super(`InvalidPath: destinationPath ${reason}: ${path}`);
         this.path = path;
         this.name = 'InvalidPathError';
     }

package/dist/index.js

@@ -47,7 +47,7 @@ catch (e) {
 // host's install-time `tools/list` succeeds.
 await runMcp({
     name: 'canvas',
-    version: '2.1.2', // x-release-please-version
+    version: '2.1.4', // x-release-please-version
     tools: [
         // Outside the `if (resolved)` on purpose: an unconfigured server must
         // still expose something that can say WHY (see the tool's docblock).

package/dist/tools/conversations.js

@@ -26,12 +26,16 @@ export function registerConversationTools(server, client) {
         return viewResponse(args.view, data);
     });
     server.registerTool('canvas_get_conversation', {
-        description: 'Get a full Canvas conversation thread with all messages.',
+        description: 'Get a full Canvas conversation thread with all messages. Read-only: does not mark the conversation as read.',
         annotations: { readOnlyHint: true },
         inputSchema: getArgs,
     }, async (rawArgs) => {
         const args = getArgs.parse(rawArgs);
+        // Canvas marks a conversation read on GET unless told otherwise; pin it
+        // off so this tool honours its readOnlyHint and never sends the parent's
+        // read receipt to the teacher on a model's behalf (fleet-audit#926).
         const path = buildPath(`/api/v1/conversations/${encodeURIComponent(args.id)}`, {
+            auto_mark_as_read: false,
             'include[]': ['participant_avatars'],
         });
         const data = await client.request(path);

package/dist/tools/files.js

@@ -6,8 +6,8 @@ const listArgs = z.object({
     contentTypes: z.array(z.string()).optional(),
 });
 const downloadArgs = z.object({
-    url: z.string().describe('The url field returned by canvas_list_course_files (absolute https URL).'),
-    destinationPath: z.string().describe('Absolute path where the file should be written.'),
+    url: z.string().describe('The url field returned by canvas_list_course_files (an https /files/ URL on the configured Canvas host; anything else is refused).'),
+    destinationPath: z.string().describe('Where to write the file. Must be inside the download directory (CANVAS_OUTPUT_DIR, default ~/Downloads); a relative path is resolved against it.'),
     overwrite: z.boolean().optional(),
 });
 export function registerFileTools(server, client) {
@@ -25,8 +25,8 @@ export function registerFileTools(server, client) {
         return textContent(data);
     });
     server.registerTool('canvas_download_file', {
-        description: "Download a Canvas file to disk. `url` is the absolute URL from canvas_list_course_files; `destinationPath` is required.",
-        annotations: { destructiveHint: true },
+        description: "Download a Canvas file to disk. `url` is the absolute URL from canvas_list_course_files (only file URLs on the configured Canvas host are accepted); `destinationPath` is required and must be inside the download directory (CANVAS_OUTPUT_DIR, default ~/Downloads).",
+        annotations: { destructiveHint: true, openWorldHint: true },
         inputSchema: downloadArgs,
     }, async (rawArgs) => {
         const args = downloadArgs.parse(rawArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "mcpName": "io.github.chrischall/canvas-parent-mcp",
   "description": "Canvas LMS (Instructure) MCP server — student/observer read access with optional file download",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "2.1.2",
+  "version": "2.1.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "2.1.2",
+      "version": "2.1.4",
       "transport": {
         "type": "stdio"
       },

package/skills/canvas-parent/SKILL.md

@@ -85,7 +85,7 @@ Precedence when multiple are set: `CANVAS_TOKEN` > username/password > OAuth > f
 
 ### Files
 - `canvas_list_course_files(courseId)` — file metadata
-- `canvas_download_file(url, destinationPath)` — download a file to disk
+- `canvas_download_file(url, destinationPath)` — download a file to disk. `url` must be a `/files/` URL on the configured Canvas host; `destinationPath` must be inside `CANVAS_OUTPUT_DIR` (default `~/Downloads`), and a relative path is resolved against it
 
 ## Response shape (`view`)
 

package/skills/canvas-parent-api/references/canvas-endpoints.md

@@ -217,7 +217,9 @@ curl -sL -H "Authorization: Bearer $CANVAS_TOKEN" "$FILE_URL" -o /path/to/destin
 ```
 
 `-L` follows Canvas's redirect to the actual file storage backend. The MCP's
-`canvas_download_file` tool additionally refuses to overwrite an existing
+`canvas_download_file` tool additionally only fetches `/files/` URLs on the
+`CANVAS_BASE_URL` host, only writes inside `CANVAS_OUTPUT_DIR` (default
+`~/Downloads`), refuses to overwrite an existing
 destination unless told to and validates the parent directory exists —
 replicate that yourself in a script if it matters (`[ -f dest ] && exit 1`,
 `[ -d "$(dirname dest)" ] || exit 1`).