What Exists Today
BuddyDrive currently has these security layers:
| Component | Algorithm | Purpose |
|---|---|---|
| Direct peer transport | libp2p Noise | Encrypt direct libp2p connections |
| Folder content encryption | libsodium crypto_secretbox (XSalsa20-Poly1305) | Encrypt filenames and file contents stored on buddy's machine |
| Path encryption | Deterministic nonce from folderKey + path | Same path always encrypts to same ciphertext (enables move detection) |
| Chunk encryption | Random nonce per 64KB chunk | Prevents nonce reuse across file versions |
| Recovery config backup | libsodium crypto_secretbox | Encrypt config synced to relay |
| Pairing code | Shared secret | Match buddies, derive discovery keys, HMAC-authenticate relay records, and relay fallback sessions |
| Recovery phrase | 12-word mnemonic | Re-derive recovery metadata on a new machine |
Recovery Phrase And Master Key
- BuddyDrive generates a 12-word recovery phrase
- It derives a master key from that phrase
- It stores recovery metadata in
config.toml - It encrypts your serialized config before syncing it to the relay
When you later run buddydrive recover, BuddyDrive uses the same 12 words to derive the same recovery material, fetches the encrypted config from the relay, decrypts it locally, and writes the restored config.
Control API Access
The control API binds to all interfaces (default port 17521):
- Localhost (
127.0.0.1,::1): No authentication required - LAN: Requests must use a secret path prefix
/w/<secret>/derived from your buddy UUID (first 8 hex characters). Requests without the correct secret receive 403 Forbidden.
The secret provides basic protection but is low-entropy (32 bits). Only access the web GUI on trusted networks or over localhost.
Pairing And Direct Connections
- You share the pairing code out-of-band with someone you trust
- Both sides store it for that buddy relationship
- Relay fallback uses it to match the two peers
- Direct libp2p connections use Noise transport encryption once connected
Current Scope And Limits
- Direct libp2p transport is encrypted by Noise
- Folder contents (filenames and file data) are encrypted with XSalsa20-Poly1305 before being stored on the buddy's machine when
encrypted = true(the default) - Recovery config blobs synced to the relay are encrypted with the recovery master key
- Restore works by recovering config first and then letting normal sync recreate missing files
- Restored files are hash-verified after write
- Append-only protects existing local files from remote overwrite
When encrypted = false (sharing mode), files are stored plaintext on the buddy's machine. Pair only with buddies you trust for unencrypted folders.
What Your Buddy Can See Today
When folder encryption is enabled (default):
Your buddy cannot see:
- Your original filenames (encrypted with deterministic path encryption)
- Your file contents (encrypted with random nonces per chunk)
- The encrypted recovery config stored in the relay without your recovery phrase
- Your other buddies' configuration unless you share it with them
Your buddy can see:
- The total storage use and sync timing
- The size of encrypted blobs on disk
When folder encryption is disabled (encrypted = false):
- Your buddy can see folder and file names, and read file contents
Threat Model
What We Protect Against
Network interception on direct libp2p connections: Noise protects direct peer transport.
Buddy reading your files: folder encryption (XSalsa20-Poly1305) makes filenames and content opaque to the storage buddy.
Relay compromise for config backup: the relay stores an encrypted config blob; without the recovery phrase-derived master key it should not be readable.
Lost machine: recovery lets you rebuild config on a replacement device and then resync missing files.
What We Do Not Protect Against
Untrusted buddies with unencrypted folders: if you pair with someone you do not trust and use encrypted = false, they can read your synced files.
Your machine compromised: malware on your machine can read files before or during sync.
Denial of service: an attacker can still prevent peers from connecting.
Secure Pairing Guidelines
- Share codes verbally or in person when possible
- Verify identity through a second channel
- Use unique codes for each buddy relationship
- Check buddy IDs on both machines
Security Checklist
- Pair only with trusted buddies
- Verify buddy ID after pairing
- Write down the 12-word recovery phrase and store it offline
- Keep your system updated
- Use strong local passwords
- Consider full-disk encryption on your machine
- Regularly check sync activity
Bottom Line
BuddyDrive protects direct libp2p transport with Noise, encrypts relay-backed recovery config with your master key, and encrypts folder filenames and contents with XSalsa20-Poly1305 before storing them on your buddy's machine. Your buddy sees only opaque encrypted blobs. Set encrypted = false only for active collaboration with buddies you trust.