---
title: Interfețe de Limită & Arhitectura de Încredere
description: Analiză a contractelor de intrare/ieșire, a punctelor publice de extensie și a granițelor de securitate în VertiWiki.
tags: [vertiwiki, arhitectura, securitate, interfete-limita, contracte, romana]
---

# Interfețe de Limită & Arhitectura de Încredere

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

Acest document stabilește granițele de securitate, punctele de intrare/ieșire din rețea și contractele de interfață care guvernează mediul de execuție pe partea de client al VertiWiki.

---

## 🚪 Interfețe de Intrare (Ingress)

| Interfață | Mecanism | Date Primite | Nivel de Încredere | Igienizare Aplicată |
| :--- | :--- | :--- | :--- | :--- |
| **Rută Hash URL** | `window.location.hash` | Calea către fișierul Markdown și ancoră (`#/ghid.md#sec`) | Neîncredere | `normalizePath()`, `slugify()` |
| **Parametri Query URL**| `window.location.search` | Parametri legacy (`?page=`, `?doc=`) | Neîncredere | `normalizePath()`, redirectare |
| **Documente Markdown** | HTTP `fetch()` | Text Markdown, YAML frontmatter, fragmente HTML | Neîncredere | `DOMPurify.sanitize()`, `autoCloseFences()` |
| **Configurație** | HTTP `fetch('config.json')`| Opțiuni UI, moduri layout, teme, ID-uri analitice | Semi-încredere | Parsare defensivă JSON cu valori de rezervă |
| **Fișiere Teme** | HTTP `fetch('themes/*.json')` | Valori culori, URL fonturi, reguli CSS | Semi-încredere | Normalizare teme și validare token-uri |
| **Interogare Căutare** | Fereastră Modală (<kbd>⌘K</kbd>)| Șir text de căutare | Neîncredere | Evadare regex, tokenizare MiniSearch |
| **Frame-uri Iframe Încorporate** | Redactare Markdown | URL-uri terțe, prezentări interactive | Neîncredere | Sandbox impus cu `allow-presentation`, fără `allow-top-navigation` |

---

## 📤 Interfețe de Ieșire (Egress)

| Interfață | Țintă | Date Transmise | Condiție Declanșare |
| :--- | :--- | :--- | :--- |
| **Preluare Resurse** | Server Web / CDN | Cereri HTTP GET pentru `.md` și `.json` | Schimbare de rută și inițializare |
| **Fonturi Web** | Google Fonts / CDN | Cereri `@font-face` pentru tipografie | Teme ce specifică `fontUrl` |
| **Telemetrie** | Servicii Analitice (GA4, Plausible) | Căi vizitate și rezoluții ecran | Schimbare de rută (doar dacă ID-ul e setat) |
| **Stocare Locală** | `localStorage` din browser | Preferință mod temă (`dark`/`light`), tab-uri active | Interacțiuni utilizator în UI |

---

## 🛡️ Granițe de Securitate & Fluxul Datelor

```mermaid
flowchart TD
    subgraph Zona Externa Fara Incredere
        WebUser[Utilizator Browser / Hash URL]
        MarkdownFiles[Fișiere Markdown la Distanță]
        ThemeFiles[Fișiere Teme Externe JSON]
    end

    subgraph Granita 1: Igienizare la Intrare
        RouterValidate[normalizePath & sanitizeUrl]
        PurifyFilter[Filtru Strict DOMPurify]
        ThemeNormalize[Normalizator Token-uri Teme]
    end

    subgraph Zona Interna de Incredere
        AppPipeline[Middleware Pipeline & Stare]
        SearchIndex[(Index MiniSearch în Memorie)]
        SafeDOM[(DOM Randat în #verti-app)]
    end

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

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

### Invarianți de Securitate:
1. **Markdown-ul Brut este Mereu Nesigur**: DOMPurify acționează ca o barieră de netrecut între parserul Markdown și DOM-ul browserului.
2. **Izolarea Datelor Locale**: Valorile citite din `localStorage` sunt validate împotriva listei de teme cunoscute înainte de a fi aplicate.
3. **Fără Evaluare Dinamică de Cod**: Utilizarea `eval()` sau `new Function()` este strict interzisă în întregul cod sursă VertiWiki.
4. **Izolarea Iframe-urilor**: Etichetele `<iframe>` terțe sunt constrânse implicit la `sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-presentation"`, omițând explicit navigarea la nivel de fereastră superioară.

---

## 🧩 Contracte Publice de Extindere

### Contractul de Plugin (`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;
}
```

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