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
(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`	Hauptdokumentation, Feature-Übersicht, CLI-Verwendung & V1→V2 Migrationsanleitung
`SECURITY.md`	Responsible Disclosure Policy, SLAs (48h/5d/90d), Scope, Meldekanal (`security@pansi.eu`)
`SECURITY_AUDIT.md`	Vollständiges Log aller 39 behobenen Audit-Findings + R-NEW-1 + Tool-Audits
`THREAT_MODEL.md`	Bedrohungsmodell, Angreiferprofile und Sicherheitsannahmen
`RELEASE_PROCESS.md`	Multi-Platform CI/CD Release-Architektur, Toolchain-Pins und Minisign-Signierung
`QUICKSTART.md`	Kompakte Schritt-für-Schritt-Anleitung für Endanwender
`INSTALL.md`	Installationsanweisungen (Binaries, Scoop, WinGet, Cargo)
`CHANGELOG.md`	Keep-a-Changelog Versionshistorie (aktuell: v0.9.3)
`deny.toml`	Strikte Konfiguration für `cargo-deny` (Advisories, Bans, Lizenzen, Quellen)
`.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:

Formatierung:
```
cargo fmt --check
```

Statische Code-Analyse (Linter):

cargo clippy --all-targets -- -D warnings

Vollständige Testsuite (aktuell 136 Tests):
```
cargo test --all
```
Supply-Chain & Lizenz-Governance:
```
cargo-deny check
```
Secret-Leak-Prävention:
```
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.

5.9 KiB Raw Blame History Unescape Escape