---
title: Boundary Interfaces & Trust Architecture
description: Analysis of inbound/outbound contracts, public extension points, and trust boundaries in VertiWiki.
tags: [vertiwiki, architecture, security, boundary-interfaces, contracts]
---

# Boundary Interfaces & Trust Architecture

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

This document establishes the trust boundaries, network ingress/egress points, and contract interfaces governing VertiWiki's client-side execution environment.

---

## 🚪 Inbound Interfaces (Ingress)

| Interface | Mechanism | Inbound Data | Trust Level | Sanitization Applied |
| :--- | :--- | :--- | :--- | :--- |
| **URL Hash Route** | `window.location.hash` | Target markdown file path and anchor (`#/guide.md#sec`) | Untrusted | `normalizePath()`, `slugify()`, whitelist check |
| **URL Query Parameters** | `window.location.search` | Legacy parameters (`?page=`, `?doc=`) | Untrusted | `normalizePath()`, redirection to hash route |
| **Markdown Documents** | HTTP `fetch()` | Markdown text, YAML frontmatter, raw HTML fragments | Untrusted | `DOMPurify.sanitize()`, `autoCloseFences()` |
| **Configuration** | HTTP `fetch('config.json')` | UI flags, layout modes, theme paths, analytics IDs | Semi-trusted | Defensive JSON parsing with fallback defaults |
| **Theme Presets** | HTTP `fetch('themes/*.json')` | Color values, font URLs, CSS declarations | Semi-trusted | Theme normalization and token sanitization |
| **User Search Query** | Modal Input (<kbd>⌘K</kbd>) | Text query string | Untrusted | Regex escaping, MiniSearch query tokenizer |
| **Embedded Iframes** | Markdown authoring | Third-party URLs, interactive presentations | Untrusted | Enforced sandbox with `allow-presentation`, omitted `allow-top-navigation` |

---

## 📤 Outbound Interfaces (Egress)

| Interface | Target | Payload | Trigger Condition |
| :--- | :--- | :--- | :--- |
| **Document Fetcher** | Web Server / CDN | HTTP GET for `.md` and `.json` assets | Route changes and initial bootstrapping |
| **Web Fonts** | Google Fonts / CDN | `@font-face` requests for typography | Custom theme presets specifying `fontUrl` |
| **Analytics Beacons** | Telemetry Providers (GA4, Plausible, Umami) | Pageview paths and screen resolutions | Hash route changes (only if provider ID is set) |
| **Local Storage API** | Browser `localStorage` | Theme preference, active mode (`dark`/`light`), tab states | User UI interactions |

---

## 🛡️ Trust Boundaries & Data Flow

```mermaid
flowchart TD
    subgraph Untrusted External Zone
        WebUser[Browser User / URL Hash]
        MarkdownFiles[Remote Markdown Files]
        ThemeFiles[External JSON Theme Files]
    end

    subgraph Trust Boundary 1: Ingress Sanitization
        RouterValidate[normalizePath & sanitizeUrl]
        PurifyFilter[Hardened DOMPurify Filter]
        ThemeNormalize[Theme Token Normalizer]
    end

    subgraph Trusted Internal Zone
        AppPipeline[Pipeline Middleware & State]
        SearchIndex[(MiniSearch In-Memory Index)]
        SafeDOM[(Rendered DOM inside #verti-app)]
    end

    WebUser --> RouterValidate
    MarkdownFiles --> PurifyFilter
    ThemeFiles --> ThemeNormalize

    RouterValidate --> AppPipeline
    PurifyFilter --> SafeDOM
    PurifyFilter --> SearchIndex
    ThemeNormalize --> SafeDOM
```

### Trust Boundary Invariants:
1. **Raw Markdown is Always Untrusted**: Even in internal company wikis, Markdown authors could inadvertently include malicious `<script>` tags or broken HTML. DOMPurify acts as an impassable gatekeeper between the Markdown parser and the browser DOM.
2. **Local Storage Isolation**: Keys written to `localStorage` (`vertiwiki_theme`, `vertiwiki_preset`) are validated against known preset IDs before being applied to the DOM.
3. **No Dynamic Code Evaluation**: VertiWiki strictly prohibits the use of `eval()` or `new Function()` in its core codebase and plugins.
4. **Iframe Isolation**: Third-party `<iframe>` tags are confined by default to `sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-presentation"`, explicitly omitting top-level window navigation.

---

## 🧩 Public Extension Contracts

Developers extending VertiWiki interact through the following TypeScript contracts:

### Plugin Contract (`src/core/pipeline.ts`)
```typescript
export interface VertiWikiPlugin {
  name: string;
  beforeParse?: (markdown: string, context: PluginContext) => Promise<string> | string;
  afterParse?: (html: string, context: PluginContext) => Promise<string> | string;
  afterRender?: (context: PluginContext) => Promise<void> | void;
}
```

### Theme Contract (`src/core/types.ts`)
```typescript
export interface ThemePreset {
  id: string;
  name: string;
  previewColor: string;
  fontUrl?: string;
  extends?: string;
  light: ThemeColors;
  dark: ThemeColors;
}
```