@ivanbard/dd2l 0.1.0 → 0.1.1

package/src/discovery.mjs

@@ -1,45 +1,45 @@
-export function courseNodes(tree, now = Date.now()) {
-  const result = [];
-  function visit(node, unavailable = false) {
-    if (!node || typeof node !== 'object') return;
-    const restricted = unavailable || node.IsHidden === true || node.IsLocked === true ||
-      Date.parse(node.StartDateTime) > now || Date.parse(node.EndDateTime) < now;
-    result.push({ ...node, restricted });
-    for (const child of [...(node.Modules || []), ...(node.Topics || [])]) visit(child, restricted);
-  }
-  visit(tree);
-  return result;
-}
-
-export function reconcileQuizzes(list, tree, grades, origin) {
-  const known = new Map();
-  const candidates = [];
-  for (const quiz of list || []) if (/^\d+$/.test(String(quiz.QuizId))) known.set(String(quiz.QuizId), { quizId: String(quiz.QuizId), name: quiz.Name, sources: ['quiz_list'], gradeItemId: quiz.GradeItemId, restricted: false });
-  for (const topic of courseNodes(tree).filter(node => node.TopicId != null)) {
-    let url;
-    try { url = new URL(topic.Url, origin); } catch {}
-    const quizTopic = topic.ActivityType === 4 || /quiz/i.test(topic.TypeIdentifier || '') ||
-      (url?.origin === origin && url.pathname.includes('/quizzing/'));
-    if (!quizTopic) continue;
-    const identifier = topic.ToolItemId ?? (url?.origin === origin ? url.searchParams.get('qi') : null);
-    if (/^\d+$/.test(String(identifier))) {
-      const key = String(identifier);
-      const existing = known.get(key);
-      if (existing) { existing.sources.push('content'); existing.restricted &&= topic.restricted; }
-      else known.set(key, { quizId: key, name: topic.Title, sources: ['content'], topicId: topic.TopicId, restricted: topic.restricted, gradeItemId: topic.GradeItemId });
-    } else candidates.push({ name: topic.Title, topicId: topic.TopicId, source: 'content', restricted: topic.restricted, detailsStatus: 'unresolved' });
-  }
-  for (const grade of grades || []) {
-    const quiz = [...known.values()].find(item => item.gradeItemId != null && String(item.gradeItemId) === String(grade.GradeObjectIdentifier));
-    if (quiz) quiz.sources.push('gradebook');
-    else if (/\bquiz/i.test(grade.GradeObjectName || '')) candidates.push({ name: grade.GradeObjectName, gradeItemId: grade.GradeObjectIdentifier, source: 'gradebook', detailsStatus: 'unresolved' });
-  }
-  return { quizzes: [...known.values()], candidates };
-}
-
-export function batch(items, offset = 0, size = 25) {
-  const start = Number.isSafeInteger(offset) && offset >= 0 && offset < items.length ? offset : 0;
-  const selected = items.slice(start, start + size);
-  return { items: selected, total: items.length, start, next: start + selected.length >= items.length ? 0 : start + selected.length,
-    limited: items.length > selected.length };
-}
+export function courseNodes(tree, now = Date.now()) {
+  const result = [];
+  function visit(node, unavailable = false) {
+    if (!node || typeof node !== 'object') return;
+    const restricted = unavailable || node.IsHidden === true || node.IsLocked === true ||
+      Date.parse(node.StartDateTime) > now || Date.parse(node.EndDateTime) < now;
+    result.push({ ...node, restricted });
+    for (const child of [...(node.Modules || []), ...(node.Topics || [])]) visit(child, restricted);
+  }
+  visit(tree);
+  return result;
+}
+
+export function reconcileQuizzes(list, tree, grades, origin) {
+  const known = new Map();
+  const candidates = [];
+  for (const quiz of list || []) if (/^\d+$/.test(String(quiz.QuizId))) known.set(String(quiz.QuizId), { quizId: String(quiz.QuizId), name: quiz.Name, sources: ['quiz_list'], gradeItemId: quiz.GradeItemId, restricted: false });
+  for (const topic of courseNodes(tree).filter(node => node.TopicId != null)) {
+    let url;
+    try { url = new URL(topic.Url, origin); } catch {}
+    const quizTopic = topic.ActivityType === 4 || /quiz/i.test(topic.TypeIdentifier || '') ||
+      (url?.origin === origin && url.pathname.includes('/quizzing/'));
+    if (!quizTopic) continue;
+    const identifier = topic.ToolItemId ?? (url?.origin === origin ? url.searchParams.get('qi') : null);
+    if (/^\d+$/.test(String(identifier))) {
+      const key = String(identifier);
+      const existing = known.get(key);
+      if (existing) { existing.sources.push('content'); existing.restricted &&= topic.restricted; }
+      else known.set(key, { quizId: key, name: topic.Title, sources: ['content'], topicId: topic.TopicId, restricted: topic.restricted, gradeItemId: topic.GradeItemId });
+    } else candidates.push({ name: topic.Title, topicId: topic.TopicId, source: 'content', restricted: topic.restricted, detailsStatus: 'unresolved' });
+  }
+  for (const grade of grades || []) {
+    const quiz = [...known.values()].find(item => item.gradeItemId != null && String(item.gradeItemId) === String(grade.GradeObjectIdentifier));
+    if (quiz) quiz.sources.push('gradebook');
+    else if (/\bquiz/i.test(grade.GradeObjectName || '')) candidates.push({ name: grade.GradeObjectName, gradeItemId: grade.GradeObjectIdentifier, source: 'gradebook', detailsStatus: 'unresolved' });
+  }
+  return { quizzes: [...known.values()], candidates };
+}
+
+export function batch(items, offset = 0, size = 25) {
+  const start = Number.isSafeInteger(offset) && offset >= 0 && offset < items.length ? offset : 0;
+  const selected = items.slice(start, start + size);
+  return { items: selected, total: items.length, start, next: start + selected.length >= items.length ? 0 : start + selected.length,
+    limited: items.length > selected.length };
+}

package/src/documents.mjs

@@ -1,154 +1,154 @@
-import { createHash } from 'node:crypto';
-import { Worker } from 'node:worker_threads';
-import { Parser } from 'htmlparser2';
-import { AccessError } from './client.mjs';
-import { officeText } from './office.mjs';
-import { recognizeImage } from './ocr.mjs';
-
-export function htmlContent(html) {
-  html = String(html || '');
-  let mainStart = -1, mainEnd, depth = 0, elements = 0;
-  const scan = new Parser({ onopentag(name, attrs) {
-    if (++elements > 100_000) throw new AccessError('partial', 'HTML exceeds the extraction element limit.');
-    if (mainStart < 0 && (name === 'main' || attrs.role === 'main')) { mainStart = scan.startIndex; depth = 1; }
-    else if (depth) depth++;
-  }, onclosetag() { if (depth && --depth === 0) mainEnd = scan.endIndex + 1; } });
-  scan.end(html);
-  if (mainStart >= 0) html = html.slice(mainStart, mainEnd);
-  const parts = [];
-  const links = [];
-  const block = new Set(['p', 'div', 'br', 'li', 'tr', 'td', 'th', 'h1', 'h2', 'h3', 'h4', 'section']);
-  const ignored = new Set(['head', 'script', 'style', 'template', 'noscript', 'nav', 'footer']);
-  let hidden = 0;
-  let anchor;
-  const parser = new Parser({
-    onopentag(name, attrs) {
-      if (ignored.has(name)) hidden++;
-      if (hidden) return;
-      if (block.has(name)) parts.push('\n');
-      if (name === 'a' && attrs.href) {
-        anchor = { url: attrs.href, label: '' };
-        links.push(anchor);
-      }
-      if (['iframe', 'embed', 'object'].includes(name) && (attrs.src || attrs.data)) {
-        links.push({ url: attrs.src || attrs.data, label: attrs.title || '', embedded: true });
-      }
-    },
-    ontext(value) { if (!hidden) { parts.push(value); if (anchor) anchor.label += value; } },
-    onclosetag(name) {
-      if (ignored.has(name)) hidden = Math.max(0, hidden - 1);
-      if (!hidden && block.has(name)) parts.push('\n');
-      if (name === 'a') anchor = undefined;
-    },
-  }, { decodeEntities: true });
-  parser.end(String(html || ''));
-  return { text: parts.join('').replace(/[\t \u00a0]+/g, ' ').replace(/ *\n */g, '\n').replace(/\n{3,}/g, '\n\n').trim(), links };
-}
-
-export function descriptionContent(description) {
-  if (description?.Html) return htmlContent(description.Html);
-  return { text: String(description?.Text || '').trim(), links: [] };
-}
-
-async function pdfText(bytes) {
-  return new Promise((resolve, reject) => {
-    const worker = new Worker(new URL('./pdf-worker.mjs', import.meta.url), {
-      workerData: bytes, stdout: true, stderr: true, resourceLimits: { maxOldGenerationSizeMb: 256 },
-    });
-    worker.stdout.resume();
-    worker.stderr.resume();
-    let settled = false;
-    const timer = setTimeout(() => finish(new AccessError('extraction_failed', 'PDF extraction exceeded its 30-second limit.')), 30_000);
-    const finish = (error, value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      void worker.terminate();
-      if (error) reject(error); else resolve(value);
-    };
-    worker.once('message', value => value.error ? finish(new AccessError('extraction_failed', value.error)) : finish(null, value));
-    worker.once('error', () => finish(new AccessError('extraction_failed', 'PDF text extraction failed.')));
-    worker.once('exit', code => { if (code !== 0) finish(new AccessError('extraction_failed', 'PDF extraction worker stopped.')); });
-  });
-}
-
-export async function readDocument(client, path) {
-  const response = await client.response(path);
-  const contentType = response.headers.get('content-type') || 'application/octet-stream';
-  if (!response.body) throw new AccessError('invalid_response', 'Document response has no body.');
-  const reader = response.body.getReader();
-  const chunks = [];
-  let size = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      size += value.length;
-      if (size > 20 * 1024 * 1024) throw new AccessError('partial', 'Document exceeds the 20 MiB read limit.');
-      chunks.push(value);
-    }
-  } catch (error) {
-    if (error instanceof AccessError) throw error;
-    throw new AccessError('retry_wait', 'Document body read failed or timed out.');
-  } finally { await reader.cancel().catch(() => {}); }
-  const bytes = Buffer.concat(chunks);
-  const isPdf = bytes.subarray(0, 5).toString() === '%PDF-' || /application\/pdf/i.test(contentType);
-  const isHtml = /(?:text\/html|application\/xhtml\+xml)/i.test(contentType);
-  const isOffice = /openxmlformats|msword|ms-excel|ms-powerpoint/i.test(contentType) || bytes.subarray(0, 2).toString() === 'PK';
-  if (isHtml && bytes.toString().includes('/d2l/login?sessionExpired=1')) throw new AccessError('needs_login', 'School session has expired.');
-  const result = { contentType, size, sha256: createHash('sha256').update(bytes).digest('hex'),
-    base64: size <= 2 * 1024 * 1024 ? bytes.toString('base64') : undefined, bytesRetained: size <= 2 * 1024 * 1024,
-    text: null, links: [], resolvedUrl: response.url || undefined,
-    format: isPdf ? 'pdf' : isHtml ? 'html' : 'other', textStatus: 'unsupported' };
-  if (isPdf) {
-    try {
-      const extracted = await pdfText(bytes);
-      const { images, pageTexts, ...metadata } = extracted;
-      let ocrFailed = false;
-      let ocrPages = 0;
-      for (const image of images) {
-        try { pageTexts[image.index] = await recognizeImage(image.bytes); ocrPages++; }
-        catch (error) { ocrFailed = true; result.textError = error.message; break; }
-      }
-      if (images.length) {
-        metadata.text = pageTexts.join('\n\n').slice(0, 1_000_000);
-        metadata.ocrPages = ocrPages;
-        metadata.ocrPendingPages = images.length - ocrPages;
-        metadata.needsReview = true;
-        metadata.extractionMethod = 'embedded_text_and_windows_ocr';
-      }
-      if (ocrFailed) metadata.truncated = true;
-      Object.assign(result, metadata);
-      result.textStatus = metadata.truncated ? 'partial' : result.text.trim() ? 'available' : 'empty';
-    } catch (error) {
-      result.textStatus = 'failed';
-      result.textError = error.message;
-    }
-  } else if (isOffice) {
-    try {
-      Object.assign(result, officeText(bytes));
-      result.textStatus = result.truncated ? 'partial' : result.text ? 'available' : 'empty';
-    } catch (error) {
-      result.textStatus = /No supported/.test(error.message) ? 'unsupported' : 'failed';
-      result.format = result.textStatus === 'unsupported' ? 'archive' : 'other';
-      result.textError = result.textStatus === 'unsupported' ? 'Archive has no supported Office document parts; archive contents were not extracted.' :
-        'Office extraction failed, exceeded safety limits, or uses a legacy binary format; export to DOCX/PPTX/XLSX or PDF.';
-    }
-  } else if (/^image\/(?:png|jpeg|bmp|tiff)/i.test(contentType)) {
-    try {
-      result.text = await recognizeImage(bytes);
-      Object.assign(result, { format: 'image', extractionMethod: 'windows_ocr', needsReview: true, textStatus: result.text ? 'available' : 'empty' });
-    } catch (error) { result.textStatus = 'failed'; result.textError = error.message; }
-  } else if (isHtml) {
-    Object.assign(result, htmlContent(bytes.toString('utf8')));
-    result.textStatus = result.text ? 'available' : 'empty';
-  } else if (/^(?:text\/|application\/json)/i.test(contentType)) {
-    const text = bytes.toString('utf8').trim();
-    result.text = text.slice(0, 1_000_000);
-    result.format = 'text';
-    result.textStatus = text.length > 1_000_000 ? 'partial' : result.text ? 'available' : 'empty';
-  }
-  if (result.text?.length > 1_000_000) { result.text = result.text.slice(0, 1_000_000); result.textStatus = 'partial'; result.truncated = true; }
-  if (result.links.length > 200) { result.links = result.links.slice(0, 200); result.linksLimited = true; }
-  return result;
-}
+import { createHash } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
+import { Parser } from 'htmlparser2';
+import { AccessError } from './client.mjs';
+import { officeText } from './office.mjs';
+import { recognizeImage } from './ocr.mjs';
+
+export function htmlContent(html) {
+  html = String(html || '');
+  let mainStart = -1, mainEnd, depth = 0, elements = 0;
+  const scan = new Parser({ onopentag(name, attrs) {
+    if (++elements > 100_000) throw new AccessError('partial', 'HTML exceeds the extraction element limit.');
+    if (mainStart < 0 && (name === 'main' || attrs.role === 'main')) { mainStart = scan.startIndex; depth = 1; }
+    else if (depth) depth++;
+  }, onclosetag() { if (depth && --depth === 0) mainEnd = scan.endIndex + 1; } });
+  scan.end(html);
+  if (mainStart >= 0) html = html.slice(mainStart, mainEnd);
+  const parts = [];
+  const links = [];
+  const block = new Set(['p', 'div', 'br', 'li', 'tr', 'td', 'th', 'h1', 'h2', 'h3', 'h4', 'section']);
+  const ignored = new Set(['head', 'script', 'style', 'template', 'noscript', 'nav', 'footer']);
+  let hidden = 0;
+  let anchor;
+  const parser = new Parser({
+    onopentag(name, attrs) {
+      if (ignored.has(name)) hidden++;
+      if (hidden) return;
+      if (block.has(name)) parts.push('\n');
+      if (name === 'a' && attrs.href) {
+        anchor = { url: attrs.href, label: '' };
+        links.push(anchor);
+      }
+      if (['iframe', 'embed', 'object'].includes(name) && (attrs.src || attrs.data)) {
+        links.push({ url: attrs.src || attrs.data, label: attrs.title || '', embedded: true });
+      }
+    },
+    ontext(value) { if (!hidden) { parts.push(value); if (anchor) anchor.label += value; } },
+    onclosetag(name) {
+      if (ignored.has(name)) hidden = Math.max(0, hidden - 1);
+      if (!hidden && block.has(name)) parts.push('\n');
+      if (name === 'a') anchor = undefined;
+    },
+  }, { decodeEntities: true });
+  parser.end(String(html || ''));
+  return { text: parts.join('').replace(/[\t \u00a0]+/g, ' ').replace(/ *\n */g, '\n').replace(/\n{3,}/g, '\n\n').trim(), links };
+}
+
+export function descriptionContent(description) {
+  if (description?.Html) return htmlContent(description.Html);
+  return { text: String(description?.Text || '').trim(), links: [] };
+}
+
+async function pdfText(bytes) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL('./pdf-worker.mjs', import.meta.url), {
+      workerData: bytes, stdout: true, stderr: true, resourceLimits: { maxOldGenerationSizeMb: 256 },
+    });
+    worker.stdout.resume();
+    worker.stderr.resume();
+    let settled = false;
+    const timer = setTimeout(() => finish(new AccessError('extraction_failed', 'PDF extraction exceeded its 30-second limit.')), 30_000);
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      if (error) reject(error); else resolve(value);
+    };
+    worker.once('message', value => value.error ? finish(new AccessError('extraction_failed', value.error)) : finish(null, value));
+    worker.once('error', () => finish(new AccessError('extraction_failed', 'PDF text extraction failed.')));
+    worker.once('exit', code => { if (code !== 0) finish(new AccessError('extraction_failed', 'PDF extraction worker stopped.')); });
+  });
+}
+
+export async function readDocument(client, path) {
+  const response = await client.response(path);
+  const contentType = response.headers.get('content-type') || 'application/octet-stream';
+  if (!response.body) throw new AccessError('invalid_response', 'Document response has no body.');
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > 20 * 1024 * 1024) throw new AccessError('partial', 'Document exceeds the 20 MiB read limit.');
+      chunks.push(value);
+    }
+  } catch (error) {
+    if (error instanceof AccessError) throw error;
+    throw new AccessError('retry_wait', 'Document body read failed or timed out.');
+  } finally { await reader.cancel().catch(() => {}); }
+  const bytes = Buffer.concat(chunks);
+  const isPdf = bytes.subarray(0, 5).toString() === '%PDF-' || /application\/pdf/i.test(contentType);
+  const isHtml = /(?:text\/html|application\/xhtml\+xml)/i.test(contentType);
+  const isOffice = /openxmlformats|msword|ms-excel|ms-powerpoint/i.test(contentType) || bytes.subarray(0, 2).toString() === 'PK';
+  if (isHtml && bytes.toString().includes('/d2l/login?sessionExpired=1')) throw new AccessError('needs_login', 'School session has expired.');
+  const result = { contentType, size, sha256: createHash('sha256').update(bytes).digest('hex'),
+    base64: size <= 2 * 1024 * 1024 ? bytes.toString('base64') : undefined, bytesRetained: size <= 2 * 1024 * 1024,
+    text: null, links: [], resolvedUrl: response.url || undefined,
+    format: isPdf ? 'pdf' : isHtml ? 'html' : 'other', textStatus: 'unsupported' };
+  if (isPdf) {
+    try {
+      const extracted = await pdfText(bytes);
+      const { images, pageTexts, ...metadata } = extracted;
+      let ocrFailed = false;
+      let ocrPages = 0;
+      for (const image of images) {
+        try { pageTexts[image.index] = await recognizeImage(image.bytes); ocrPages++; }
+        catch (error) { ocrFailed = true; result.textError = error.message; break; }
+      }
+      if (images.length) {
+        metadata.text = pageTexts.join('\n\n').slice(0, 1_000_000);
+        metadata.ocrPages = ocrPages;
+        metadata.ocrPendingPages = images.length - ocrPages;
+        metadata.needsReview = true;
+        metadata.extractionMethod = 'embedded_text_and_windows_ocr';
+      }
+      if (ocrFailed) metadata.truncated = true;
+      Object.assign(result, metadata);
+      result.textStatus = metadata.truncated ? 'partial' : result.text.trim() ? 'available' : 'empty';
+    } catch (error) {
+      result.textStatus = 'failed';
+      result.textError = error.message;
+    }
+  } else if (isOffice) {
+    try {
+      Object.assign(result, officeText(bytes));
+      result.textStatus = result.truncated ? 'partial' : result.text ? 'available' : 'empty';
+    } catch (error) {
+      result.textStatus = /No supported/.test(error.message) ? 'unsupported' : 'failed';
+      result.format = result.textStatus === 'unsupported' ? 'archive' : 'other';
+      result.textError = result.textStatus === 'unsupported' ? 'Archive has no supported Office document parts; archive contents were not extracted.' :
+        'Office extraction failed, exceeded safety limits, or uses a legacy binary format; export to DOCX/PPTX/XLSX or PDF.';
+    }
+  } else if (/^image\/(?:png|jpeg|bmp|tiff)/i.test(contentType)) {
+    try {
+      result.text = await recognizeImage(bytes);
+      Object.assign(result, { format: 'image', extractionMethod: 'windows_ocr', needsReview: true, textStatus: result.text ? 'available' : 'empty' });
+    } catch (error) { result.textStatus = 'failed'; result.textError = error.message; }
+  } else if (isHtml) {
+    Object.assign(result, htmlContent(bytes.toString('utf8')));
+    result.textStatus = result.text ? 'available' : 'empty';
+  } else if (/^(?:text\/|application\/json)/i.test(contentType)) {
+    const text = bytes.toString('utf8').trim();
+    result.text = text.slice(0, 1_000_000);
+    result.format = 'text';
+    result.textStatus = text.length > 1_000_000 ? 'partial' : result.text ? 'available' : 'empty';
+  }
+  if (result.text?.length > 1_000_000) { result.text = result.text.slice(0, 1_000_000); result.textStatus = 'partial'; result.truncated = true; }
+  if (result.links.length > 200) { result.links = result.links.slice(0, 200); result.linksLimited = true; }
+  return result;
+}

package/src/links.mjs

@@ -1,99 +1,99 @@
-import { AccessError, checkedResponse } from './client.mjs';
-import { readDocument } from './documents.mjs';
-import { courseNodes } from './discovery.mjs';
-
-// Only observed public reference hosts; private providers need their own sign-in.
-const publicHosts = new Set(['www.queensu.ca', 'smithengineering.queensu.ca', 'www.cs.queensu.ca',
-  'www.cs.cmu.edu', 'www.perfeng.com', 'sunnyday.mit.edu', 'www.instructables.com',
-  'www.sciencedaily.com', 'www.protoexpress.com', 'www.youtube.com', 'www.youtube-nocookie.com', 'youtu.be']);
-
-export function linkUrl(client, target, base = client.origin) {
-  let url;
-  try { url = new URL(target, base); } catch { throw new AccessError('invalid_link', 'Invalid document link.'); }
-  if (url.username || url.password) throw new AccessError('invalid_link', 'Credentials in a document URL are not supported.');
-  url.hash = '';
-  if (/%(?:2f|5c|25(?:2e|2f|5c))/i.test(url.pathname)) throw new AccessError('invalid_link', 'Encoded path traversal is not a supported document target.');
-  if (url.username || url.password || url.protocol !== 'https:') {
-    if (url.protocol === 'http:' && publicHosts.has(url.hostname)) url.protocol = 'https:';
-    else throw new AccessError('unsupported_link', 'Only HTTPS document links can be read.');
-  }
-  if (url.origin === client.origin && (url.pathname.startsWith('/content/') || url.pathname.startsWith('/shared/'))) return url;
-  if (url.origin !== client.origin && publicHosts.has(url.hostname) && (!url.port || url.port === '443')) {
-    for (const key of [...url.searchParams.keys()]) if (/token|session|csrf|xsrf|authorization/i.test(key)) url.searchParams.delete(key);
-    return url;
-  }
-  throw new AccessError('external_auth_required', 'Link needs a provider-specific reader or is an unsupported school action; it was not followed.');
-}
-
-export function actionLink(target, origin) {
-  try {
-    const url = new URL(target, origin);
-    return ['mailto:', 'tel:', 'javascript:'].includes(url.protocol) || target.startsWith('#') ||
-      (url.origin === origin && /quickLink\.d2l$/i.test(url.pathname) &&
-        /survey|enroll|dropbox|quiz|discussion/i.test(url.searchParams.get('type') || ''));
-  } catch { return false; }
-}
-
-export async function linkedResponse(client, target) {
-  let url = linkUrl(client, target);
-  for (let redirects = 0; redirects <= 5; redirects++) {
-    const headers = { accept: '*/*' };
-    if (url.origin === client.origin) {
-      const session = await client.session.load();
-      headers.cookie = session.cookies.filter(cookie => {
-        const domain = cookie.domain.replace(/^\./, '');
-        const path = cookie.path || '/';
-        return (url.hostname === domain || url.hostname.endsWith(`.${domain}`)) &&
-          (url.pathname === path || url.pathname.startsWith(path.endsWith('/') ? path : `${path}/`)) &&
-          (cookie.expires === -1 || !cookie.expires || cookie.expires > Date.now() / 1000);
-      }).map(cookie => `${cookie.name}=${cookie.value}`).join('; ');
-    }
-    let response;
-    try { response = await client.fetch(url, { headers, redirect: 'manual', signal: AbortSignal.timeout(30_000) }); }
-    catch { throw new AccessError('retry_wait', 'Linked document request failed or timed out.'); }
-    if (response.status >= 300 && response.status < 400) {
-      const next = response.headers.get('location');
-      await response.body?.cancel();
-      if (!next) throw new AccessError('invalid_link', 'Redirect did not identify a target.');
-      url = linkUrl(client, next, url);
-      continue;
-    }
-    if ([401, 403].includes(response.status) && url.origin !== client.origin) throw new AccessError('external_auth_required', 'Public provider refused the reader or requires its own sign-in.');
-    return checkedResponse(response, url);
-  }
-  throw new AccessError('partial', 'Linked document exceeded the redirect limit.');
-}
-
-export async function readLinkedDocument(client, target, { le, courseId, tree, base = client.origin } = {}) {
-  let url;
-  try { url = new URL(target, base); } catch { throw new AccessError('invalid_link', 'Invalid document link.'); }
-  const topic = url.origin === client.origin && url.pathname.match(/^\/d2l\/le\/content\/(\d+)\/viewContent\/(\d+)\/(?:View|Home)\/?$/i);
-  const apiFile = url.origin === client.origin && url.pathname.match(/^\/d2l\/api\/le\/\d+\.\d+\/(\d+)\/(?:content\/topics\/(\d+)\/file|overview\/attachment)$/);
-  const linkedCourse = topic?.[1] || apiFile?.[1];
-  const linkedTopic = topic?.[2] || apiFile?.[2];
-  if (linkedCourse && linkedCourse !== String(courseId)) throw new AccessError('unsupported_link', 'Linked document belongs to a different course.');
-  const known = courseNodes(tree).find(node => {
-    if (linkedTopic) return String(node.TopicId) === linkedTopic;
-    try { return node.Url && new URL(node.Url, client.origin).href === url.href; } catch { return false; }
-  });
-  if (known?.restricted) throw new AccessError('restricted', 'Linked source or its ancestor is outside release conditions.');
-  if (known?.ActivityType === 1 && /^\d+$/.test(String(known.TopicId))) return readDocument(client, `${le}/content/topics/${known.TopicId}/file`);
-  if (apiFile) return readDocument(client, linkedTopic ? `${le}/content/topics/${linkedTopic}/file` : `${le}/overview/attachment`);
-  if (topic) {
-    if (topic[1] !== String(courseId)) throw new AccessError('unsupported_link', 'Linked topic belongs to a different course.');
-    const path = `${le}/content/topics/${topic[2]}`;
-    const metadata = await client.get(path);
-    if (metadata.IsHidden || metadata.IsLocked || Date.parse(metadata.StartDate) > Date.now() || Date.parse(metadata.EndDate) < Date.now()) {
-      throw new AccessError('restricted', 'Linked topic is outside its release conditions.');
-    }
-    if (metadata.Type === 1 || metadata.ActivityType === 1) return readDocument(client, `${path}/file`);
-    if (metadata.Url && metadata.Url !== target && metadata.Url !== url.href) {
-      // File/static/public links only here; another topic cannot create a recursion loop.
-      return readDocument({ response: value => linkedResponse(client, value) }, linkUrl(client, metadata.Url).href);
-    }
-    throw new AccessError('unsupported_link', 'Linked topic has no directly readable document target.');
-  }
-  const safe = linkUrl(client, url.href);
-  const document = await readDocument({ response: value => linkedResponse(client, value) }, safe.href);
-  return { ...document, resolvedUrl: safe.href };
-}
+import { AccessError, checkedResponse } from './client.mjs';
+import { readDocument } from './documents.mjs';
+import { courseNodes } from './discovery.mjs';
+
+// Only observed public reference hosts; private providers need their own sign-in.
+const publicHosts = new Set(['www.queensu.ca', 'smithengineering.queensu.ca', 'www.cs.queensu.ca',
+  'www.cs.cmu.edu', 'www.perfeng.com', 'sunnyday.mit.edu', 'www.instructables.com',
+  'www.sciencedaily.com', 'www.protoexpress.com', 'www.youtube.com', 'www.youtube-nocookie.com', 'youtu.be']);
+
+export function linkUrl(client, target, base = client.origin) {
+  let url;
+  try { url = new URL(target, base); } catch { throw new AccessError('invalid_link', 'Invalid document link.'); }
+  if (url.username || url.password) throw new AccessError('invalid_link', 'Credentials in a document URL are not supported.');
+  url.hash = '';
+  if (/%(?:2f|5c|25(?:2e|2f|5c))/i.test(url.pathname)) throw new AccessError('invalid_link', 'Encoded path traversal is not a supported document target.');
+  if (url.username || url.password || url.protocol !== 'https:') {
+    if (url.protocol === 'http:' && publicHosts.has(url.hostname)) url.protocol = 'https:';
+    else throw new AccessError('unsupported_link', 'Only HTTPS document links can be read.');
+  }
+  if (url.origin === client.origin && (url.pathname.startsWith('/content/') || url.pathname.startsWith('/shared/'))) return url;
+  if (url.origin !== client.origin && publicHosts.has(url.hostname) && (!url.port || url.port === '443')) {
+    for (const key of [...url.searchParams.keys()]) if (/token|session|csrf|xsrf|authorization/i.test(key)) url.searchParams.delete(key);
+    return url;
+  }
+  throw new AccessError('external_auth_required', 'Link needs a provider-specific reader or is an unsupported school action; it was not followed.');
+}
+
+export function actionLink(target, origin) {
+  try {
+    const url = new URL(target, origin);
+    return ['mailto:', 'tel:', 'javascript:'].includes(url.protocol) || target.startsWith('#') ||
+      (url.origin === origin && /quickLink\.d2l$/i.test(url.pathname) &&
+        /survey|enroll|dropbox|quiz|discussion/i.test(url.searchParams.get('type') || ''));
+  } catch { return false; }
+}
+
+export async function linkedResponse(client, target) {
+  let url = linkUrl(client, target);
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    const headers = { accept: '*/*' };
+    if (url.origin === client.origin) {
+      const session = await client.session.load();
+      headers.cookie = session.cookies.filter(cookie => {
+        const domain = cookie.domain.replace(/^\./, '');
+        const path = cookie.path || '/';
+        return (url.hostname === domain || url.hostname.endsWith(`.${domain}`)) &&
+          (url.pathname === path || url.pathname.startsWith(path.endsWith('/') ? path : `${path}/`)) &&
+          (cookie.expires === -1 || !cookie.expires || cookie.expires > Date.now() / 1000);
+      }).map(cookie => `${cookie.name}=${cookie.value}`).join('; ');
+    }
+    let response;
+    try { response = await client.fetch(url, { headers, redirect: 'manual', signal: client.signal ? AbortSignal.any([client.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000) }); }
+    catch { throw new AccessError('retry_wait', 'Linked document request failed or timed out.'); }
+    if (response.status >= 300 && response.status < 400) {
+      const next = response.headers.get('location');
+      await response.body?.cancel();
+      if (!next) throw new AccessError('invalid_link', 'Redirect did not identify a target.');
+      url = linkUrl(client, next, url);
+      continue;
+    }
+    if ([401, 403].includes(response.status) && url.origin !== client.origin) throw new AccessError('external_auth_required', 'Public provider refused the reader or requires its own sign-in.');
+    return checkedResponse(response, url);
+  }
+  throw new AccessError('partial', 'Linked document exceeded the redirect limit.');
+}
+
+export async function readLinkedDocument(client, target, { le, courseId, tree, base = client.origin } = {}) {
+  let url;
+  try { url = new URL(target, base); } catch { throw new AccessError('invalid_link', 'Invalid document link.'); }
+  const topic = url.origin === client.origin && url.pathname.match(/^\/d2l\/le\/content\/(\d+)\/viewContent\/(\d+)\/(?:View|Home)\/?$/i);
+  const apiFile = url.origin === client.origin && url.pathname.match(/^\/d2l\/api\/le\/\d+\.\d+\/(\d+)\/(?:content\/topics\/(\d+)\/file|overview\/attachment)$/);
+  const linkedCourse = topic?.[1] || apiFile?.[1];
+  const linkedTopic = topic?.[2] || apiFile?.[2];
+  if (linkedCourse && linkedCourse !== String(courseId)) throw new AccessError('unsupported_link', 'Linked document belongs to a different course.');
+  const known = courseNodes(tree).find(node => {
+    if (linkedTopic) return String(node.TopicId) === linkedTopic;
+    try { return node.Url && new URL(node.Url, client.origin).href === url.href; } catch { return false; }
+  });
+  if (known?.restricted) throw new AccessError('restricted', 'Linked source or its ancestor is outside release conditions.');
+  if (known?.ActivityType === 1 && /^\d+$/.test(String(known.TopicId))) return readDocument(client, `${le}/content/topics/${known.TopicId}/file`);
+  if (apiFile) return readDocument(client, linkedTopic ? `${le}/content/topics/${linkedTopic}/file` : `${le}/overview/attachment`);
+  if (topic) {
+    if (topic[1] !== String(courseId)) throw new AccessError('unsupported_link', 'Linked topic belongs to a different course.');
+    const path = `${le}/content/topics/${topic[2]}`;
+    const metadata = await client.get(path);
+    if (metadata.IsHidden || metadata.IsLocked || Date.parse(metadata.StartDate) > Date.now() || Date.parse(metadata.EndDate) < Date.now()) {
+      throw new AccessError('restricted', 'Linked topic is outside its release conditions.');
+    }
+    if (metadata.Type === 1 || metadata.ActivityType === 1) return readDocument(client, `${path}/file`);
+    if (metadata.Url && metadata.Url !== target && metadata.Url !== url.href) {
+      // File/static/public links only here; another topic cannot create a recursion loop.
+      return readDocument({ response: value => linkedResponse(client, value) }, linkUrl(client, metadata.Url).href);
+    }
+    throw new AccessError('unsupported_link', 'Linked topic has no directly readable document target.');
+  }
+  const safe = linkUrl(client, url.href);
+  const document = await readDocument({ response: value => linkedResponse(client, value) }, safe.href);
+  return { ...document, resolvedUrl: safe.href };
+}