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:
61
docs/SECURITY.md
Normal file
61
docs/SECURITY.md
Normal 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.
|
||||
Reference in New Issue
Block a user