Skip to content

Latest commit

 

History

History
24 lines (19 loc) · 2.52 KB

SUBSTRATE_SPEC.md

File metadata and controls

24 lines (19 loc) · 2.52 KB

CodeSearchGitSecure: Substrate Specification

This document defines the strict, non-negotiable structural invariants for the V1 build.

1. Level 0: Granular Git Object Encryption

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 --batch and receive standard plaintext streams without awareness of the underlying cryptography.
  • Zero-Leakage Constraint: Standard Git smudge/clean filters that materialize plaintext to the host filesystem are strictly prohibited. Decrypted streams must be piped directly into volatile memory.

2. Level 1: Volatile Execution (Zoekt)

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 ramfs mounts.
  • 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.

3. Cryptographic Key Lifecycle

  • 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 mlockall requirement. It is hostile to Go's runtime and Zoekt's mmap architecture, 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.