docs: document manifest integrity model (audit I4)

Clarifies what AEAD protects (tampering) vs. what it doesn't (deletion,
rollback). Documents that git history is the audit trail and device
authentication is the mitigation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
adlee-was-taken
2026-05-02 09:36:34 -04:00
parent b9f44a3d4f
commit 8e26c8708b

61
docs/SECURITY.md Normal file
View File

@@ -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.