neuro-canvas-lms 2.11.0 → 2.13.0

package/AGENTS.md

@@ -2,8 +2,8 @@
 
 This repo, **Neuro-CanvasLMS** (`neuro-canvas-lms`), is a read-only Canvas LMS connector (remote MCP
 server on Cloudflare Workers) that each user deploys to their **own** Cloudflare account. It works
-with any Canvas school; nothing school-specific is in the code (the school comes from Worker vars).
-It is a community project provided as is.
+with any Canvas school that lets students create access tokens; nothing school-specific is in the
+code (the school comes from Worker vars). It is a community project provided as is.
 
 - To install, update, reconnect, uninstall or troubleshoot: follow
   `.claude/skills/canvas-connector-setup/SKILL.md` (Claude Code loads it as a skill; other agents
@@ -26,11 +26,16 @@ Code map:
 - Files: `file-content.mjs` (text extraction), `file-types.mjs` (file type detection shared by all
   readers), `zip-content.mjs` (server-side ZIP unpacking), `find-files.mjs` (finds files a course
   links to when its Files list is hidden), `external-links.mjs` (Google/Dropbox/GitHub share links →
-  the file itself), `module-file.mjs` + `file-resource.mjs` (original files as MCP resources).
+  the file itself), `module-file.mjs` + `file-resource.mjs` (original files as MCP resources),
+  `download-link.mjs` (one-time, minutes-long Canvas storage link so coding agents can curl an original
+  file to disk).
 - `owner.mjs`: owner binding, allowed OAuth clients. `i18n.mjs` + `pages.mjs`: web pages.
+  `page-scene.mjs`: their one script (allowed by its hash in the CSP; pages stay off the network):
+  the black-hole scene and the step-by-step authorization. Everything works without it.
 - `update-check.mjs`: once a day reads the newest version number from npm; when it is newer the AI
   tells the user how to update. Also the `canvas_connector_version` tool.
-- `installer/`: the setup wizard. Re-running it asks once (y/n), then updates with the saved
+- `installer/`: the setup wizard. On a new Cloudflare account it registers a random workers.dev
+  subdomain through Cloudflare's API. Re-running it asks once (y/n), then updates with the saved
   settings (without a terminal it does not ask). `installer/verify.mjs`: the post-deploy online
   check, also run alone by `npx -y neuro-canvas-lms check`.
 - `version.mjs`: shown on the home page and /healthz, compared with npm by update-check.mjs.

package/README.md

@@ -2,9 +2,11 @@
 
 **English** · [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [日本語](docs/README.ja.md) · [हिन्दी](docs/README.hi.md)
 
-**Wire your Canvas LMS straight into Claude and ChatGPT.** Your courses, deadlines, grades and lecture files become part of what your AI knows, in any chat and on any device. Works with any school that uses Canvas.
+![Neuro-CanvasLMS answering "What's due this week?" in Claude](https://raw.githubusercontent.com/BloodyReginaa/Neuro-CanvasLMS/main/docs/images/banner.png)
 
-> "What's due this week?" · "Summarize Lecture 5 in MATH 132." · "What feedback did I get on HW 3?" · "What's in the code ZIP for Lecture 12?"
+**Wire your Canvas LMS straight into Claude and ChatGPT.** Your courses, deadlines, grades and lecture files become part of what your AI knows, in any chat and on any device. It is a read-only remote MCP server that one command deploys to your own free Cloudflare account. Works at any Canvas school that lets students create access tokens ([30-second check](#can-you-use-it)).
+
+> "What's due this week?" · "Summarize Lecture 5 in MATH 132." · "What feedback did I get on HW 3?" · "What's in the code ZIP for Lecture 12?" · "Set up the PA2 starter code in this folder."
 
 ## Why Neuro-CanvasLMS
 
@@ -15,28 +17,33 @@
 | 💸 **Free** | It runs on Cloudflare's free plan, which is far more than one student needs. |
 | 🧠 **Your files live in the conversation** | Lecture notes and PDFs the AI reads stay with that chat on your AI provider's servers. Nothing to download. |
 
-Most Canvas integrations for AI are **local** tools: they only work while your own computer runs them, and only inside desktop or coding apps. Neuro-CanvasLMS is a **remote connector** that runs in your own Cloudflare account, so it also works on your phone and in ChatGPT.
+Local Canvas tools only work while your own computer runs them. Hosted services keep your Canvas token, or a copy of your courses, on their servers. Neuro-CanvasLMS runs in **your own** Cloudflare account: always on, usable from your phone and in ChatGPT, and your token goes only to your own Worker and your school's Canvas.
 
 ## What you get
 
-- **63 read-only tools:** courses, modules, pages, files, assignments, submissions, grades and feedback, rubrics, announcements, discussions, inbox, calendar, to-dos, groups, quiz history and profile settings.
+- **64 read-only tools:** courses, modules, pages, files, assignments, submissions, grades and feedback, rubrics, announcements, discussions, inbox, calendar, to-dos, groups, quiz history and profile settings.
 - **Real file reading:** text from PDF, Word, PowerPoint and Excel, about 90 kinds of code and text files, and Jupyter notebooks (cells and outputs); ZIP archives unpacked on the server (listing plus every code/text file); scanned or handwritten PDFs are recognised and their original pages handed to the AI to look at.
 - **Linked files too:** course files that a module links on Google Docs/Slides/Sheets, Google Drive, Dropbox (files and folders) and GitHub (files and repositories) are read as text, as long as they are shared publicly ("Anyone with the link").
 - **Finds files the course hides:** many courses hide their Files list from students. The connector searches the front page, syllabus, modules, assignments, announcements and the pages they link to, so the AI can still find "the Lecture 12 slides" by name.
+- **Starter code onto your computer:** in Claude Code, Codex and other coding agents, ask "set up PA2 from Canvas". The agent gets a one-time download link that expires in minutes, saves the assignment's starter files in your folder and unpacks them.
 - **Read-only by design:** only fixed `GET` requests. It never submits work, sends messages, starts quizzes or changes anything in Canvas.
 - **Yours only:** deployed in your own Cloudflare account and locked to your own Canvas account. Nobody else, including the authors, ever sees your Canvas token.
 
+## Can you use it?
+
+Check in 30 seconds: in Canvas, open **Account → Settings** and scroll to **Approved Integrations**. If you see a **+ New Access Token** button, you're set. If it is missing, or creating a token is refused, your school doesn't let students make personal tokens, and this connector can't work there yet.
+
 ## Install (about 5 minutes)
 
-You need [Node.js 22+](https://nodejs.org), a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and your Canvas login. In a terminal, run:
+You need [Node.js 22+](https://nodejs.org), a free [Cloudflare account](https://dash.cloudflare.com/sign-up) (verify its email address) and your Canvas login. In a terminal, run:
 
 ```bash
 npx -y neuro-canvas-lms
 ```
 
-The installer signs you in to Cloudflare (a browser page opens; click **Authorize**), asks for your school's Canvas address, deploys the connector to your own account and checks that it works. Then:
+The installer signs you in to Cloudflare (a browser page opens; click **Authorize**), asks for your school's Canvas address, sets up your free workers.dev address if the account is new, deploys the connector to your own account and checks that it works. A new address can take a few minutes to come online; meanwhile the installer opens Canvas so you can create your token. Then:
 
-1. **Create a Canvas token:** Canvas → Account → Settings → **+ New Access Token**. Your school may cap its lifetime (30 days at UMass Amherst). Copy it right away; Canvas shows it only once.
+1. **Create a Canvas token** (if you haven't yet): Canvas → Account → Settings → **+ New Access Token**. Your school may cap its lifetime (30 days at UMass Amherst). Copy it right away; Canvas shows it only once.
 2. **Claude:** Settings → Connectors → **Add custom connector** → paste the URL the installer printed (it is already copied) → **Connect** → paste the Canvas token → Authorize. It then works everywhere you use Claude, including the mobile app and Claude Code.
 3. **ChatGPT:** add a custom connector (developer mode) with the same URL.
 4. Start a new chat and ask: "What assignments do I have this week?"

package/canvas.mjs

@@ -229,27 +229,55 @@ export async function callCanvas(name, args, token, fetcher = fetch, opts = {})
   return out;
 }
 
+// Canvas could not be reached at all: say so (and that the connection is fine), so the AI retries
+// instead of changing its arguments. Our own transport messages already start with "Canvas".
+export function unreachable(e) {
+  if (/^Canvas/.test(e?.message ?? '')) return e;
+  const timeout = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+  return Object.assign(
+    new Error(
+      timeout
+        ? 'Canvas did not answer within 20 seconds; it may be slow or down right now. Try again in a minute. The token and the connection are fine: do not reconnect.'
+        : `Canvas could not be reached (network error: ${e?.name ?? 'Error'}). Try again in a minute. The token and the connection are fine: do not reconnect.`,
+    ),
+    { unreachable: true, cause: e },
+  );
+}
+
 // One GET to the Canvas API: fixed headers, no redirects, Canvas errors turned into safe messages
 // (never the upstream body). `e.status` is set when Canvas refused this item (not a token problem).
 export async function canvasGet(u, token, fetcher = fetch) {
-  const r = await fetcher(u, {
-    method: 'GET',
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: 'application/json',
-      'User-Agent': 'Neuro-CanvasLMS/2.0 (read-only personal integration)',
-    },
-    redirect: 'manual',
-    signal: AbortSignal.timeout(20000),
-  });
+  let r;
+  try {
+    r = await fetcher(u, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        'User-Agent': 'Neuro-CanvasLMS/2.0 (read-only personal integration)',
+      },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(20000),
+    });
+  } catch (e) {
+    throw unreachable(e);
+  }
   if (
     r.status === 406 ||
     (r.status >= 500 && !(r.headers.get('content-type') ?? '').includes('json'))
   ) {
-    // Canvas answers its API with JSON. An HTML error page means a firewall in front of Canvas
-    // rejected the request, or Canvas failed on a malformed token (it returns an HTML 500 for that).
-    throw new Error(
-      `Canvas returned an HTML error page (HTTP ${r.status}) instead of JSON: a firewall in front of Canvas rejected the request, or the token is malformed. If it persists, reconnect with a freshly created token.`,
+    // Canvas answers its API with JSON. An HTML error page means Canvas is down or in maintenance
+    // (502/503/504 from the load balancer), a firewall in front of Canvas rejected the request, or
+    // Canvas failed on a malformed token (an HTML 500; only possible on the authorization page,
+    // since a connected token already passed). The phrase "HTML error page" stops canvas_find_files.
+    await r.body?.cancel().catch(() => {});
+    throw Object.assign(
+      new Error(
+        [502, 503, 504].includes(r.status)
+          ? `Canvas is temporarily unavailable (HTTP ${r.status}, an HTML error page instead of JSON). Try again in a few minutes. The token and the connection are fine: do not reconnect.`
+          : `Canvas returned an HTML error page (HTTP ${r.status}) instead of JSON: usually a temporary Canvas problem or a firewall in front of Canvas. Try again in a few minutes; reconnecting does not help.`,
+      ),
+      { htmlError: r.status },
     );
   }
   if (r.status === 401) {
@@ -276,7 +304,14 @@ export async function canvasGet(u, token, fetcher = fetch) {
       ),
       { status: r.status },
     );
-  const data = await r.json();
+  let data;
+  try {
+    data = await r.json();
+  } catch {
+    throw new Error(
+      `Canvas answered HTTP ${r.status} but not with JSON (a maintenance or login page in between?). Try again in a few minutes; the token and the connection are fine.`,
+    );
+  }
   const next = nextPage(r.headers.get('link'));
   // api_url is the API request itself (it shows JSON); links for the user are the html_url fields.
   return { data, has_more: next !== null, next_page: next, api_url: u.href };
@@ -286,20 +321,47 @@ export async function canvasGet(u, token, fetcher = fetch) {
 // anyone holding the link can download the file without logging in. The connector needs it for
 // its own downloads, but it must not end up in conversations, so it is stripped from everything
 // returned to the AI. The links keep working for the user, who is logged in to Canvas.
-// Private calendar/announcement feed links (/feeds/…) work the same way and are removed whole.
+// Other passes are removed whole, in compact and raw results alike (raw skips slim.mjs):
+//  - private calendar/announcement feed links (/feeds/…);
+//  - signed links: document preview sessions (canvadoc/crocodoc), storage links signed with
+//    sf_verifier, hmac, S3/CloudFront signatures or a JWT `token`. They open a file, or carry the
+//    user's id, without logging in.
+// Ordinary links stay: Canvas pages (including a submission's preview page), Dropbox/Google share
+// links and meeting links a teacher posted, and this connector's own /dl/ download links.
+// The connector's own requests use Canvas data directly and never pass through this filter.
 const VERIFIER = /(&amp;|[?&])verifier=[^&#"'\s<>()]*(&amp;|&)?/gi;
 const FEED = /https?:\/\/[^\s"'<>()]*\/feeds\/[^\s"'<>()]+/gi;
+const LINK = /(?:https?:\/\/|\/api\/v1\/(?:canvadoc|crocodoc)_session)[^\s"'<>()]*/gi;
+const SIGNED =
+  /(?:canvadoc|crocodoc)_session|[?&](?:amp;)?(?:sf_verifier|hmac|x-amz-signature|signature)=|[?&](?:amp;)?token=[\w-]+\.[\w-]+\.[\w-]+/i;
+// A file's `uuid` is the verifier itself (Canvas accepts ?verifier=<uuid>) and its thumbnail_url
+// carries it in the path; a course's uuid is the key of its calendar feed. Raw results lose them.
+const SIGNED_KEYS = new Set([
+  'canvadoc_session_url',
+  'crocodoc_session_url',
+  'uuid',
+  'thumbnail_url',
+]);
+// The same pass URL-encoded inside another link (e.g. a login page's return_to=).
+const ENCODED_VERIFIER = /verifier%3D[^&#"'\s<>()%]*/gi;
 export function withoutVerifiers(value) {
   if (typeof value === 'string') {
     let v = value;
     if (v.includes('verifier='))
       v = v.replace(VERIFIER, (m, before, after) => (after ? before : ''));
+    if (/verifier%3D/i.test(v)) v = v.replace(ENCODED_VERIFIER, 'verifier%3D');
     if (v.includes('/feeds/')) v = v.replace(FEED, '[private feed link removed]');
+    if (/[?]|_session/.test(v))
+      v = v.replace(LINK, link => (SIGNED.test(link) ? '[signed link removed]' : link));
     return v;
   }
   if (Array.isArray(value)) return value.map(withoutVerifiers);
   if (value && typeof value === 'object')
-    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, withoutVerifiers(v)]));
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([k]) => !SIGNED_KEYS.has(k))
+        .map(([k, v]) => [k, withoutVerifiers(v)]),
+    );
   return value;
 }
 

package/download-link.mjs

@@ -0,0 +1,203 @@
+// canvas_file_download_link: put an original Canvas file on the user's own computer from a coding
+// agent with a shell (Claude Code, Codex, Cursor). Those agents get MCP resources only as links they
+// cannot save to disk; cloud chats (which can) don't need this.
+// The Worker asks Canvas for the file's download address once and takes where Canvas redirects it
+// (Canvas's file domain), minus the permanent `verifier` pass. It never downloads the bytes and never
+// requests that address itself. Measured on UMass Amherst, 2026-11-06: curl follows that address
+// (302 → 302 → 200) to the complete file once, a second use answers 401 — but its "5-minute"
+// signature is NOT enforced: an unused address still worked after 60 minutes. So the address is
+// never shown to the AI. The AI gets a link to this Worker instead (/dl/<random id>), which
+//   - works for 5 minutes and once: the Canvas address waits in this deployment's own KV with a
+//     5-minute expiry and is deleted on use;
+//   - is only honoured with the X-Canvas-Download header from the command we return, so a browser
+//     or a link preview that opens it gets a 403 and does not use it up;
+//   - answers with a redirect: the file still comes straight from Canvas, with no size limit.
+import { callCanvas } from './canvas.mjs';
+import { CANVAS_HOST } from './config.mjs';
+import { DOWNLOAD_UA, loginRedirect, allowedDownload } from './file-content.mjs';
+import { safeURL } from './module-file.mjs';
+
+export const fileDownloadLinkTool = {
+  name: 'canvas_file_download_link',
+  description:
+    "Put an ORIGINAL Canvas file (e.g. an assignment's starter-code ZIP) on the user's computer from a coding agent with a shell, such as Claude Code, Codex or Cursor: returns the exact curl command (a link that works ONCE, for 5 minutes, and only with the header in that command) and the expected size; the file itself comes straight from Canvas. Run the command right away; if it fails or expires, call this again. Cloud chats cannot reach it: there, use canvas_file_original (the app attaches the file) or canvas_file_content. Takes a Canvas file_id only (from canvas_find_files, canvas_files or a /files/<id> link).",
+  inputSchema: {
+    type: 'object',
+    properties: { file_id: { type: 'integer', minimum: 1 } },
+    required: ['file_id'],
+    additionalProperties: false,
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+};
+
+const cloudFetch = (input, init) => fetch(input, init);
+const REDIRECT = new Set([301, 302, 303, 307, 308]);
+export const DOWNLOAD_TTL = 5 * 60; // seconds a /dl link works
+export const DOWNLOAD_HEADER = 'X-Canvas-Download';
+const ID = /^[A-Za-z0-9_-]{43}$/;
+const onCanvas = u => u.hostname === CANVAS_HOST || u.hostname.endsWith('.instructure.com');
+
+// When a signed storage link stops working (epoch seconds), or null if it carries no expiry we
+// recognise. A link without one is never handed out: it could be permanent.
+export function linkExpiry(u) {
+  const q = u.searchParams;
+  for (const [, v] of q) {
+    if (!/^[\w-]+\.[\w-]+\.[\w-]+$/.test(v)) continue;
+    try {
+      const exp = JSON.parse(atob(v.split('.')[1].replace(/-/g, '+').replace(/_/g, '/'))).exp;
+      if (Number.isFinite(exp)) return exp;
+    } catch {}
+  }
+  const amzDate = q.get('X-Amz-Date');
+  const amzExpires = Number(q.get('X-Amz-Expires'));
+  if (amzDate && amzExpires > 0) {
+    const m = amzDate.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+    if (m) return Date.UTC(m[1], m[2] - 1, m[3], m[4], m[5], m[6]) / 1000 + amzExpires;
+  }
+  const expires = Number(q.get('Expires'));
+  return Number.isFinite(expires) && expires > 1e9 ? expires : null;
+}
+
+// A file name that is safe inside quotes on macOS, Linux and Windows and stays in the folder.
+export function safeFileName(name) {
+  const base = String(name ?? '')
+    .split(/[\\/]/)
+    .pop()
+    .replace(/[\x00-\x1f"*:<>?|$`]/g, '_')
+    .replace(/^\.+/, '')
+    .trim();
+  return base.slice(0, 180) || 'canvas-file';
+}
+
+export async function fileDownloadLink(
+  args,
+  token,
+  apiFetch,
+  { fetcher = cloudFetch, issue } = {},
+) {
+  if (typeof issue !== 'function')
+    throw new Error('Canvas file: download links are not available.');
+  if (
+    Object.keys(args).some(k => k !== 'file_id') ||
+    !Number.isSafeInteger(args.file_id) ||
+    args.file_id < 1
+  )
+    throw new Error('Canvas file: only a positive Canvas file_id is accepted.');
+  const meta = (await callCanvas('canvas_file', { file_id: args.file_id }, token, apiFetch)).data;
+  // `hidden` files are only hidden from the Files list ("only available with link"), which is how
+  // many courses share files; students may open them. Only a lock stops a download.
+  if (meta.locked_for_user) throw new Error('Canvas file: file is locked.');
+  if (!meta.url)
+    throw new Error('Canvas file: Canvas did not provide a download link for this file.');
+  let url = safeURL(meta.url);
+  if (!onCanvas(url)) throw new Error('Canvas file: unexpected download address.');
+  for (let hop = 0; hop < 4; hop++) {
+    // Canvas credentials are never attached: the download address carries its own authorization.
+    const r = await fetcher(url.href, {
+      method: 'GET',
+      redirect: 'manual',
+      headers: { Accept: '*/*', 'User-Agent': DOWNLOAD_UA },
+      signal: AbortSignal.timeout(15000),
+    });
+    await r.body?.cancel();
+    if (!REDIRECT.has(r.status)) {
+      if (r.ok)
+        throw new Error(
+          'Canvas file: this Canvas sends the file without a short-lived link, so no one-time link can be made. Use canvas_file_original, or give the user the html_url to download it in their browser.',
+        );
+      throw new Error(`Canvas file: the download address answered HTTP ${r.status}.`);
+    }
+    const location = r.headers.get('location');
+    if (!location) throw new Error('Canvas file: download redirect without a destination.');
+    const next = safeURL(new URL(location, url).href);
+    if (loginRedirect(next.href))
+      throw new Error('Canvas file: download was redirected to the Canvas login page.');
+    if (onCanvas(next)) {
+      url = next; // a redirect inside Canvas: not the storage link yet
+      continue;
+    }
+    if (!allowedDownload(next.href))
+      throw new Error('Canvas file: download redirected to an unexpected host.');
+    next.searchParams.delete('verifier'); // the permanent pass; the signed one stays
+    // Without a signature of its own, the address would not work once the pass is removed.
+    if (!linkExpiry(next))
+      throw new Error(
+        'Canvas file: this Canvas did not give a signed download address. Use canvas_file_original, or give the user the html_url to download it in their browser.',
+      );
+    const name = safeFileName(meta.display_name ?? meta.filename);
+    const link = await issue(next.href);
+    const header = `-H "${DOWNLOAD_HEADER}: 1"`;
+    return {
+      file_id: args.file_id,
+      name,
+      size: meta.size,
+      content_type: meta['content-type'],
+      html_url: `https://${CANVAS_HOST}/files/${args.file_id}`,
+      download_url: link,
+      expires_in_seconds: DOWNLOAD_TTL,
+      single_use: true,
+      command: `curl -L --fail ${header} -o "${name}" "${link}"`,
+      command_windows: `curl.exe -L --fail ${header} -o "${name}" "${link}"`,
+      check: `The file must be ${meta.size} bytes${/\.zip$/i.test(name) ? '; then test the archive with `unzip -t`' : ''}.`,
+      note: 'Run the command exactly as given, right away: the link works once, for 5 minutes, and only with that header. If it fails, call canvas_file_download_link again.',
+    };
+  }
+  throw new Error('Canvas file: too many redirects inside Canvas.');
+}
+
+// --- the /dl/<id> links ------------------------------------------------------------------------
+
+export function newDownloadId() {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+// Store the Canvas address for 5 minutes and return the Worker link that leads to it.
+export async function issueDownload(kv, origin, target, now = Date.now) {
+  const id = newDownloadId();
+  await kv.put('dl:' + id, JSON.stringify({ target, exp: now() + DOWNLOAD_TTL * 1000 }), {
+    expirationTtl: DOWNLOAD_TTL,
+  });
+  return `${origin}/dl/${id}`;
+}
+
+const plain = {
+  'Cache-Control': 'no-store',
+  'Referrer-Policy': 'no-referrer',
+  'X-Content-Type-Options': 'nosniff',
+  'Content-Type': 'text/plain; charset=utf-8',
+};
+// GET /dl/<id> with the header: redirect to the Canvas address once, within 5 minutes.
+export async function redeemDownload(request, kv, id, now = Date.now) {
+  if (!ID.test(id)) return new Response('Not found.\n', { status: 404, headers: plain });
+  if (request.method !== 'GET')
+    return new Response('Method not allowed.\n', { status: 405, headers: plain });
+  if (request.headers.get(DOWNLOAD_HEADER) !== '1')
+    return new Response(
+      'This one-time link only works with the curl command the connector gave (it sends the ' +
+        DOWNLOAD_HEADER +
+        ' header). Opening it anywhere else does not use it up.\n',
+      { status: 403, headers: plain },
+    );
+  const key = 'dl:' + id;
+  let entry = null;
+  try {
+    entry = JSON.parse((await kv.get(key)) ?? 'null');
+  } catch {}
+  if (entry) await kv.delete(key);
+  // KV expiry can lag a little: the stored deadline is checked too.
+  if (!entry?.target || !(now() < entry.exp))
+    return new Response(
+      'This download link has expired or was already used. Ask the AI for a new one.\n',
+      { status: 410, headers: plain },
+    );
+  return new Response(null, { status: 302, headers: { ...plain, Location: entry.target } });
+}

package/file-content.mjs

@@ -226,9 +226,24 @@ export async function extractBytes(bytes, shown, mime = '', opts = {}) {
       'This format is not supported for text extraction. Call canvas_file_original with this file_id to get the original file.',
   };
 }
+// extractBytes, but a parser failing on the file itself (damaged, password-protected, or not really
+// a PDF/Office file) becomes a note with a way on instead of an error the AI reads as "check your
+// arguments". Our own messages (limits, a wrong `entry`) start with "Canvas" and go through.
+export async function extractOrExplain(bytes, name, mime, opts, wayOn) {
+  try {
+    return await extractBytes(bytes, name, mime, opts);
+  } catch (e) {
+    if (/^Canvas/.test(e?.message ?? '')) throw e;
+    return {
+      text: null,
+      extraction_note: `Could not read the text of this file (${e?.name ?? 'Error'}): it may be damaged, password-protected, or not really the type its name says. ${wayOn}`,
+    };
+  }
+}
 export async function readFileContent(meta, args, fetcher = fetch) {
-  if (meta.locked_for_user || meta.hidden_for_user)
-    throw new Error('Canvas file is locked or hidden for this user.');
+  // `hidden` files are only hidden from the Files list ("only available with link"), which is how
+  // many courses share files; students may open them. Only a lock stops a download.
+  if (meta.locked_for_user) throw new Error('Canvas file is locked for this user.');
   const base = {
     file_id: meta.id,
     name: meta.display_name ?? meta.filename,
@@ -236,7 +251,14 @@ export async function readFileContent(meta, args, fetcher = fetch) {
     html_url: `https://${CANVAS_HOST}/files/${meta.id}`,
     mime_type: meta['content-type'],
   };
-  if (!meta.url || !allowedDownload(meta.url))
+  if (!meta.url)
+    return {
+      ...base,
+      text: null,
+      extraction_note:
+        'Canvas gives no download address for this file (it may only be viewable inside Canvas); open html_url.',
+    };
+  if (!allowedDownload(meta.url))
     return {
       ...base,
       text: null,
@@ -261,14 +283,22 @@ export async function readFileContent(meta, args, fetcher = fetch) {
       throw new Error(
         'Canvas file redirect host is not allowed: ' + [...hops, where(url)].join(' → '),
       );
-    response = await fetcher(url, {
-      method: 'GET',
-      redirect: 'manual',
-      headers: { Accept: '*/*', 'User-Agent': DOWNLOAD_UA },
-      signal: AbortSignal.timeout(20000),
-    });
+    try {
+      response = await fetcher(url, {
+        method: 'GET',
+        redirect: 'manual',
+        headers: { Accept: '*/*', 'User-Agent': DOWNLOAD_UA },
+        signal: AbortSignal.timeout(20000),
+      });
+    } catch (e) {
+      if (/^Canvas/.test(e?.message ?? '')) throw e;
+      throw new Error(
+        `Canvas file download did not finish (${e?.name === 'TimeoutError' || e?.name === 'AbortError' ? 'no answer within 20 seconds' : 'network error: ' + (e?.name ?? 'Error')}; ${where(url)}). Try again in a minute; the connection is fine.`,
+      );
+    }
     hops.push(response.status + ' ' + where(url));
     if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel().catch(() => {});
       const location = response.headers.get('location');
       if (!location) throw new Error('Canvas download redirect is missing its destination.');
       url = new URL(location, url).href;
@@ -292,11 +322,12 @@ export async function readFileContent(meta, args, fetcher = fetch) {
         (response.headers.get('content-type') ?? 'unknown').split(';')[0] +
         ').',
     );
-  const extracted = await extractBytes(
+  const extracted = await extractOrExplain(
     await boundedBytes(response),
     base.name ?? '',
     base.mime_type ?? response.headers.get('content-type') ?? '',
     { entry: args.entry, storedName: meta.filename },
+    'Call canvas_file_original with this file_id to get the file itself, or open html_url.',
   );
   return paginated(base, extracted, args);
 }

package/find-files.mjs

@@ -180,14 +180,24 @@ export async function findFiles(args, token, fetcher) {
     return canvasGet(u, token, fetcher);
   };
   const searched = {};
-  // One source failing (hidden, not enabled) is normal; an expired token stops everything.
+  // A source being hidden or not enabled (401/403/404) is normal. A source that failed (timeout,
+  // network, rate limit, Canvas error) was not searched: the result is then incomplete, and if
+  // nothing could be searched at all the error is passed on instead of an empty "complete" list.
+  // An expired token or an HTML error page (Canvas down, a firewall) stops everything.
+  const failures = [];
+  const hidden = e => [401, 403, 404].includes(e.status);
   const attempt = async (source, run) => {
     try {
       const n = await run();
       searched[source] = n === undefined ? 'ok' : `ok (${n})`;
     } catch (e) {
       if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
-      searched[source] = e.status ? `not available (HTTP ${e.status})` : 'failed';
+      if (hidden(e)) searched[source] = `not available (HTTP ${e.status})`;
+      else {
+        failures.push(e);
+        complete = false;
+        searched[source] = e.status ? `failed (HTTP ${e.status})` : 'failed';
+      }
     }
   };
   const pagesOf = async (path, query, maxPages, each) => {
@@ -337,7 +347,8 @@ export async function findFiles(args, token, fetcher) {
 
   // Pages linked from everything above, breadth first, never outside this course.
   let pagesRead = 0,
-    pagesUnavailable = 0;
+    pagesUnavailable = 0,
+    pagesFailed = 0;
   while (queue.length) {
     const batch = queue.splice(0, PAGE_BATCH).filter(slug => !read.has(slug));
     await Promise.all(
@@ -355,7 +366,12 @@ export async function findFiles(args, token, fetcher) {
           });
         } catch (e) {
           if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
-          pagesUnavailable++;
+          if (hidden(e)) pagesUnavailable++;
+          else {
+            failures.push(e);
+            complete = false;
+            pagesFailed++;
+          }
         }
       }),
     );
@@ -365,7 +381,20 @@ export async function findFiles(args, token, fetcher) {
     }
   }
   searched.linked_pages =
-    `${pagesRead} read` + (pagesUnavailable ? `, ${pagesUnavailable} not available` : '');
+    `${pagesRead} read` +
+    (pagesUnavailable ? `, ${pagesUnavailable} not available` : '') +
+    (pagesFailed ? `, ${pagesFailed} failed` : '');
+  const sources = Object.entries(searched).filter(([k]) => k !== 'linked_pages');
+  // Nothing could be searched: say why instead of "no files, complete".
+  if (failures.length && !pagesRead && !sources.some(([, v]) => v.startsWith('ok'))) {
+    const e = failures.find(x => /^Canvas/.test(x.message ?? '')) ?? failures[0];
+    throw /^Canvas/.test(e.message ?? '')
+      ? e
+      : new Error(`Canvas could not be searched (${e.name}). Try again in a minute.`);
+  }
+  // Every source 404: most likely not a course this user is in.
+  const wrongCourse =
+    !files.size && sources.length && sources.every(([, v]) => v === 'not available (HTTP 404)');
 
   let list = [...files.values()];
   let matchedOn = null;
@@ -393,11 +422,21 @@ export async function findFiles(args, token, fetcher) {
     external_links: ext,
     searched,
     complete,
-    ...(complete
-      ? {}
-      : {
-          note: `Stopped after ${requests} Canvas requests; some linked pages or lists were not searched. Open more pages with canvas_context_page or canvas_module_items if the file is not listed.`,
-        }),
+    ...(failures.length
+      ? {
+          note: `Some places could not be searched (they failed, see searched: ${failures.length} failed request${failures.length > 1 ? 's' : ''}), so a file missing here may still exist. Try again in a minute before telling the user it is not there.`,
+        }
+      : complete
+        ? {}
+        : {
+            note: `Stopped after ${requests} Canvas requests; some linked pages or lists were not searched. Open more pages with canvas_context_page or canvas_module_items if the file is not listed.`,
+          }),
+    ...(wrongCourse
+      ? {
+          course_note:
+            'Every part of this course answered 404: check the course_id (canvas_courses lists the user’s courses).',
+        }
+      : {}),
     how_to_read:
       'Read a file_id with canvas_file_content (text from PDF/Office/code, ZIP listing and contents) or canvas_file_original (original bytes, e.g. scanned PDFs). An external link with read_with (a module item): call canvas_module_file_content with those IDs for its text (Google Docs/Slides/Sheets/Drive, Dropbox, GitHub), or canvas_module_file for the original file. Other external links cannot be read by this connector: give the user the link.',
   };