← Dashboard · Docs ·Security

Grove Security Model

Build e6c937427256 · Updated 2026-06-07

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 or their names
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
Manifest metadata (filename, path)	ChaCha20-Poly1305	256-bit (per-recipient envelope)
Grant key wrapping	X25519 + HKDF-SHA256	256-bit
Chunk/content addressing	BLAKE2b	256-bit
Cell identity	Ed25519	256-bit
Chat key exchange	X25519	256-bit
Chat messages (peer + portal)	ChaCha20-Poly1305	256-bit
Password hashing	PBKDF2-SHA256	100k iterations, random salt
Peer secret comparison	HMAC-SHA256 (timing-safe)	—

Authentication

Dashboard

Password hashed with PBKDF2-SHA256 (100k iterations, random salt), stored in ~/.grove/dashboard_auth
Session cookies: HttpOnly, SameSite=Lax, 30-day expiry
Brute-force protection: lockout after repeated failed attempts (auth_lockout)
Per-real-client-IP rate limiting (nginx sets X-Real-IP authoritatively; Grove uses it for lockout and rate checks)
Login endpoint rate-limited to 20 requests/60 s per IP

Peer-to-Peer

X-Grove-Secret header on all peer API calls
Per-peer derived secrets (v0.4.1+): each peer relationship uses an HMAC-SHA256 derived from the bilateral pubkey pair (_derive_peer_secret). The global peer secret is a fallback for legacy callers only.
X-Grove-Sender header identifies the calling cell's pubkey; the receiver derives the expected secret for that identity and rejects mismatches — this prevents a peer from using a valid global secret to masquerade as a different identity.
All comparisons use hmac.compare_digest (constant-time, prevents timing attacks).

Relay

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

Manifest Metadata Protection (§7 — SEALED)

Prior to build d487e1d (2026-05-20), manifest metadata — filename, source path, version note, delete state — was stored in plaintext on every peer that held even one chunk for replication. Any replication-only peer could enumerate a user's entire library. This was a real leak against Grove's stated privacy goals.

The fix is documented in full at MANIFEST-METADATA-LEAK.md (canonical). Summary:

Schema v1 manifests: the three sensitive fields (filename, source_path, version_note) live in an encrypted_metadata blob, encrypted with a per-manifest metadata key.
Per-recipient envelope: metadata_envelope holds the metadata key wrapped with X25519 for each authorized recipient (creator + every grantee). Peers without a grant entry cannot decrypt the metadata.
Opaque on-disk names: manifests are stored as .json (not filename-derived), so the filename is not revealed by the filesystem either.
Author-signed: v1 manifests include the creator's Ed25519 signature over the v1-tagged signable data. A peer cannot forge or swap manifests.
Peer access gating: peer_can_access_manifest() in grove.py gates which peers receive manifests during sync. Metadata visibility is strictly per-grant.
Migration complete: all pre-v1 manifests on the fleet were re-encrypted and pushed to peers (2026-05-23, 4f358be). The fleet holds no plaintext v0 manifests for own files.

Trust Model and Identity Tiers

Identity in Grove is a keypair (Ed25519 for signing, X25519 for encryption). Three tiers:

Tier	Who	What they can do
Peer	Any connected cell	Replicate encrypted chunks; no file/metadata access
Friend	Mutual explicit trust	Chat + file sharing (grants); metadata visible only for explicitly granted files
Observer	Portal account	Sees only files the cell owner has explicitly shared to that account

Friendship grants chat access and file sharing but does NOT grant blanket metadata visibility. Metadata is strictly per-grant via peer_can_access_manifest.
Grants are signed (Ed25519) by the creator and envelope-encrypted (X25519) per recipient. A peer cannot access a grant it wasn't issued.
C1 invariant (revoke-grant is sender-pubkey-gated): a revoke-grant request at /api/revoke-grant is only accepted if the request's granted_by field matches the X-Grove-Sender header. An attacker who compromises a peer secret cannot forge revocations from a different identity. See INVARIANTS.md / INVARIANT-AUDITS.md.
Symmetric unfriend/revoke: unfriending removes the peer from both sides and revokes all outstanding grants.

What Peers Can See

Data	Visible to replication-only peers?
File contents	No — encrypted chunks, key never shared
File names	No — v1 manifest metadata is encrypted; opaque on-disk names
Source paths	No — encrypted in v1 manifest metadata
Chunk hashes	Yes — needed for deduplication/replication
Your cell's pubkey	Yes — identity
Your cell's name	Yes — you choose what to advertise
Your IP address	Yes — needed to connect
Storage usage (chunk count)	Yes — chunk count visible
Chat messages	No — end-to-end encrypted

Friends with grants can decrypt filename/path for the specific files they were granted access to. They cannot enumerate your full library.

What Relay Operators Can See

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

Portal and WAN Security

The portal is an owner-gated window into a cell, accessible over the public WAN.

Owner session is tailnet-only: nginx on WAN-facing nodes tags public-edge requests with X-Grove-Public-Edge: 1 (overwriting any client-supplied value). check_dashboard_auth rejects owner session cookies and portal-admin /api/ access when this tag is present. The owner dashboard and admin APIs are therefore only reachable over Tailscale (or from localhost). This closed a real hole on the familynook node (2026-06-06, da49bd0).*
Portal file visibility: a portal account sees only files it owns (creator or portal_owner stamp matches) or files explicitly shared to it. _portal_visible_manifests() enforces this. This closed prior IDOR / roster-enumeration / XSS / reshare bugs (tasks #57-#60).
Portal chat at rest: portal chat content is encrypted with ChaCha20-Poly1305 under a cell-local key (portal_chat.key) before being written to the database (v1: format).
Owner WAN remote access: the owner's identity keys never leave the cell. Portal remote access authenticates the owner account via the portal credential path, not by exposing Ed25519 keys to the gateway.
Public endpoints: only /portal, /site, /invite, /relay, and explicitly public APIs are reachable over the public edge. Everything else requires tailnet or localhost.
Per-account rate limiting: friends are rate-limited more tightly than owners (15 req/60 s vs 60 req/60 s) to protect fleet resources.

AI Safety Posture

Grove's AI features (chat inference, image generation, peer AI proxying) include several security layers:

Local-first inference: AI requests prefer local models. The peer_model_policy config key (default: friends) gates which peers may use your cell's inference capacity — friends = only mutual friends, none = no remote access.
E2E-encrypted AI proxy: when AI requests are forwarded to a peer, the payload is encrypted with ChaCha20-Poly1305 using a per-conversation key (encrypt_chat_message). The relay cannot read inference traffic.
Image-gen moderation hook: every image generation request passes through _image_prompt_moderation() before reaching the worker queue. Hard-reject token patterns block the request at submission time and log to ~/.grove/image-gen-rejections.log. This was added after a 2026-05-18 incident.
Abliterated/refusal-stripped LLMs are banned as submitters: models with refusal training removed may suggest content in a chat context but may never be the direct submitter of side-effecting actions (image generation, file writes, broadcasts). They are suggesters only, behind a human gate. This is a standing operational rule, not just a preference.
Threat model framing (§10): Grove's AI threat model is calibrated for "a tinkerer with an abliterated LLM and loose ops hygiene," not a deliberate external attacker. This is appropriate for a small trusted family network. The four defense layers must all fail simultaneously for a recurrence of the 2026-05-18 class of incident.

Defense-in-Depth: Signed Deletion

Chunks belonging to a peer are only deleted from your node by one path: a signed tombstone that propagates via the regular manifest-sync loop. process_tombstones() verifies the Ed25519 signature against the leaving peer's pubkey before purging anything.

The live /api/peer-leaving notification is treated as a hint only — it removes the peer from config and health, but never deletes data, even when authenticated. Reason: shared peer secrets can leak; Ed25519 signatures cannot be forged. An attacker who obtained a peer's secret could remove the peer from your peer list, but cannot trigger a data purge.

Key Files and 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
~/.grove/portal_chat.key     # Portal chat at-rest key — keep private

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

Invariants

Grove has 14+ locked behavioral invariants covering replication counting, trust boundaries, grant gating, routing, and chunk management. They are the authoritative source of truth for expected security behavior:

INVARIANTS.md — invariant definitions in plain language
INVARIANT-AUDITS.md — audit procedure, per-invariant compliance tables, property test pointers

This document does not duplicate them. When a code path appears to violate an invariant, consult those files first.

Threat Model

Protected against

Passive network eavesdropping (all data encrypted in transit)
Curious replication-only peers (chunks encrypted; filenames and paths encrypted in v1 manifests)
Curious relay operators (messages E2E encrypted)
Brute-force password attacks (PBKDF2 + lockout + rate limiting)
Timing attacks on peer secret comparison (constant-time HMAC comparison)
Path traversal attacks (input sanitization on file operations)
Grant forgery / revocation forgery (Ed25519-signed grants; C1 invariant gates revocations by sender identity)
Owner dashboard exposure over the public WAN (nginx X-Grove-Public-Edge tag; tailnet-only gate)
Portal IDOR / roster enumeration (per-account manifest visibility filter)
Manifest metadata enumeration by replication peers (§7 v1 envelope encryption, sealed 2026-05-23)
Image-gen prompt injection from abliterated LLMs (pre-submission moderation hook + operational ban)

NOT protected against

Compromised cell (attacker with your private keys can decrypt everything)
Physical device access (Grove does not encrypt the disk — use OS-level full-disk encryption)
Traffic metadata analysis (chunk counts, timing patterns, connection graph visible to relay)
A malicious peer deleting chunks they hold (replication factor mitigates; Grove cannot force a peer to retain data)
Auto-update supply chain (a compromised update channel could push malicious code; can be disabled with disable_auto_update: true)

Mitigations

Key backup: download and store offline via the dashboard
Replication: desired_factor ≥ 3 reduces single-peer loss risk
Auto-update: disable in config if supply-chain risk is a concern
OS-level disk encryption recommended for all cells, especially laptops and mobile devices