# Keepsake Security Model

**Status:** Draft 1 (2026-07-02). This document is written to be published verbatim at securekeepsake.com/security once Vault Format v2 ships. Honesty is the point: we state what Keepsake protects against, what it doesn't, and how to verify our claims.

---

## 1. Architecture in one paragraph

Keepsake is **local-first and zero-knowledge by construction**. Your documents are encrypted with AES-256-GCM on your device, under keys derived only from things you hold (your password, recovery phrase, or your device's hardware keystore). Encrypted data is stored on your device and — if you enable sync — in **your own** Google Drive or OneDrive. Keepsake (the company) operates no document servers. We cannot read, lose, leak, or be compelled to hand over your documents, because we never possess them in any form.

## 2. What we protect, and from whom

| Threat | Protected? | How |
|---|---|---|
| Stolen/lost laptop or phone | ✅ | All content AES-256-GCM encrypted at rest; keys derived via Argon2id from your password; auto-lock wipes keys from memory |
| Cloud provider (Google/Microsoft) reading synced vault | ✅ | Provider stores only ciphertext blobs; keys never leave your devices |
| Keepsake (us) reading your data | ✅ | Structurally impossible: no servers hold your data or keys |
| Data breach at Keepsake | ✅ | Our website database contains at most your email + license record — never documents or keys |
| Ciphertext tampering (malicious cloud, MITM) | ✅ | GCM authentication + AAD binding; modified files fail decryption loudly |
| Someone replaying an old vault state | ✅ (local) | Index generation counter — a device refuses to load older state than it has seen |
| Shared-link interception (Secure Send) | ✅ | Content encrypted client-side; decryption key travels in the URL **fragment**, which browsers do not send to servers; optional PIN; burn-after-read |
| Audit-log falsification | ✅ | Hash-chained audit records; verifiable in Settings |
| Weak/guessed password | ⚠️ Partial | Argon2id (memory-hard) makes offline guessing expensive; strength meter at registration; we cannot stop you choosing "123456" — choose well |
| Malware on your unlocked device | ❌ | No app can defend a compromised OS with the vault open. Keys are held only while unlocked and zeroed on lock, which limits the window |
| You forgetting password AND losing the Recovery Kit | ❌ | Zero-knowledge means exactly that: nobody — including us — can reset it. This is a feature; treat the Recovery Kit like cash |
| Rubber-hose/coerced unlock | ❌ | Out of scope |

## 3. Cryptography (summary — full spec in VAULT_FORMAT_V2.md)

- **Encryption:** AES-256-GCM, random 96-bit nonce per file, AAD binding ciphertext to document identity. No unauthenticated modes anywhere.
- **Key derivation:** Argon2id (64 MiB / 3 iterations / 4 lanes on desktop; tuned per platform), parameters stored openly in the vault manifest.
- **Envelope keys:** a random 256-bit Master Key encrypts data; your password/recovery phrase/biometric key only *wrap* the Master Key. Password change and key rotation never require re-encrypting your documents.
- **Recovery:** 24-word BIP-39 phrase (printable Recovery Kit with QR) wraps the same Master Key.
- **Biometrics:** Windows Hello / Android Keystore hold a hardware-backed wrapping key; biometric data never touches Keepsake.
- **Licenses:** Ed25519-signed, verified offline; the license system knows your email, never your data.
- **Primitives are boring on purpose:** AES-GCM, Argon2id, HKDF, SHA-256, Ed25519, BIP-39, X25519 — no home-made crypto.

## 4. What Keepsake's website knows about you

| Data | Where | Why |
|---|---|---|
| Email + password hash (Argon2id) | securekeepsake.com MySQL | Website account (forum, license) — optional, separate from your vault |
| License record (email, plan, expiry) | same | To re-issue your key if you lose it |
| Invoice details you send us | email | Manual payment processing |
| Secure Send blobs | same host | Ciphertext only, auto-deleted at TTL/burn |
| Analytics | server-side page counters | No third-party trackers, no ad-tech, no fingerprinting |

Your vault never requires a website account. The apps work forever with no registration.

## 5. OCR and AI stay on-device

All OCR (Tesseract/PurpleOCR, ML Kit, ONNX models) and any future "Ask your vault" AI run **entirely on your device**. Document text is never sent to any cloud API. Corrections you make improve extraction locally only — we deliberately reject collecting training data.

## 6. Verifiability ("don't trust, check")

1. **The format is public** — VAULT_FORMAT_V2.md documents every byte; an independent tool can decrypt your vault with your password alone.
2. **Network transparency** — run the apps behind a proxy: you'll see traffic only to your chosen cloud provider (sync), your license check is offline, and update checks fetch static files.
3. **Survivability guarantee** — if Keepsake disappears tomorrow, your apps keep working (offline license verification), your data stays in your Drive, and the published spec is enough to recover everything.
4. Core crypto module planned as source-available for public review.

## 7. Known v1 weaknesses being fixed in v2 (public changelog)

Existing installs (pre-v2) use AES-256-CBC without authentication and direct password-derived file keys. Vault Format v2 replaces this with authenticated GCM + envelope keys; the app migrates vaults automatically on first unlock after update. We document this because pretending past versions were perfect is how vendors earn distrust.

## 8. Reporting security issues

Email hello@securekeepsake.com. No bug bounty budget yet — but credited acknowledgements, fast fixes, and honest disclosure notes are guaranteed. Please practice coordinated disclosure.