diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..d99a64b --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,61 @@ +# Relicario Security Model + +## Cryptographic Protection + +Relicario uses two-factor vault decryption: +1. **Passphrase** — user-memorized, zxcvbn score ≥3 required +2. **Reference image** — JPEG carrying 256-bit secret via DCT steganography + +Key derivation: Argon2id (64 MiB memory, 3 iterations, 4 parallelism) +Encryption: XChaCha20-Poly1305 (192-bit nonce, 256-bit key) + +## Manifest Integrity + +The manifest (`manifest.enc`) is encrypted with AEAD, which provides: + +- **Confidentiality**: Contents unreadable without master key +- **Integrity**: Any modification detected and rejected on decrypt +- **Authenticity**: Only master key holders can create valid ciphertexts + +### What AEAD Does NOT Protect + +- **Item deletion**: An attacker with write access can delete `.enc` files + or git-revert commits. The manifest decrypts successfully but won't + contain the deleted items. + +- **Rollback attacks**: An attacker can replace `manifest.enc` with an + older valid version. AEAD accepts any ciphertext created with the key. + +### Mitigation + +Item deletion and rollback are detectable via **git history**: + +```bash +git log --oneline items/ +``` + +For environments where git history could be rewritten (force-push): + +1. Enable device authentication (commit signing + pre-receive hook) +2. Use a git server that rejects non-fast-forward pushes +3. Regular backups with `relicario backup export` + +## Device Authentication + +When enabled, device authentication provides: + +- **Commit authorship**: All commits signed by registered device keys +- **Push access control**: Deploy keys managed via Gitea API +- **Instant revocation**: One command cuts off both signing and push + +See `docs/superpowers/specs/2026-05-02-device-authentication-design.md`. + +## Access Control + +Without device authentication, access control is transport-layer only: + +- **CLI**: SSH key authentication to git remote +- **Extension**: Git credentials in browser storage + +Device registration was optional before v0.4.0. With device auth enabled, +all commits must be signed by a registered device.