99 lines
5.9 KiB
Markdown
99 lines
5.9 KiB
Markdown
# Sanctum — Projekt-Kontext & Agenten-Leitfaden (AGENTS.md)
|
||
|
||
Dieses Dokument dient als primäres Projektgedächtnis für Antigravity-Agenten und Entwickler. Es verknüpft die historische Entwicklungshistorie, dokumentiert die Kernarchitektur, verweist auf alle Sicherheitsdokumente und definiert die verbindlichen Quality Gates.
|
||
|
||
---
|
||
|
||
## 1. Konversations-Referenz & Historie
|
||
|
||
Die gesamte Genese dieses Projekts (Audit-Behebung aller 39 Findings, Carrier V2 Paged Manifest, Disaster Recovery MAC-Fix R-NEW-1, Supply-Chain-Audits und Releases bis v0.9.3) ist in folgender Konversation protokolliert:
|
||
|
||
🔗 **[Sanctum Genese, Audit-Härtung & v0.9.3 Release-Konversation](conversation://f8a1e581-6556-4799-b012-fabcae853c09)**
|
||
*(ID: `f8a1e581-6556-4799-b012-fabcae853c09` — kann in Antigravity per Klick oder im Chat via `@Conversations` geladen werden).*
|
||
|
||
---
|
||
|
||
## 2. Projektüberblick & Kernarchitektur
|
||
|
||
**Sanctum** ist eine speichersichere, hochperformante Userland-CLI in Rust, die verschlüsselte Ein-Datei-Container (`.sanctum`) unter Windows 10/11 und Linux verwaltet — zu 100 % im Userland ohne Administratorrechte oder Kernel-Treiber (kein Dokan, kein WinFsp).
|
||
|
||
### 2.1 Kryptografische Säulen (Container-Format V3)
|
||
- **Format-Version**: Neue Container nutzen Format V3 (`format_version = 3`).
|
||
- **KDF**: Argon2id ($M=256\,\text{MiB}, T=4, P=4$, M-01) zur KEK-Ableitung mit CSPRNG-Salts (`OsRng`).
|
||
- **DEK & Wrapping**: 256-Bit DEK, gewrappt per AES-256-GCM.
|
||
- **Kanonische Metadaten-Authentifizierung (K-01)**:
|
||
- Inode-Metadaten werden mit einer HMAC-SHA-256 (`SANCTUM_META_MAC_V3`) authentifiziert.
|
||
- Validierung bei jedem `mount` (`verify_metadata_mac_status_for_slot`).
|
||
- Disaster-Recovery-Resilienz (R-NEW-1): Rebuild-Fähigkeit via `MetadataMacStatus::PendingRebuild` nach Header-Wiederherstellung.
|
||
- **Chunk-Replay-Schutz (K-02)**: 24-Byte AAD (`node_id || chunk_index || metadata_gen`).
|
||
- **Dateinamen-Verschlüsselung**: AES-256-GCM mit Bindung an `parent_id` als AAD (Swap-Schutz). Warnung bei `--legacy-names`.
|
||
|
||
### 2.2 Dual-Vault & Carrier-Format V2 (Paged Manifest)
|
||
- **2-Slot-Architektur**: Slot 0 als Decoy-Vault, Slot 1 als Second Safe (Hidden Vault Modell A).
|
||
- **Steganografie & Größeninvarianz**: Der Hidden Vault liegt innerhalb einer Alibi-Trägerdatei im Decoy-Vault. Versteckte Schreibvorgänge verändern die Host-Dateigröße um exakt 0 Bytes.
|
||
- **Paged Manifest V2**:
|
||
- Trennung von Superblock (redundant auf Block 0 und Block 1, rollierende `manifest_generation`, C-02) und Inode-Seiten (`CarrierInodePage`, ~1 MB Payload, ca. 4.500–7.000 Inodes/Seite).
|
||
- Keine starre Kapazitätsobergrenze mehr; dynamische Skalierung mit den Trägerblöcken.
|
||
- Fail-Soft Resilienz (D-01): Isolierung beschädigter Seiten ohne Mount-Abbruch.
|
||
- In-Memory Sekundärindex (D-02): $O(\text{Geschwister})$ Pfadauflösung.
|
||
- Manifest-Entkopplung via Dirty-Tracking (C-03): Schnelle I/O-Operationen ohne synchrone 1-MB-Manifest-Neuverschlüsselung.
|
||
|
||
### 2.3 OpSec, Anti-Leak & Disaster Recovery
|
||
- **Anti-Leak Shield**: Blockiert Explorer-Artefakte (`Thumbs.db`, `desktop.ini`, `*.tmp`, NTFS ADS `:Zone.Identifier`).
|
||
- **Memory Security**: `Zeroize` für alle Schlüssel und Passwörter; `VirtualLock` / `mlock` gegen Swap-Auslagerung.
|
||
- **Transaktionales Chunk-Shredding**: Logisches Überschreiben von Chunks mit CSPRNG-Rauschen vor dem Löschen.
|
||
- **Disaster Recovery**: 24-Wort BIP-39 Notfallschlüssel pro Slot, Online-Backups via SQLite Online Backup API.
|
||
|
||
---
|
||
|
||
## 3. Zentrale Dokumentation im Repository
|
||
|
||
| Dokument | Zweck / Inhalt |
|
||
|---|---|
|
||
| [`README.md`](README.md) | Hauptdokumentation, Feature-Übersicht, CLI-Verwendung & V1→V2 Migrationsanleitung |
|
||
| [`SECURITY.md`](SECURITY.md) | Responsible Disclosure Policy, SLAs (48h/5d/90d), Scope, Meldekanal (`security@pansi.eu`) |
|
||
| [`SECURITY_AUDIT.md`](SECURITY_AUDIT.md) | Vollständiges Log aller 39 behobenen Audit-Findings + R-NEW-1 + Tool-Audits |
|
||
| [`THREAT_MODEL.md`](THREAT_MODEL.md) | Bedrohungsmodell, Angreiferprofile und Sicherheitsannahmen |
|
||
| [`RELEASE_PROCESS.md`](RELEASE_PROCESS.md) | Multi-Platform CI/CD Release-Architektur, Toolchain-Pins und Minisign-Signierung |
|
||
| [`QUICKSTART.md`](QUICKSTART.md) | Kompakte Schritt-für-Schritt-Anleitung für Endanwender |
|
||
| [`INSTALL.md`](INSTALL.md) | Installationsanweisungen (Binaries, Scoop, WinGet, Cargo) |
|
||
| [`CHANGELOG.md`](CHANGELOG.md) | Keep-a-Changelog Versionshistorie (aktuell: v0.9.3) |
|
||
| [`deny.toml`](deny.toml) | Strikte Konfiguration für `cargo-deny` (Advisories, Bans, Lizenzen, Quellen) |
|
||
| [`.gitea/workflows/release.yaml`](.gitea/workflows/release.yaml) | Automatisierte CI/CD Release-Pipeline für Windows & Linux musl |
|
||
|
||
---
|
||
|
||
## 4. Richtlinien für Agenten (Quality Gates)
|
||
|
||
Jede Code- oder Konfigurationsänderung **MUSS** vor einem Release oder Commit folgende Gates erfolgreich und ohne Warnungen durchlaufen:
|
||
|
||
1. **Formatierung**:
|
||
```powershell
|
||
cargo fmt --check
|
||
```
|
||
2. **Statische Code-Analyse (Linter)**:
|
||
```powershell
|
||
cargo clippy --all-targets -- -D warnings
|
||
```
|
||
3. **Vollständige Testsuite** (aktuell 136 Tests):
|
||
```powershell
|
||
cargo test --all
|
||
```
|
||
4. **Supply-Chain & Lizenz-Governance**:
|
||
```powershell
|
||
cargo-deny check
|
||
```
|
||
5. **Secret-Leak-Prävention**:
|
||
```powershell
|
||
gitleaks detect --verbose
|
||
```
|
||
*(Erlaubte Test-Mocks in `.gitleaksignore` pflegen).*
|
||
|
||
---
|
||
|
||
## 5. Coding-Konventionen
|
||
- **Keine Panics im Produktivcode**: Verwende `anyhow::Result`, `context(...)` oder `bail!` anstelle von `.unwrap()` oder `.expect()`.
|
||
- **Pfad- und Knotennamens-Sicherheit**: Alle neuen Dateinamen-Operationen müssen `validate_node_name` / `validate_path_safety` durchlaufen (Abweisung von Windows-Reservierungen wie `CON`, `PRN`, ungültigen Zeichen `<>:"/\|?*` und Steuerzeichen).
|
||
- **Speichersicherheit**: Alle sensiblen Schlüsselstrukturen müssen `Zeroize` implementieren und mit `Zeroizing<T>` gewrappt werden.
|
||
- **PowerShell-Syntax**: Befehle in PowerShell mit `;` verketten (nicht `&&`). Keine `cd`-Befehle verwenden.
|