Grove Security Model

Trust Model

Grove uses a peer-to-peer trust model — you explicitly choose who to connect with. There is no central authority.

• You control your data — encryption keys never leave your cell
• Peers store encrypted chunks — they can't read your files
• Friends can share — you choose who can send you files
• Relay operators are blind — messages are end-to-end encrypted

---

Encryption Summary

What	Algorithm	Key Size
File chunks	ChaCha20-Poly1305	256-bit
Key derivation	HKDF-SHA256	—
Chunk hashing	SHA-256	—
Cell identity	Ed25519	256-bit
Chat key exchange	X25519	256-bit
Chat messages	ChaCha20-Poly1305	256-bit
Password hashing	PBKDF2-SHA256	100k iterations
Peer secret comparison	HMAC (timing-safe)	—

---

Authentication

Dashboard

• Password hashed with PBKDF2 (100k iterations, random salt)
• Stored in ~/.grove/dashboard_auth as base64_salt:hex_hash
• Session cookies: HttpOnly, SameSite=Lax, 30-day expiry
• Brute-force protection: lockout after 6 failed attempts

Peer-to-Peer

• X-Grove-Secret header on all peer API calls
• Secret comparison uses hmac.compare_digest (prevents timing attacks)
• Each cell generates its own peer_secret on first run

Relay

• Ed25519 challenge-response authentication
• Only cells with known pubkeys can connect to relay

---

What Peers Can See

Data	Visible to Peers?
Your file contents	❌ No (encrypted chunks)
Your file names	❌ No (manifests only shared with friends via grants)
Your chunk hashes	✅ Yes (needed for deduplication)
Your cell's pubkey	✅ Yes (identity)
Your cell's name	✅ Yes (you choose what to share)
Your IP address	✅ Yes (needed to connect)
How much storage you use	✅ Yes (chunk count visible)
Chat messages	❌ No (end-to-end encrypted)

---

What Relay Operators Can See

Data	Visible?
Message contents	❌ No (E2E encrypted)
Who's connected	✅ Yes (pubkeys + IPs)
Message size/timing	✅ Yes (metadata)
Which cells communicate	✅ Yes (routing info)

---

Key Files & Permissions

All private key files should be chmod 600 (owner read/write only):

~/.grove/node.key          # Ed25519 private key — NEVER share
~/.grove/node_x25519.key   # X25519 private key — NEVER share
~/.grove/.key              # Master encryption key — NEVER share
~/.grove/peer_secret       # API auth secret — NEVER share
~/.grove/dashboard_auth    # Password hash — keep private

If you lose .key, your encrypted files are unrecoverable. Back up keys regularly.

---

Threat Model

Protected against:

• Passive network eavesdropping (all data encrypted in transit)
• Curious peer operators (chunks encrypted, can't read files)
• Curious relay operators (messages E2E encrypted)
• Brute-force password attacks (PBKDF2 + lockout)
• Timing attacks on peer secret (constant-time comparison)
• Path traversal attacks (input sanitization on file operations)

NOT protected against:

• Compromised cell (if attacker gets your private keys, they can decrypt)
• Physical access to your device (disk not encrypted by Grove — use OS-level encryption)
• Metadata analysis (chunk counts, timing patterns can reveal activity)
• Targeted attacks by a peer who stores your chunks (they can delete them)
• Auto-update supply chain (a compromised peer could push malicious code)

Mitigations:

• Key backup: download and store offline
• Replication: multiple peers reduces single-peer risk
• Auto-update: can be disabled in config (disable_auto_update: true)
• OS-level disk encryption recommended for mobile/laptop cells