This document defines the strict, non-negotiable structural invariants for the V1 build.
To support the sub-50ms indexing of multi-gigabyte repositories (including dynamic, heavy chat-log backups), encryption cannot be monolithic.
- Encrypted Envelopes: Git objects must be encrypted at the granular level (
encblob,enctree,enccommit) using authenticated AES-256-GCM. - Transparent Interception: Downstream indexing tools (Level 1) must be able to invoke
git cat-file --batchand receive standard plaintext streams without awareness of the underlying cryptography. - Zero-Leakage Constraint: Standard Git
smudge/cleanfilters that materialize plaintext to the host filesystem are strictly prohibited. Decrypted streams must be piped directly into volatile memory.
The search daemon must ensure that plaintext code and index shards never touch persistent storage.
- RAMFS Isolation: Decrypted shards and active key caches must reside strictly on non-swappable
ramfsmounts. - Memory Pinning: The search process must lock its entire address space into RAM via
mlockall(MCL_CURRENT | MCL_FUTURE)on startup to prevent kernel page-swap vulnerabilities. - Blind Indexing: Raw hexadecimal OIDs must be blinded (e.g., via
HMAC-SHA256) before entering the search index to prevent structural graph correlation.
- Cold Tier: Root master keys are maintained completely offline via physical air-gaps.
- Hot Tier: Ephemeral Data Encryption Keys (DEKs) are orchestrated via HashiCorp Vault Transit, enforcing automated daily rotation. Keys exist only within volatile memory and are aggressively zeroized upon process termination.
errata:
- LEVEL 0 (Smudge/Clean): Banning smudge filters is unnecessary and fragile. Instead, the substrate will rely on Kernel-level sandboxing: all Non-Volatile (NV) mounts must be Read-Only. Git operations can use standard smudge/clean filters, provided the target working tree is an ephemeral
ramfs/tmpfs. - LEVEL 1 (Memory Pinning): Remove
mlockallrequirement. It is hostile to Go's runtime and Zoekt'smmaparchitecture, leading to inevitable OOM crashes. Swapping will instead be disabled system-wide at the OS/cgroup level. - LEVEL 1 (Blind Indexing): Acknowledge that 1:1 HMAC-SHA256 blinding prevents simple public-OID correlation, but does not mask the underlying graph topology from frequency analysis.