Phase 6: Canvas integration — connect, link, file import, roster sync

[sroygit]

Phase 6 — Canvas integration (read-only)

An instructor connects their own Canvas account via OAuth, links a Canvas course they teach, imports Canvas Files into the course's materials, and syncs the Canvas roster so a student on it can enroll with the registration code alone.

Design: docs/superpowers/specs/2026-08-27-canvas-integration-design.md · Plan: docs/superpowers/plans/phase-6/Saurav/ · Contract: docs/api-contract.md → "Canvas LMS".

What's in it

• @ubc/ubc-genai-toolkit-lms-integration@^1.2.0 (GitHub Packages). The committed .npmrc carries only the @ubc registry line; each developer needs a read:packages PAT in ~/.npmrc.
• components/lms/ binds the package to FinanceBot identity: getUserKey = req.user.puid, tokens in lmsCanvasTokens. Mounted under /api/lms/canvas only when all four CANVAS_* variables are set.
• Course link — course.canvas sub-document. PUT link refuses any Canvas course not in the connected identity's teacher list. Every Canvas read derives its external course id from the stored link, never a request body.
• File import — Canvas Files in an upload-accepted format under the shared 50 MB limit, downloaded with maxBytes, written under uploads/ like a multer upload, handed to the existing createMaterials → ingestMaterial pipeline. Material.origin + the fixed-name partial unique index materials_origin_unique make a re-import a skip, never a duplicate. Per-file independent.
• Roster sync — matched on Canvas integration_id (= PUID at UBC) only, no fallback key. Stored in a new lmsRosterEntries collection with two unique indexes; each sync replaces the course's set. A roster exposing no integration_id is refused (409 roster-coverage) and nothing is written.
• Enrollment gate — passes on the CSV roster or a Canvas entry by PUID. The Canvas lookup runs only when the CSV roster did not match, so existing behaviour is byte-identical. Synced entries add to the CSV roster; the CSV path is the escape hatch (e.g. a student whose Canvas account has no integration_id).
• UI — Settings gains a Canvas card (connect → choose course → linked; sync report with coverage; unlink; disconnect). Materials gains Import from Canvas for linked courses.
• PRD — Canvas linking/import/roster sync moved into scope; gradebook write-back stays a stretch goal.

Not in it, on purpose

No writes to Canvas (grades, feedback). No Moodle. No submission import.

Verification

• Full suite green: 102 suites / 1,291 tests (+45 new). Typecheck, lint, client build clean.
• End-to-end smoke against local Canvas (../local-lms-dev/, verified 2026-08-27) as a plain non-admin teacher — every step matched the prediction, with each stage confirmed in the database. Table in docs/superpowers/plans/phase-6/Saurav/STATUS.md. Highlights: a student with no CSV entry enrolled via the Canvas roster alone; a Canvas user without integration_id was reported and not stored; unlink left enrollments and imported materials intact.

Reviewer notes

• materials.routes.test.ts mocks the whole materials.service; the upload limits now come from that module, so the mock supplies them. Anyone else mocking it wholesale will need the same.
• The package's structural MongoDbLike type doesn't satisfy mongodb v7's Db at the type level (createIndex param variance); one cast at the boundary in components/lms/index.ts, runtime-compatible. Worth an upstream note.
• Before go-live: the production Developer Key must be scoped to the five endpoints in the spec's Configuration section with Allow Include Parameters on, and someone should confirm with LT Hub that hosted UBC Canvas populates integration_id with the PUID and exposes it to Teacher-role tokens. Locally it does; hosted is a separate account-level configuration.