Canvas to Obsidian Local-First Bridge

🎓 The Academic Knowledge Management Dilemma

Modern higher education and enterprise training programs rely almost universally on Learning Management Systems (LMS) like Instructure Canvas to distribute coursework, lecture modules, assignments, student discussions, and grading rubrics.

Yet for technical students, researchers, and security practitioners who build their intellectual workflows inside personal knowledge management (PKM) tools like Obsidian, Canvas represents an isolated, walled-off data silo:

Ephemerality & Term Expiration: Once an academic semester concludes, student access to Canvas courses is routinely archived or revoked. Syllabi, instructor annotations, curated reading lists, and assignment rubrics vanish behind institutional access gates.
Disconnected Knowledge Silos: Course notes authored in Obsidian remain disconnected from source materials, grading criteria, and module pacing guides living inside the web browser.
Administrative Token Gating: Canvas exposes an extensive REST API, but institutional administrators frequently disable personal access tokens (Account > Settings > + New Access Token) for student roles due to enterprise compliance policies.
Third-Party Cloud Aggregation Risks: Existing third-party scrapers and web integrations require routing student session credentials, course documents, and peer discussions through external SaaS servers. For students handling proprietary lab code or education records governed by FERPA and GDPR, third-party cloud aggregation is an unacceptable privacy compromise.

Third-Party Cloud Scraper (High Risk):
[Canvas LMS] ----(Credentials/Course Data)----> [Cloud Relay / SaaS] ----> [Obsidian Vault]
                                                        ▲
                                                        └── Attack Surface & Data Leakage Risk

Canvas to Obsidian Sync (Hybrid Local-First Architecture):
[Canvas LMS REST API] ════(Direct Token / requestUrl)═══════════════════╗
                                                                        ▼
[Canvas LMS Web Tab]  ════(Session Cookies)════> [Browser Ext] ──(127.0.0.1)──> [Obsidian Vault]

To bridge this divide while respecting strict privacy boundaries, I designed and open-sourced Canvas to Obsidian Sync (v0.3.1)—a hybrid, local-first ecosystem that provides two flexible ingestion pathways converging on a unified rendering engine.

🏛️ Hybrid Ingestion Architecture

obsidian-canvas-sync employs a hybrid architecture that adapts to both institutional API policies and platform constraints:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                   CANVAS LMS CLOUD                                     │
│   ┌────────────────────────────────────────────────────────────────────────────────┐   │
│   │  Canvas REST API (/api/v1/...)                                                 │   │
│   │  - Courses, Modules, Pages, Syllabus                                           │   │
│   │  - Assignments, Rubrics & Student Submissions                                  │   │
│   │  - Discussions & Complete Nested Reply Trees                                   │   │
│   │  - Calendar Events & Due Date Milestones                                       │   │
│   │  - Course Files & Static Asset Downloads                                       │   │
│   └────────────────────────┬───────────────────────────────┬───────────────────────┘   │
└────────────────────────────┼───────────────────────────────┼───────────────────────────┘
                             │                               │
        Mode A: Direct API   │ HTTPS                         │ Mode B: Session-Based
      (Obsidian requestUrl)  │ (Bearer Token)                │ (Browser Session Cookies)
                             │                               ▼
                             │                 ┌───────────────────────────┐
                             │                 │ Companion Web Extension   │
                             │                 │ (Chrome / Firefox)        │
                             │                 │ - Session Extractor       │
                             │                 │ - Extraction Toggles      │
                             │                 └─────────────┬─────────────┘
                             │                               │ Loopback POST (127.0.0.1:27125)
                             │                               │ (Opt-in / Disabled by default)
                             ▼                               ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              OBSIDIAN PLUGIN RUNTIME                                   │
│  ┌─────────────────────────┐                     ┌──────────────────────────────────┐  │
│  │ CanvasApiClient         │                     │ Loopback Bridge Server           │  │
│  │ (Direct API Connection) │                     │ (conditionally active)           │  │
│  └────────────┬────────────┘                     └────────────────┬─────────────────┘  │
│               │                                                   │                    │
│               └─────────────────────┬─────────────────────────────┘                    │
│                                     │                                                  │
│                                     ▼                                                  │
│                       ┌───────────────────────────┐                                    │
│                       │   Canonical Course Payload│                                    │
│                       │   (CanvasCoursePayload)   │                                    │
│                       └─────────────┬─────────────┘                                    │
│                                     │                                                  │
│                                     ▼                                                  │
│                       ┌───────────────────────────┐                                    │
│                       │ Markdown & Link Engine    │                                    │
│                       │ - GFM Converter (Turndown)│                                    │
│                       │ - Wikilink Transformer    │                                    │
│                       │ - Table Pipe Escaper      │                                    │
│                       └─────────────┬─────────────┘                                    │
│                                     │                                                  │
│                                     ▼                                                  │
│                       ┌───────────────────────────┐                                    │
│                       │ Asset & File Downloader   │                                    │
│                       │ - Binary Streamer         │                                    │
│                       │ - Size/Extension Filters  │                                    │
│                       └─────────────┬─────────────┘                                    │
│                                     │                                                  │
│                                     ▼                                                  │
│                       ┌───────────────────────────┐                                    │
│                       │ Vault Note Generator      │                                    │
│                       │ - Path Sanitization       │                                    │
│                       │ - Templated Course Vault  │                                    │
│                       └─────────────┬─────────────┘                                    │
└─────────────────────────────────────┼──────────────────────────────────────────────────┘
                                      ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              OBSIDIAN VAULT STORAGE                                    │
│  └── Canvas/CS101 - Intro to CS/                                                       │
│      ├── Course.md, Home.md, Syllabus.md, Grades.md                                    │
│      ├── Tasks.md, Discussions.md, Calendar.md                                         │
│      ├── Modules/01 - Week 1/01 - Page - Lecture.md                                    │
│      ├── Files/ (PDF, DOCX, XLSX, etc.)                                                │
│      └── Attachments/ (Images, Banners)                                                │
└────────────────────────────────────────────────────────────────────────────────────────┘

The Two Ingestion Modes

Ingestion Mode	Primary Mechanism	Best For	Platform Support
Mode A: Direct REST API	Obsidian native `requestUrl` using Canvas Bearer Token	Standard users, automated multi-course batch syncing, historical/concluded course archiving	Obsidian Desktop & Mobile
Mode B: Companion Web Extension	Manifest V3 background script extracting active tab session cookies	Locked-down universities where student API keys are disabled	Chrome, Firefox, Brave, Edge, Arc

🔒 Threat Modeling & Security Hardening

Operating an open HTTP listener within an Electron desktop application introduces potential Cross-Site Port Scanning and CSRF risks if an attacker attempts to transmit payloads to 127.0.0.1.

In obsidian-canvas-sync v0.3.1, the loopback bridge implements strict defense-in-depth controls:

1. Opt-In Loopback Server (Closed by Default)

The local HTTP server on 127.0.0.1:27125 is disabled by default. Users relying on the Direct REST API mode never expose a local TCP port. The bridge only initializes when the user explicitly enables browser extension sync in plugin settings.

2. Mandatory Origin & Client Header Guards

Preflight OPTIONS and POST requests must present:

An approved extension scheme (chrome-extension:// or moz-extension://).
The mandatory custom header: X-Canvas-Sync-Client: Obsidian-Canvas-Sync-Extension.

Browsers prohibit arbitrary websites from setting custom request headers across origins without triggering CORS preflight rejections, isolating the endpoint from drive-by web scripts.

3. Path Traversal & Filename Sanitization

Canvas module names and assignment titles often contain characters that are illegal across POSIX/NTFS file systems or represent directory traversal sequences (../../).

All paths pass through deterministic sanitization:

1
2
3
4
5
6
7
export function sanitizeVaultPath(input: string): string {
    return input
        .replace(/[\\/:*?"<>|]/g, '-')  // Strip illegal filesystem characters
        .replace(/\.\.+/g, '.')          // Eliminate directory traversal sequences
        .replace(/^\/+|\/+$/g, '')       // Trim boundary slashes
        .trim();
}

📊 Comprehensive Synchronization Capabilities

Both ingestion modes stream data into a unified canonical payload (CanvasCoursePayload), producing complete, interconnected course vaults:

1. Grades & Submissions (`Grades.md`)

Syncs active grade standing, current course scores, submission status (Submitted, Graded, Missing), points earned vs points possible, submitted file links, and instructor feedback comments.

1
2
3
4
5
6
### 📊 Student Gradebook Summary

| Assignment | Status | Score | Max Points | Feedback |
| :--- | :--- | :--- | :--- | :--- |
| **Lab 1: Cryptanalysis** | Graded | 95.0 | 100.0 | Great implementation of Kasiski examination. |
| **Midterm Exam** | Graded | 88.0 | 90.0 | Solid analysis on forward secrecy. |

2. Discussions with Nested Reply Trees (`Discussions.md`)

Preserves instructor discussion prompts along with complete multi-tier nested student replies, formatted as hierarchical callouts with author timestamps and direct link anchors.

3. Assignments & Rubric Table Normalization (`Tasks.md`)

Canvas rubrics use complex, nested HTML tables. The engine converts these into clean GitHub Flavored Markdown (GFM) tables, capturing rating descriptions, point distributions, and grading criteria:

1
2
3
4
5
6
### 📋 Assignment Grading Rubric

| Criterion | Ratings | Max Points |
| :--- | :--- | :--- |
| **Architecture & Threat Model** | • Exemplary (20 pts): STRIDE model applied.<br>• Proficient (15 pts): Minor gaps.<br>• Novice (5 pts): Missing loopback controls. | 20 pts |
| **Unit Test Coverage** | • Full Marks (30 pts): 100% Vitest pass rate.<br>• Partial (20 pts): Missing edge cases. | 30 pts |

4. Local File & Asset Downloader (`Files/` & `Attachments/`)

Directly downloads referenced course documents (.pdf, .docx, .pptx, .xlsx, .zip) and embedded images into dedicated vault folders. Includes configurable maximum file size limits (default: 50MB) and extension allowlists.

5. Wikilink Engine with Table Pipe Escaping

All internal module items and syllabus links are resolved to Obsidian [[wikilinks]]. Table-embedded links use strict pipe escaping ([[path\|alias]]) to ensure markdown tables render without broken column boundaries.

🗂️ Generated Vault Structure

Synced courses generate a structured, navigable directory hierarchy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
Canvas/
└── CS510 - Advanced Network Security/
    ├── Course.md         # Master index note with metadata & instructor contact
    ├── Home.md           # Course landing page & announcement banners
    ├── Syllabus.md       # Complete syllabus text, policies & textbook list
    ├── Tasks.md          # Assignment checklists, due dates & rubric tables
    ├── Grades.md         # Gradebook table with scores, percentages & feedback
    ├── Discussions.md    # Discussion board topics with full student reply trees
    ├── Calendar.md       # Course milestones, due dates & Zoom meeting links
    ├── Modules/
    │   ├── 01 - Week 1 - Applied Cryptography/
    │   │   ├── 01 - Page - Stream Ciphers & Block Ciphers.md
    │   │   └── 02 - Assignment - Breaking Polyalphabetic Ciphers.md
    │   └── 02 - Week 2 - Protocol Vulnerabilities/
    │       ├── 01 - Page - TLS 1.3 & Forward Secrecy.md
    │       └── 02 - Assignment - Wireshark Decryption Lab.md
    ├── Files/            # Downloaded PDFs, DOCX, slides, spreadsheets, and archives
    └── Attachments/      # Embedded images, course banners, and diagrams

🚀 Installation & Getting Started

1. Install the Obsidian Plugin

Method A: Community Plugins (Recommended)

Open Obsidian Settings > Community Plugins.
Disable Restricted mode if prompted.
Search for Canvas Sync Bridge, click Install, and Enable.

Method B: Obsidian BRAT (Beta Builds)

Install the BRAT Plugin in Obsidian.

Under BRAT settings, click Add Beta plugin and enter:

https://github.com/SixFiveMil/obsidian-canvas-sync

Method C: Manual Release

Download main.js, manifest.json, and styles.css from the Latest GitHub Release and place them in <Vault>/.obsidian/plugins/canvas-sync-bridge/.

2. Choose Your Sync Method

Option A: Direct REST API (Recommended)

In Canvas, navigate to Account > Settings > Approved Integrations > + New Access Token.
Copy your generated access token.
In Obsidian Settings under Canvas Sync, enter your Canvas Base URL (https://canvas.instructure.com or your institution domain) and API Token.
Press Ctrl/Cmd + P and run Canvas Sync: Select & sync courses (or click the 🎓 ribbon icon) to launch the interactive course selector.

Option B: Browser Extension Bridge (Zero-Token Mode)

In Obsidian Settings under Canvas Sync, toggle on Enable browser bridge listener.
Install the companion extension:
- 🌐 Chrome Web Store (Chrome, Edge, Brave, Arc, Opera)
- 🦊 Firefox Add-ons (Mozilla)
Open any Canvas course tab in your browser, click the extension icon, test the bridge connection, and click Sync Active Course.

🤝 Open Source & Community RFC

obsidian-canvas-sync is distributed under the MIT License and developed publicly at SixFiveMil/obsidian-canvas-sync.

We welcome feedback, issues, and contributions from students, researchers, and educators. Join the architectural discussion on GitHub Discussions!

🎓 The Academic Knowledge Management Dilemma#

🏛️ Hybrid Ingestion Architecture#

The Two Ingestion Modes#

🔒 Threat Modeling & Security Hardening#

1. Opt-In Loopback Server (Closed by Default)#

2. Mandatory Origin & Client Header Guards#

3. Path Traversal & Filename Sanitization#

📊 Comprehensive Synchronization Capabilities#

1. Grades & Submissions (Grades.md)#

2. Discussions with Nested Reply Trees (Discussions.md)#

3. Assignments & Rubric Table Normalization (Tasks.md)#

4. Local File & Asset Downloader (Files/ & Attachments/)#

5. Wikilink Engine with Table Pipe Escaping#

🗂️ Generated Vault Structure#

🚀 Installation & Getting Started#

1. Install the Obsidian Plugin#

Method A: Community Plugins (Recommended)#

Method B: Obsidian BRAT (Beta Builds)#

Method C: Manual Release#

2. Choose Your Sync Method#

Option A: Direct REST API (Recommended)#

Option B: Browser Extension Bridge (Zero-Token Mode)#

🤝 Open Source & Community RFC#