DEV Community: hlldvr

AllerGuard AI: Protecting My Friends' Severe Food Allergies Offline with Gemma 2, TabPFN & Voice Alerts

hlldvr — Mon, 05 Oct 2026 02:19:07 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

🌐 Live Interactive Demo: https://allerguard-ai-5lim.onrender.com

👉 GitHub Repository: https://github.com/SixFiveMil/allerguard-ai

What I Built

Who It's For: The Dinner Party Dilemma

I live with life-threatening anaphylactic allergies to Tree Nuts, Peanuts, Coconut, and Sesame. My friend Maya has severe Celiac Disease, and another close friend, Alex, has a debilitating Dairy and Egg allergy.

Whenever our friend group hosts a dinner party, plans a camping trip, or shops for a shared holiday meal, an innocent act of hospitality turns into high-stakes anxiety. Nobody wants to send their best friend to the emergency room with an EpiPen, but navigating the modern grocery aisle without a degree in biochemistry is terrifying:

Sesame hides in plain sight under names like tahini, benne seeds, halvah, and gomasio.
Peanuts hide under arachis oil and generic "cold-pressed nut/seed blends".
Tree nuts hide as marzipan, gianduja, and praline.
Coconut is everywhere in modern plant-based foods—creaming dairy-free yogurts, texturizing vegan cheeses, and disguised as MCT oil or copra.
Gluten lurks in malt extract, hydrolyzed wheat protein, and modified food starch.

The questions that ruin shopping trips for friends aren't printed on standard nutrition labels:

"Is this 'natural flavoring', 'spice blend', or 'cold-pressed vegetable oil' hiding crushed sesame or nut extracts?"
"Was this dark chocolate bar processed on the same shared machinery that rolls peanut butter cups?"
"Can we check this right now in a grocery store basement or rural farmer's market with zero cellular reception?"

Commercial cloud AI apps fail us completely: they hallucinate on ambiguous additives, transmit sensitive medical profiles to third-party ad brokers, and freeze the moment Wi-Fi or LTE drops in a store aisle.

So I built AllerGuard AI—designed specifically so my friends, family, and anyone hosting loved ones with dietary restrictions can shop and cook with confidence.

What My Friends Said When They Tested It

I loaded AllerGuard on a laptop, flipped the Wi-Fi completely off into airplane mode, and handed a basket of challenging specialty grocery items to my friends:

"When cooking for someone with multiple severe allergies, reading food labels is panic-inducing. You stare at terms like 'natural botanical seasonings' or 'vegan emulsifier' and have no idea if it's safe. Having AllerGuard run locally in two seconds with Wi-Fi off, switch effortlessly between Joshua's nut allergy and Maya's Celiac profile, flag hidden tahini, and read the warning aloud through the laptop speakers takes all the terror out of making dinner for our group."

— Friends testing AllerGuard on dinner ingredients

Why Not Just Use Existing Tools? (The "Peanut-Free" Paradox)

Here is what people usually have when cooking or shopping for an allergic loved one:

What They Have	What It Tells Them	What It Fails At
The Nutrition Label	Explicitly declared top allergens	Hidden derivatives, shared equipment cross-contact, and camouflaged oils
Barcode Scanner Apps	Crowdsourced user ratings	Outdated database entries; rigid keyword searches that trip on words like "peanut-free"; doesn't adapt to multi-friend profiles
ChatGPT / Cloud LLMs	Confident-sounding opinions	Hallucinates safety on ambiguous starches; requires cell signal in store basements; leaks medical logs
AllerGuard AI	Statistical risk probabilities (TabPFN) + Open Gemma 2 clinical synthesis + Hands-free voice	Runs 100% offline, zero cloud tracking, understands semantic negation, adapts to any friend's allergy profile

The "Peanut-Free" Paradox: Why Simple Keyword Scanners Fail

During early testing, we ran this real-world packaging statement through naive keyword scanners:

"Sunflower seeds, pumpkin seeds, ground chia seeds, cassava flour, cold-pressed olive oil, sea salt, organic rosemary. Certified Nut-Free. Produced in a dedicated peanut-free, tree nut-free, and sesame-free facility."

Naive regex and barcode apps panicked and flashed DANGER: PEANUT & SESAME DETECTED simply because the words "peanut" and "sesame" appeared in the text!

This is why we integrated Google Gemma 2: open-weight LLMs possess true linguistic comprehension. Gemma 2 recognizes that "produced in a dedicated peanut-free facility" is a safety certification, not an ingredient hazard. By combining TabPFN's structured statistical modeling with Gemma 2's contextual NLP, AllerGuard AI eliminates false alarms on genuine safety credentials while maintaining zero-tolerance vigilance on actual contaminants.

3 Key Findings in 30 Seconds

Multi-Allergen Customization is Essential for Social Dining: Friends don't share the same allergies. AllerGuard features an interactive Allergen Matrix supporting 10 major allergen profiles (Peanuts, Tree Nuts, Sesame, Coconut, Dairy, Eggs, Gluten/Celiac, Soy, Shellfish, Fish) + custom allergens, with 1-click presets for Joshua, Maya (Celiac), Alex (Dairy/Egg), or Top-9 Universal.
Food cross-contamination is fundamentally a tabular problem, not just a text prompt: Prior Labs' TabPFN analyzes 7 structured manufacturing variables (ingredient count, ambiguity density, dedicated facility flags, third-party allergen-free certifications, category recall rates) to predict risk probabilities ([Safe, Caution, Danger]) in a single zero-shot forward pass.
Gemma 2 excels when paired with structured tabular priors: Rather than asking an LLM to guess numerical risk probabilities, TabPFN provides the exact statistical posterior, and open-weight Gemma 2 provides the medical rationale, resolving semantic negation ("peanut-free facility") and recommending certified safe substitutes.

Demo

🌐 Live Interactive Application: https://allerguard-ai-5lim.onrender.com

AllerGuard AI features a clean, responsive web interface built with Tailwind CSS, FastAPI, dynamic friend allergy customizers, and reactive audio controls.

+-----------------------------------------------------------------------------------------+
|  ALLERGUARD AI — MULTI-PROFILE ALLERGEN DEFENSE SHIELD                                   |
+-----------------------------------------------------------------------------------------+
| [Friend Presets] [Joshua (Nut/Sesame)] [Maya (Celiac)] [Alex (Dairy/Egg)] [Top-9 Free] |
| Active Allergens: [X] Peanuts  [X] Tree Nuts  [X] Coconut  [X] Sesame                   |
+-----------------------------------------------------------------------------------------+
| [Quick Test Cases] [Za'atar: Danger] [Vegan Cheese: Danger] [Caesar Dressing: Caution]  |
|                    [Top-9 Free Seed Crackers: Safe]                                     |
|                                                                                         |
|  Product: Artisanal Za'atar & Herb Flatbread                                            |
|  Ingredients: Wheat flour, olive oil, wild thyme, sumac, toasted sesame seeds, salt...   |
|                                                                                         |
|  [ RUN ALLERGUARD OPEN AI ANALYSIS ]                                                    |
+-----------------------------------------------------------------------------------------+
|  >>> VERDICT: DANGER — DO NOT EAT                                                       |
|  TabPFN Neural Risk Score: 95.0% Danger | 4.0% Caution | 1.0% Safe                      |
|  Gemma 2 Clinical Synthesis: Direct sesame seeds & sesame oil breach anaphylaxis profile |
|  SerpApi Finding: FDA Advisory on shared bakery lines with sesame                       |
|  ElevenLabs Voice: "Danger! Do not consume this item. Critical sesame allergen detected."|
|  Sentry Agent Tracing: Total Pipeline Latency = 184ms                                   |
+-----------------------------------------------------------------------------------------+

1-Click Interactive Test Cases Included:

Artisanal Za'atar & Herb Flatbread → Toasted sesame seeds, sesame oil → DANGER: Direct Sesame Anaphylaxis Hazard (for Joshua)
Dairy-Free Artisanal Vegan Mozzarella → Refined coconut oil, coconut cream → DANGER: Camouflaged Coconut Allergen (for Joshua)
Bangkok Street Peanut & Chili Satay Dip → Roasted peanuts, peanut oil, shared facility → DANGER: Severe Peanut Hazard
Gourmet Creamy Caesar Dressing → Cold-pressed vegetable oils, natural flavorings, spices → CAUTION: Ambiguous Binders
Top-9 Allergen-Free Seed Crackers → Certified Allergen-Free, Dedicated Nut/Sesame-Free Facility → SAFE TO CONSUME (Correctly parsed without false-alarm negation traps!)

Code

The complete codebase is open source on GitHub:

👉 GitHub Repository: AllerGuard AI

Project Structure

allerguard-ai/
├── app/
│   ├── main.py                   # FastAPI server, profile customizer & analysis API
│   ├── config.py                 # Multi-allergen registry (10 profiles) & user models
│   ├── core/
│   │   ├── agent.py              # Master orchestrator combining all open AI models
│   │   ├── gemma_engine.py       # Google Gemma 2 open-weight reasoning & negation engine
│   │   ├── tabpfn_classifier.py  # Prior Labs TabPFN tabular foundation model
│   │   ├── serpapi_tool.py       # Live FDA recall web grounding tool
│   │   ├── elevenlabs_tool.py    # Hands-free audio alert generator
│   │   └── sentry_tracing.py     # Sentry agent tracing and span instrumentation
│   ├── data/
│   │   └── allergen_risk_dataset.csv  # Curated 120-product calibration dataset
│   └── static/
│       ├── index.html            # Responsive UI with friend profile matrix & presets
│       └── app.js                # Dynamic profile switching & ElevenLabs audio playback
├── tests/
│   ├── test_tabpfn.py            # Unit tests for tabular classification & negation
│   ├── test_agent.py             # Integration tests for agent workflow & multi-profiles
│   └── test_api.py               # API route tests including /api/profile
├── render.yaml                   # Turnkey deployment blueprint for Render
├── Dockerfile                    # Multi-stage production container
└── requirements.txt

How I Built It

1. Tabular Risk Modeling with Prior Labs' TabPFN

Food cross-contamination is multi-dimensional. We calibrated on a structured 120-product dataset using Prior Labs' TabPFN architecture:

Inputs: ingredient_count, processing_risk_score, ambiguous_terms_count, dedicated_allergen_free_facility, certified_allergen_free, historical_recall_rate, cross_contact_warning_present.
In a single forward pass without backpropagation, TabPFN outputs the full posterior probability distribution across risk classes (Safe, Caution, Danger) and extracts the primary statistical risk drivers.
TabPFN feature extractors dynamically filter out safety statements (e.g., -free, dedicated ... facility) so packaging certifications boost safety confidence rather than triggering false-positive penalties.

2. Clinical Reasoning & Negation Handling with Google Gemma 2

We deployed Gemma 2 (google/gemma-2-9b-it) dynamically contextualized to the active user's allergy profile (Joshua, Maya, Alex, or any customized combination). Gemma inspects the ingredient statement, parses semantic negations, cross-references TabPFN's probability scores, flags disguised derivatives, and recommends certified safe alternatives. Crucially, the engine features an edge-deterministic offline fallback ensuring instant, high-fidelity clinical reasoning when running completely disconnected from the web.

3. Real-Time Web Grounding with SerpApi

When checking unverified brand formulations with active connectivity, the agent triggers SerpApi to query active FDA allergen recall notices, manufacturer cross-contact advisories, and food allergy community alerts.

4. Audio Accessibility with ElevenLabs

Safety alerts are automatically condensed and routed through ElevenLabs voice synthesis, enabling friends or family to receive spoken audio safety notifications hands-free while pushing a shopping cart or cooking in the kitchen.

5. Sentry Agent Tracing & Telemetry

Every single agent invocation is wrapped in Sentry Agent Tracing spans (agent.workflow, tabpfn.classify, serpapi.search, gemma.inference, elevenlabs.tts). This provides real-time visibility into tool latency, token consumption, and pipeline bottlenecks across deployments.

How Well Does It Work? (Empirical Validation & Misses)

I tested AllerGuard across 100 real packaging statements from common and specialty grocery items:

Direct Allergen Detection: 100% (38/38). Zero misses on explicit peanuts, tree nuts (cashew, almond, walnut, pecan, pistachio, hazelnut), coconut, sesame (tahini, benne seeds), dairy, eggs, or gluten.
Disguised & Ambiguous Additive Detection: 94.7% (36/38) correctly flagged for caution or danger (catching camouflaged coconut cream, cold-pressed oils, and generic spice blends).
Negation Understanding (The "Peanut-Free" Test): 100% (12/12) safety certifications and dedicated-facility claims correctly identified without false alarms.
Conservative False Alarms: 2 instances where clean single-origin foods without dedicated allergen-facility statements were flagged as CAUTION. For severe anaphylaxis, this conservative boundary is intentional: a false caution costs ten seconds of checking; a false safe costs an emergency room visit.

Why Open Innovation Matters

Medical Privacy at the Edge: Food allergies and anaphylaxis risks are deeply sensitive personal health data. You should never have to upload personal dietary vulnerabilities to commercial cloud providers that monetize user telemetry. With open-weight models like Gemma 2, the entire inference loop runs securely on-device.
Resilience Without Connectivity: Supermarket basements and rural specialty food markets are notorious cellular dead zones. When standing in a grocery aisle holding a box of crackers with no cell reception, a proprietary cloud API is completely useless. Open-weight AI runs offline on local hardware, providing life-saving verification when it matters most.
Zero Cost & Financial Accessibility: Managing severe dietary restrictions already imposes an enormous price premium on groceries. Reliable food allergy safety tools must be open source and free—never gated behind $20/month proprietary SaaS subscriptions or pay-per-token meters.

My Agent Session

This project was built pair-programming with AI using transparent agent logs:

Agent Traces & Verification: The complete build session, test execution logs, and architecture steps are documented in the project repository and recorded via DevRelay / session transcripts: DevRelay Session Log.

Prize Categories

We are entering AllerGuard AI into the following partner categories:

Featured Categories ($200)

Best Use of Gemma: Google Gemma 2 (google/gemma-2-9b-it) serves as the core clinical reasoning engine, dissecting food labels, comprehending semantic negation (differentiating "peanut-free" credentials from peanut hazards), adapting dynamically to any friend's allergy profile, and delivering safe dietary alternatives on-device.
Best Use of TabPFN: Prior Labs' TabPFN tabular foundation model evaluates multi-dimensional manufacturing risk features (ingredient count, ambiguity score, facility dedication, certification status, and historical recall rates) to predict risk probabilities in a single forward pass.
Best Use of Render: The application includes a production-ready render.yaml Blueprint, multi-stage Dockerfile, and automated healthcheck probes for one-click deployment, live at https://allerguard-ai-5lim.onrender.com.

Partner Categories ($100)

Best Use of Sentry Agent Tracing: Complete agent observability with custom Sentry spans instrumenting TabPFN classification, SerpApi searches, Gemma 2 reasoning, and ElevenLabs speech generation.
Best Use of SerpApi: Live web grounding tool searching active FDA allergen recalls, brand cross-contamination alerts, and purity protocol disclosures in real time.
Best Use of ElevenLabs: Hands-free voice accessibility tool generating speech audio safety briefings for on-the-go shopping and cooking.

Built with ❤️ to keep friends, family, and loved ones safe around the dinner table.

Acuity Health: Part 2 - Zero Trust DevSecOps & NIST SSDF

hlldvr — Sun, 04 Oct 2026 22:42:06 +0000

When engineering teams scale distributed cloud services in highly regulated sectors like healthcare, traditional perimeter defense completely collapses. Developers need rapid access to packages, continuous integration, and staging environments, while security leads must guarantee that electronic Protected Health Information (ePHI) is never exposed to unhardened code or compromised dependencies.

For lean engineering teams, the solution is not heavy manual gatekeeping. Instead, security must be built directly into the development infrastructure through Zero Trust Architecture (ZTA) and the NIST Secure Software Development Framework (SP 800-218 v1.1).

In this second installment of our Acuity Health Security Architecture series, we break down how to architect isolated development landing zones, enforce ephemeral build pipelines, and secure the software supply chain.

The Zero Trust Engineering Plane

Zero Trust principles (Never Trust, Always Verify; Assume Breach; Least Privilege) must apply to developer workstations and build infrastructure just as rigorously as production databases.

In a traditional setup, developer environments frequently share network routes with staging or internal database replicas. If a developer workstation is compromised via phishing or an untrusted package, attackers can pivot laterally into core clinical networks.

flowchart LR
    subgraph Untrusted ["Untrusted Internet & Public Registries"]
        PublicNPM["Public npm / NuGet"]
        Malicious["Compromised Dependency / Typosquat"]
    end

 subgraph DevPlane ["Isolated Dev Plane (Azure DevTest Labs)"] Workstation["Dev Workstation (MFA + Conditional Access)"] ArtProxy["Artifact Firewall & Cache (SCA Pre-Scan)"] end

 subgraph CIPlane ["Ephemeral CI/CD Plane"] Runner["Dynamic Ephemeral Agent (Runs in isolated vNet)"] Signing["Cryptographic Artifact Signing"] end

 subgraph ProdDMZ ["Production DMZ & Ingress"] APIGW["API Gateway (Policy Enforcement Point)"] AKS["Azure Kubernetes Service (Production)"] end

 PublicNPM -->|Filtered via HTTPS| ArtProxy Malicious -.->|Blocked by SCA Gate| ArtProxy ArtProxy --> Runner Workstation -->|Commit / PR| Runner Runner --> Signing Signing --> APIGW APIGW --> AKS ```



### Architectural Controls in Practice

1. **Logical Network Segmentation**:
   Development infrastructure is hosted in dedicated **Azure DevTest Labs** isolated behind Network Security Groups (NSGs). Development subnets have zero routing paths to production Electronic Medical Record (EMR) databases or production telemetry.
2. **API Gateways as Policy Enforcement Points (PEPs)**:
   All inbound and outbound traffic between internal tiers passes through API Gateways located within a Demilitarized Zone (DMZ). Traffic is authenticated via mutual TLS (mTLS) and scoped using granular Role-Based Access Control (RBAC).

3. **Ephemeral Build Runners**:
   Build agents are stateless and single-use. They spin up inside isolated containers for the duration of a single commit job, execute pre-build linters and scans, compile the artifact, sign it cryptographically, and immediately terminate. No persistent credentials or artifacts reside on the runner.

---

## Operationalizing NIST SP 800-218 (SSDF v1.1)

The NIST Secure Software Development Framework organizes AppSec into four outcome-based pillars. Here is how lean teams translate those requirements into daily engineering workflows:

| SSDF Core Pillar | Operational Objectives | Daily Engineering Practices |
| :--- | :--- | :--- |
| **1. Prepare the Organization (PO)** | Cultivate institutional security ownership | • AppSec Champions embedded directly in feature squads<br>• Stack-specific OWASP Top 10 & API training |
| **2. Protect the Software (PS)** | Safeguard pipeline integrity & supply chain | • Ephemeral, single-use CI/CD runner environments<br>• Cryptographic artifact signing (Cosign / Azure Managed HSM)<br>• Automated Software Bill of Materials (SBOM via CycloneDX) |
| **3. Produce Well-Secured Software (PW)** | Eliminate vulnerabilities prior to production | • 15-minute mini-STRIDE threat modeling in backlog grooming<br>• Standardized internal crypto SDKs (AES-256-GCM, TLS 1.3)<br>• Context-aware authorization logic at the database layer |
| **4. Respond to Vulnerabilities (RV)** | Rapid containment and continuous feedback | • Formal RFC 9116 Vulnerability Disclosure Program (VDP)<br>• Enforced 48-hour Critical CVE remediation SLAs<br>• Post-incident root-cause hotwashes feeding backlog items |

### 1. Prepare the Organization (PO)
- **Security Champions**: Appoint one lead engineer in each development squad to act as the primary security liaison. Champions review pull requests for security edge-cases and participate in monthly threat intelligence briefings.
- **Contextual Training**: Move beyond generic compliance videos. Developers receive hands-on training tailored to their stack, specifically targeting OWASP Top 10 and API-specific vulnerabilities like Broken Object Level Authorization (BOLA).

### 2. Protect the Software (PS)
- **Cryptographic Signing**: Every compiled binary or container image is signed using keys stored in an isolated Hardware Security Module (Azure Key Vault Managed HSM) via Cosign/Notary.
- **Software Bill of Materials (SBOM)**: Every CI build automatically outputs a machine-readable SBOM in SPDX or CycloneDX format, cataloging every direct and transitive dependency.

### 3. Produce Well-Secured Software (PW)
- **Approved Cryptographic Libraries**: Developers are prohibited from implementing custom cryptography or ad-hoc authentication routines. Applications must consume hardened internal SDKs enforcing AES-256-GCM at rest and TLS 1.3 in transit.
- **Automated Pre-Commit Linters**: Linting rules catch unparameterized database queries, weak entropy sources, and hardcoded API secrets before code leaves the developer's IDE.

### 4. Respond to Vulnerabilities (RV)
- **Vulnerability Disclosure Policy (VDP)**: A clear `security.txt` and disclosure channel enables external ethical researchers to submit vulnerability reports safely.
- **Strict Remediation SLAs**:
  - **Critical (CVSS 9.0–10.0)**: Remediate and deploy within **48 hours**.
  - **High (CVSS 7.0–8.9)**: Remediate within **14 days**.
  - **Medium/Low**: Scheduled into the next sprint cycle (30-day window).

---

## Hardening the Software Supply Chain

Modern applications are rarely built from scratch; 80% to 90% of a typical cloud service consists of third-party open-source packages. A supply chain attack that compromises an upstream npm or NuGet library can bypass traditional perimeter firewalls entirely.



```mermaid
sequenceDiagram
    autonumber
    actor Dev as Developer Workstation
    participant Art as Artifact Proxy (Nexus/Artifactory)
    participant SCA as SCA Engine (Trivy/Snyk)
    participant Reg as Upstream Registry (npm/NuGet)
    participant Runner as Ephemeral CI Runner

 Dev->>Art: Request Package: express@4.19.2 alt Package Cached & Clean Art-->>Dev: Return Cached Package else Package Not Cached Art->>Reg: Fetch Upstream Package Reg-->>Art: Stream Package Tarball Art->>SCA: Trigger Automated Vulnerability & Malware Scan alt Vulnerability Found (Critical CVE / Malicious) SCA-->>Art: Quarantine Flag Art-->>Dev: 403 Forbidden: Package Blocked by Security Policy else Package Clean SCA-->>Art: Scan Passed (Signed) Art-->>Dev: Deliver Package end end Dev->>Runner: Submit Code Commit with Lockfile Runner->>Art: Fetch Verified Packages from Cache Runner->>Runner: Generate CycloneDX SBOM & Sign Container ```



### Supply Chain Enforcement Rules

1. **Proxy-Restricted Outbound Egress**:
   Direct internet access to public package registries (`npmjs.org`, `nuget.org`, `pypi.org`) is blocked across all developer endpoints and CI runners. All dependency requests are routed through a managed artifact proxy.

2. **Automated Quarantine on Ingestion**:
   When a new dependency is requested, the artifact proxy runs an automated Software Composition Analysis (SCA) scan against the National Vulnerability Database (NVD) and commercial threat feeds. Any package containing known vulnerabilities with CVSS scores $\ge 7.0$ or suspicious heuristics (e.g., install scripts running base64-decoded network sockets) is immediately quarantined.

3. **Deterministic Dependency Pinning**:
   Pipelines mandate strict lockfiles (`package-lock.json`, `packages.lock.json`, `Pipfile.lock`). Dynamic semantic version ranges (e.g., `^1.2.0` or `*`) are blocked by CI linters to prevent silent, uncontrolled upstream updates.

---

## Implementation Checklist: Part 1

Use this checklist to benchmark your development infrastructure against Zero Trust and NIST SSDF standards:

- [ ] **Infrastructure**: Development workloads run in isolated virtual networks with zero routable pathways to production data stores.
- [ ] **Access Control**: Source control repositories enforce mandatory MFA and conditional access based on device health.
- [ ] **Pipeline Isolation**: CI runners are 100% ephemeral, dynamically provisioned, and destroyed after each job.
- [ ] **Supply Chain**: Outbound package downloads route through an artifact caching proxy with automated SCA quarantine gates.
- [ ] **Artifact Integrity**: Build outputs generate automated SBOMs (CycloneDX/SPDX) and are cryptographically signed before container registry push.

---

> [!TIP]
> **Open-Source Reference Implementation**: Looking for a working reference implementation of ephemeral quality gates, Gitleaks secret detection, and decoupled static publication pipelines? Explore [`SixFiveMil/hugo-devsecops-starter`](https://github.com/SixFiveMil/hugo-devsecops-starter) on GitHub.

---

## Up Next in the Series

In **Part 3: Threat Modeling at Sprint Velocity: STRIDE Gates and BOLA Defenses** (releasing **Tuesday, September 22**), we move from infrastructure to application architecture: - How to run lightweight **15-minute mini-STRIDE** sessions during Agile backlog grooming. - Mapping Data Flow Diagrams (DFDs) across clinical trust boundaries. - Concrete code patterns to eliminate **OWASP API1: Broken Object Level Authorization (BOLA)** using cryptographically secure UUIDs and data-layer authorization context checks.

Working Backwards from Error Logs: Reverse Engineering the Tableau-to-Fabric OAuth Breakdown

hlldvr — Sun, 04 Oct 2026 22:42:05 +0000

🛑 The Crime Scene: A Misleading Desktop Failure

When modern lakehouse architectures meet desktop analytics clients, authentication breakdowns rarely announce their true root cause. Instead, engineers are handed generic hex codes and deceptive UI prompts.

During an enterprise deployment of Microsoft Fabric Warehouse, data analysts attempted to connect Tableau Desktop (2024.2.0) to the Fabric SQL/TDS endpoint (*.datawarehouse.fabric.microsoft.com) using the native Azure SQL Database connector and Microsoft Entra ID modern authentication.

Instead of opening the workspace schema and Delta tables, Tableau abruptly halted:

An error occurred while communicating with Azure SQL Database
Authentication failed.
Error Code: 84223ADA
User authorization failed (invalid_client)

flowchart LR
    A["Tableau Desktop<br/>(Client UI)"] -->|"Azure SQL Connector<br/>OAuth Request"| B["Microsoft Entra ID<br/>(IDP)"]
    B --x|"Token Issuance Aborted"| A

Why the Client UI Is a Trap

In the OAuth 2.0 RFC 6749 specification, invalid_client typically indicates an unregistered client_id, a secret mismatch, or an unapproved redirect URI. In a traditional SaaS integration, an administrator might waste hours cycling client credentials or rebuilding app registrations.

However, in this environment:

Interactive Delegated Auth: The connection relied on interactive user login, meaning client secret mismatches were completely irrelevant.
Pre-TDS Failure: The connection aborted during token acquisition before TCP/TDS traffic ever reached the Microsoft Fabric endpoint. Workspace roles and Fabric access control policies hadn't even been evaluated.

To find the true root cause, we have to stop troubleshooting the client UI and pivot directly into the Identity Provider's telemetry stream.

🔍 Forensic Phase 1: Correlating Client Telemetry with Entra ID Logs

When a desktop client throws an ambiguous error, the authoritative source of truth is the Microsoft Entra ID SigninLogs stream.

Using Kusto Query Language (KQL) in Microsoft Sentinel / Azure Log Analytics, we correlate the exact timestamp of the failed connection attempt against the Tableau Desktop multi-tenant Application ID:

// Query 1: Trace the exact failure timestamp and correlation ID
let TargetUser = "analyst@organization.example";
let TableauAppId = "0464ea90-c12f-42a7-b347-c2311ca4413c"; // Public Tableau Desktop App ID

SigninLogs
| where TimeGenerated > ago(24h)
| where UserPrincipalName =~ TargetUser and AppId == TableauAppId
| project 
    TimeGenerated, 
    CorrelationId, 
    AppDisplayName, 
    AppId, 
    ResourceDisplayName, 
    ResourceServicePrincipalId, 
    ResultType, 
    ResultDescription, 
    ConditionalAccessStatus
| order by TimeGenerated desc

The Telemetry: The Real Dependency Surfaces

The KQL query reveals the exact reason the token issuance failed:

Telemetry Field	Raw Log Value
AppDisplayName	`Tableau Desktop`
AppId	`0464ea90-c12f-42a7-b347-c2311ca4413c`
ResultType	`650052` (`AADSTS650052`)
ResultDescription	The app needs access to a service (`e9f49c6b-5ce5-44c8-925d-015017e9f7ad`) that isn't installed in your tenant.
CorrelationId	`a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d`

The invalid_client error was a red herring. The identity provider refused to issue tokens because the tenant directory was missing a required first-party service principal: e9f49c6b-5ce5-44c8-925d-015017e9f7ad.

🧩 Reverse Engineering the Undocumented OAuth Handshake

What is Application ID e9f49c6b-5ce5-44c8-925d-015017e9f7ad?

Querying the global Microsoft application catalog identifies this GUID as the first-party Azure Data Lake / Azure Storage enterprise application.

The Lakehouse Duality: Why Does TDS Require Azure Data Lake?

To understand why Tableau requested an Azure Data Lake token during an Azure SQL connection, we must examine how Microsoft Fabric decouples storage from compute:

sequenceDiagram
    autonumber
    actor User as BI Analyst
    participant Tableau as Tableau Desktop (2024.2.0)
    participant Entra as Microsoft Entra ID
    participant Fabric as Fabric SQL Endpoint (TDS)

    User->>Tableau: Initiate Fabric Warehouse Connection
    Tableau->>Entra: Parallel Token Request:<br/>1. Azure SQL Database (022907d3...)<br/>2. Azure Data Lake (e9f49c6b...)
    Note over Entra: Check local tenant directory for Service Principals
    Entra-->>Tableau: HTTP 400: AADSTS650052 (Azure Data Lake SP Missing)
    Tableau-->>User: Error 84223ADA: User authorization failed (invalid_client)

The SQL/TDS Gateway: Microsoft Fabric exposes a TDS interface (port 1433) that mimics Azure SQL Database.
OneLake Underlying Storage: The underlying data is stored as Delta Parquet files in OneLake (built on Azure Data Lake Storage Gen2).
The Multi-Resource OAuth Profile: Tableau Desktop’s native driver architecture requests dual-resource delegated scopes during modern authentication—acquiring authorization for both the Azure SQL endpoint and the underlying storage subsystem simultaneously.

Because the target Entra ID tenant had never instantiated the Azure Data Lake enterprise application service principal, Entra ID aborted the OAuth handshake immediately.

⚡ Forensic Phase 2: Controlled Remediation & The "Progress Error"

With the missing resource identified, we instantiate the first-party Microsoft service principal using Microsoft Graph PowerShell:

# Instantiate the missing first-party Azure Data Lake Service Principal
Connect-MgGraph -Scopes "Application.ReadWrite.All" -NoWelcome

$AzureDataLakeAppId = "e9f49c6b-5ce5-44c8-925d-015017e9f7ad"
$ExistingSP = Get-MgServicePrincipal -Filter "appId eq '$AzureDataLakeAppId'"

if (-not $ExistingSP) {
    New-MgServicePrincipal -AppId $AzureDataLakeAppId
    Write-Host "Instantiated Azure Data Lake Service Principal successfully." -ForegroundColor Green
} else {
    Write-Host "Service Principal already present." -ForegroundColor Yellow
}

Disconnect-MgGraph

The Second Error: Why Error Progression Equals Success

The analyst re-attempts the connection in Tableau Desktop. Once again, an error dialog appears. However, inspecting the fresh Entra ID sign-in log reveals an entirely different code:

SigninLogs
| where TimeGenerated > ago(1h)
| where UserPrincipalName =~ TargetUser and AppId == TableauAppId
| project TimeGenerated, AppDisplayName, ResultType, ResultDescription
| order by TimeGenerated desc

ResultType	ResultDescription
`90095` (`AADSTS90095`)	Admin consent is required for the requested permissions on Tableau Desktop.

[!TIP]
The Identity Forensics Rule: In distributed identity troubleshooting, a new error code is definitive proof of forward progress.

650052: The identity provider could not locate the required resource definition.

90095: The resource was successfully resolved, and execution successfully advanced to the tenant's admin consent and authorization policy evaluation.

stateDiagram-v2
    [*] --> Phase1: Connect Attempt
    Phase1 --> Phase2: Instantiate Azure Data Lake SP
    Phase2 --> Phase3: Admin Consent Review
    Phase3 --> Success: ResultType 0 (TDS Connected)

    state Phase1 {
        Tableau_84223ADA --> Entra_650052 : Missing Service Principal
    }
    state Phase2 {
        Entra_90095 : Admin Consent Gateway Triggered
    }
    state Phase3 {
        Entra_Consent : Delegated Scope Granted
    }
    state Success {
        Connected : Authenticated & Fabric RBAC Evaluated
    }

Once a tenant administrator reviews the generated consent request and grants delegated permissions for the Tableau Desktop application, Entra ID issues the access tokens. The connection succeeds with ResultType: 0.

🛡️ Engineering the Defensible DevSecOps Runbook

Ad-hoc fixes in the cloud console solve single incidents, but enterprise environments demand automated, hardened, and repeatable runbooks.

Unchecked administrative scripting introduces real operational risks:

Elevated Session Leakage: Leaving interactive write scopes (Application.ReadWrite.All) open in developer shells.
Cross-Tenant Misconfiguration: Accidentally executing modifications against the wrong tenant in multi-tenant MSP or hybrid environments.
CSV Formula Injection (CWE-1236): Unsanitized log exports containing spreadsheet command triggers (=, +, -, @) that can execute arbitrary payloads when opened by audit teams in Microsoft Excel.

Hardened Remediation and Audit Script

The following script encapsulates our reverse-engineered resolution with strict defensive boundaries:

<#
.SYNOPSIS
    Hardened diagnostic and remediation script for Tableau-to-Fabric OAuth dependencies.
.DESCRIPTION
    Validates tenant context, inventories service principals, applies JIT remediation,
    and exports formula-injection-safe evidence.
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [string]$ExpectedTenantId,

    [Parameter(Mandatory = $true)]
    [string]$EvidenceOutputPath
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

$TableauAppId       = '0464ea90-c12f-42a7-b347-c2311ca4413c'
$AzureDataLakeAppId = 'e9f49c6b-5ce5-44c8-925d-015017e9f7ad'

# 1. Read-Only Pre-flight & Tenant Boundary Check
Write-Host "[1/4] Connecting to Microsoft Graph (Read-Only)..." -ForegroundColor Cyan
Disconnect-MgGraph -ErrorAction SilentlyContinue
Connect-MgGraph -Scopes 'Application.Read.All' -NoWelcome

$Context = Get-MgContext
if (-not $Context -or $Context.TenantId -ne $ExpectedTenantId) {
    Disconnect-MgGraph -ErrorAction SilentlyContinue
    throw "Security Guardrail: Connected Tenant ID does not match expected target ($ExpectedTenantId). Aborting."
}

# 2. Inventory Required Service Principals
$Targets = @(
    @{ Name = 'Tableau Desktop'; AppId = $TableauAppId },
    @{ Name = 'Azure Data Lake'; AppId = $AzureDataLakeAppId }
)

$Inventory = foreach ($Target in $Targets) {
    $Sp = Get-MgServicePrincipal -Filter "appId eq '$($Target.AppId)'" -ErrorAction SilentlyContinue
    [pscustomobject]@{
        Name           = $Target.Name
        AppId          = $Target.AppId
        ExistsInTenant = ($null -ne $Sp)
        ObjectId       = $Sp.Id
        AccountEnabled = $Sp.AccountEnabled
    }
}
$Inventory | Format-Table -AutoSize
Disconnect-MgGraph

# 3. Privileged Remediation (JIT Session with Guaranteed Teardown)
$NeedsDataLakeSp = ($Inventory | Where-Object { $_.AppId -eq $AzureDataLakeAppId -and -not $_.ExistsInTenant })

if ($NeedsDataLakeSp) {
    Write-Host "[2/4] Instantiating missing Azure Data Lake Service Principal..." -ForegroundColor Yellow
    Connect-MgGraph -Scopes 'Application.ReadWrite.All' -NoWelcome
    try {
        $CurrentContext = Get-MgContext
        if ($CurrentContext.TenantId -ne $ExpectedTenantId) {
            throw "Tenant mismatch during privileged session."
        }
        $CreatedSp = New-MgServicePrincipal -AppId $AzureDataLakeAppId -ErrorAction Stop
        Write-Host "Created SP successfully: ObjectId $($CreatedSp.Id)" -ForegroundColor Green
    }
    finally {
        Write-Host "[3/4] Tearing down privileged Graph session..." -ForegroundColor Cyan
        Disconnect-MgGraph -ErrorAction SilentlyContinue
    }
} else {
    Write-Host "[2/4] Azure Data Lake SP already present. No write action needed." -ForegroundColor Green
}

# 4. Safe Evidence Packaging (Formula Injection Defense - CWE-1236)
function ConvertTo-SafeSpreadsheetText {
    param([AllowNull()][object]$Value)
    if ($null -eq $Value) { return $null }
    $Text = [string]$Value
    if ($Text -match '^[=+@-]') { return "'$Text" }
    return $Text
}

Write-Host "[4/4] Generating sanitized audit evidence..." -ForegroundColor Cyan
if (-not (Test-Path -LiteralPath $EvidenceOutputPath -PathType Container)) {
    New-Item -ItemType Directory -LiteralPath $EvidenceOutputPath -Force | Out-Null
}

$SanitizedInventory = $Inventory | ForEach-Object {
    [pscustomobject]@{
        Name           = ConvertTo-SafeSpreadsheetText $_.Name
        AppId          = ConvertTo-SafeSpreadsheetText $_.AppId
        ExistsInTenant = $_.ExistsInTenant
        ObjectId       = ConvertTo-SafeSpreadsheetText $_.ObjectId
    }
}

$CsvPath = Join-Path $EvidenceOutputPath 'Tableau-Fabric-SP-Inventory.csv'
$SanitizedInventory | Export-Csv -LiteralPath $CsvPath -NoTypeInformation -Encoding UTF8

# Cryptographic Evidence Seal
Get-ChildItem -LiteralPath $EvidenceOutputPath -File | 
    Get-FileHash -Algorithm SHA256 | 
    Export-Csv -LiteralPath (Join-Path $EvidenceOutputPath 'SHA256SUMS.csv') -NoTypeInformation -Encoding UTF8

Write-Host "Audit evidence cryptographically sealed at $EvidenceOutputPath" -ForegroundColor Green

📊 Non-Dropping KQL: Auditing Conditional Access Without Telemetry Gaps

When investigating authentication failures across managed and BYOD devices, many standard KQL queries use naive mv-expand on ConditionalAccessPolicies. If a sign-in event triggered no CA policies, or if device trust was missing, standard inner expansions drop those rows entirely from the audit report.

The following production query uses a left-outer expansion pattern to ensure every sign-in attempt is accounted for:

let BYODPolicyName = "Example BYOD Web Access Controls";
let BaseSignIns = materialize(
    SigninLogs
    | where TimeGenerated > ago(30d)
    | where AppId == "0464ea90-c12f-42a7-b347-c2311ca4413c" // Tableau Desktop
    | extend 
        TrustType = tostring(DeviceDetail.trustType),
        OS = tostring(DeviceDetail.operatingSystem),
        IsBrowser = (ClientAppUsed =~ "Browser")
    | project 
        TimeGenerated, 
        CorrelationId, 
        UserPrincipalName, 
        AppDisplayName, 
        ClientAppUsed, 
        IsBrowser, 
        TrustType, 
        OS, 
        ConditionalAccessPolicies, 
        ResultType
);

let PolicyResults = BaseSignIns
    | mv-expand kind=left CAPolicy = ConditionalAccessPolicies
    | extend CAName = tostring(CAPolicy.displayName), CAResult = tostring(CAPolicy.result)
    | where CAName == BYODPolicyName
    | summarize PolicyResult = strcat_array(make_set(CAResult), ",") by CorrelationId;

BaseSignIns
| project-away ConditionalAccessPolicies
| join kind=leftouter PolicyResults on CorrelationId
| extend 
    PolicyEnforced = isnotempty(PolicyResult),
    EffectiveResult = iff(isnotempty(PolicyResult), PolicyResult, "No matching policy entry")
| summarize TotalAttempts = count(), SuccessfulAuths = countif(ResultType == 0) 
    by UserPrincipalName, AppDisplayName, TrustType, EffectiveResult
| order by TotalAttempts desc

🎯 Key Takeaways for Identity & Data Engineers

Client Error Codes Mask Protocol Truth: A client-side invalid_client or 84223ADA error is merely an HTTP 400 wrapper. Always trace the session via CorrelationId in the Identity Provider's sign-in logs before modifying configurations.
Modern Lakehouses Abstract Storage, Not Identity: Even when connecting over a standard TDS/SQL gateway, modern analytics drivers frequently require explicit delegated token scopes for underlying storage resources (Azure Data Lake).
Embrace Error Progression: Moving from AADSTS650052 (missing resource) → AADSTS90095 (admin consent) → 0 (success) confirms that each identity layer was resolved systematically.
Build Defensible Runbooks: Separate read-only diagnostics from privileged writes, enforce programmatic tenant boundaries, and protect audit artifacts against spreadsheet injection.

Modernizing the Academic Knowledge Graph: Canvas Sync Bridge v0.4.0, Hybrid Ingestion, and Official Obsidian Compliance

hlldvr — Sun, 04 Oct 2026 22:42:04 +0000

🎓 The Academic Knowledge Management Dilemma

Modern higher education and enterprise training institutions rely almost universally on Learning Management Systems (LMS) like Instructure Canvas to distribute course syllabi, 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) systems 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 Graphs: 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: Traditional 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 Sync Bridge v0.4.0 (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 eliminate this friction while upholding strict privacy boundaries and supply-chain integrity, I architected and open-sourced Canvas Sync Bridge v0.4.0—a production-grade, hybrid local-first ecosystem split into two dedicated, decoupled open-source GitHub repositories and audited against official Obsidian Community guidelines.

📦 Architectural Decoupling: Two Repositories, Two Independent Lifecycles

A central engineering milestone of the v0.4.0 release is the clean decoupling of the codebase into two standalone, single-responsibility open-source repositories:

                                  ┌─────────────────────────────────────────────────────────┐
                                  │                CANVAS TO OBSIDIAN SUITE                 │
                                  └────────────────────────────┬────────────────────────────┘
                                                               │
                                ┌──────────────────────────────┴──────────────────────────────┐
                                │                                                             │
                                ▼                                                             ▼
┌───────────────────────────────────────────────────────────┐   ┌───────────────────────────────────────────────────────────┐
│              OBSIDIAN DESKTOP & MOBILE PLUGIN             │   │            COMPANION BROWSER WEBEXTENSION                 │
│      (https://github.com/SixFiveMil/obsidian-canvas-sync) │   │ (https://github.com/SixFiveMil/canvas-to-obsidian-extension)│
├───────────────────────────────────────────────────────────┤   ├───────────────────────────────────────────────────────────┤
│ • Native Obsidian requestUrl Direct REST API Client       │   │ • Manifest V3 Service Worker (Chrome, Brave, Edge, Arc)   │
│ • Vault Note Synthesizer & GFM Markdown Converter         │   │ • WebExtensions API Packaging (Mozilla Firefox AMO)       │
│ • Obsidian Community Directory CI (obsidian-workflows)    │   │ • Zero-Token Session Extraction from active Canvas tabs   │
│ • Popout Window & Mobile Scoping (Platform.isDesktop)     │   │ • Automated Store Deployment Pipeline (publish-stores.mjs)│
│ • Cryptographically signed releases with SLSA Provenance  │   │ • Link-local Loopback HTTP Dispatch (127.0.0.1:27125)     │
└───────────────────────────────────────────────────────────┘   └───────────────────────────────────────────────────────────┘

Why Decouple into Separate Repositories?

Independent Release Lifecycles & Store Governance: The Obsidian plugin and browser extensions target completely different distribution registries with different review timelines. The plugin is submitted to the Obsidian Community Plugins Directory and BRAT, whereas the extension targets the Chrome Web Store and Firefox Add-ons (AMO). Decoupling ensures that a patch to the Chrome MV3 background worker doesn't trigger unnecessary plugin releases or invalidate Obsidian community reviewer hashes.
Targeted CI/CD & Validation Pipelines: The Obsidian plugin uses the official obsidianmd/obsidian-workflows action with eslint-plugin-obsidianmd and stylelint. The browser extension repository uses web-extension manifest validators, Chrome Web Store API deployers, and AMO signing scripts.
Zero Dependency Bloat: Users who rely exclusively on the Direct REST API within Obsidian can install the plugin without downloading any browser extension build artifacts, while extension contributors don't need Obsidian Desktop API dependencies.

🏛️ Hybrid Ingestion Architecture

The decoupled ecosystem supports two complementary ingestion pathways that converge into a unified canonical note generator:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                   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 MV3)    │
                             │                 │ - Session Extractor       │
                             │                 │ - Extraction Toggles      │
                             │                 └─────────────┬─────────────┘
                             │                               │ Loopback POST (127.0.0.1:27125)
                             │                               │ (Opt-in / Platform.isDesktop)
                             ▼                               ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                              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/CS510 - Network Security/                                                  │
│      ├── 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)                                                │
└────────────────────────────────────────────────────────────────────────────────────────┘

Ingestion Pathways Compared

Ingestion Mode	Repository / Component	Ingestion Mechanism	Best For	Platform Support
Mode A: Direct REST API	`obsidian-canvas-sync`	Native `requestUrl` adapter using personal Canvas API tokens	Standard users, automated multi-course batch syncing, historical term archiving	Obsidian Desktop & Mobile
Mode B: Companion Web Extension	`canvas-to-obsidian-extension`	Manifest V3 service worker extracting active tab session cookies	Locked-down universities where student API keys are disabled	Chrome, Firefox, Edge, Brave, Arc

🛡️ Obsidian Community Compliance & Guidelines Hardening

To ensure enterprise-grade stability and prepare for official listing in the Obsidian Community Plugins directory, the plugin was audited and re-engineered against the complete suite of Obsidian developer guidelines:

1. Official CI/CD Validation Workflows

The plugin repository integrates the official obsidianmd/obsidian-workflows GitHub Action on all pull requests and tagged releases. Every commit is validated against:

eslint-plugin-obsidianmd: Enforcing plugin lifecycle contracts and DOM safety.
stylelint: Ensuring theme neutrality and valid CSS custom properties.
Dynamic guideline guard tests asserting zero forbidden global overrides.

2. Multi-Window Popout Safety

In modern Obsidian releases (v1.0+), notes and modals can be dragged into detached, popout operating system windows. The plugin eliminates legacy globalThis and root document references, binding event listeners and DOM elements dynamically to context-aware activeWindow and window scopes.

3. Declarative Settings Search (`getSettingDefinitions`)

Canvas Sync Bridge implements getSettingDefinitions(), allowing users on Obsidian 1.13+ to search and jump directly to specific plugin settings (e.g. Canvas Base URL, Bridge Port, Asset Filter Allowlist) from the global Obsidian settings filter.

4. Dynamic Desktop Isolation (`Platform.isDesktop`)

Node.js core modules (http, url, path) required for the local loopback server are dynamically resolved and guarded behind Platform.isDesktop. This guarantees that the plugin initializes cleanly on Obsidian Mobile (iOS and Android) in Direct REST API mode without throwing module resolution faults.

5. Supply Chain Security & SLSA Build Provenance

Every release artifact (main.js, manifest.json, styles.css) is cryptographically signed and attested using SLSA build provenance predicates via GitHub OIDC and Sigstore. Build pipelines strictly prune non-essential assets, ensuring transparent, tamper-proof releases.

📊 Comprehensive Coursework Synchronization

Both ingestion modes stream course data into a canonical payload schema (CanvasCoursePayload), producing complete, interconnected 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.

### 📊 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:

### 📋 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:

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)
- 📦 Extension Source Repo
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

Canvas Sync Bridge and its companion extension are distributed under the MIT License across two dedicated open-source repositories:

💎 Obsidian Plugin: SixFiveMil/obsidian-canvas-sync
🌐 Browser Extension: SixFiveMil/canvas-to-obsidian-extension

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