<p align="center">
  <img src="extension/icons/relicario-logo.svg" alt="Relicario" width="128" height="128">
</p>

# Relicario

A git-backed, self-hostable password manager where decryption requires two independent factors: a passphrase you memorize and a reference JPEG that carries a hidden secret. Compromise of either factor alone is insufficient.

The server only ever sees opaque ciphertext. There is nothing else going on. This README is the security proof.

## How it works

```
Your passphrase (something you know)
        +
Your reference photo (something you have)
        |
        v
   [ Argon2id KDF ]  -->  master_key  -->  [ XChaCha20-Poly1305 ]  -->  encrypted vault
        ^                                                                      |
        |                                                                      v
   Never leaves                                                          Stored in git
   your device                                                         (opaque ciphertext)
```

At vault creation, Relicario embeds a random 256-bit secret into a carrier JPEG using DCT steganography. This photo becomes your **reference image** — a second factor that lives on your devices (and optionally as a "dead drop" on social media, since it survives JPEG re-encoding and mild cropping).

To unlock the vault, you provide your passphrase and point the client at the reference image. The client extracts the hidden secret, concatenates it with your passphrase, and runs Argon2id to derive the master key. Everything else follows from there.

## Security model

### What the server sees

A git repository containing:
- `manifest.enc` — opaque binary blob
- `entries/*.enc` — more opaque binary blobs
- `.relicario/salt` — a random 32-byte value (not secret)
- `.relicario/params.json` — Argon2id parameters (not secret)
- `.relicario/devices.json` — authorized device public keys

That's it. No plaintext. No metadata about what's inside. No keys, no passphrases, no reference images.

### What an attacker needs

| Scenario | Has | Needs | Result |
|---|---|---|---|
| Server breach | Encrypted vault + salt | Passphrase AND image secret | 256+ bits of entropy. Infeasible. |
| Server breach + stolen image | Vault + image secret | Passphrase | Passphrase entropy through Argon2id. 4 diceware words = ~7 million years. |
| Shoulder-surfed passphrase | Passphrase | Image secret | 256 bits. Infeasible. |
| Stolen device | Image + vault | Passphrase | Argon2id brute-force. Strong passphrase = safe. |

No single point of failure. The two-factor design means the passphrase alone can't decrypt the vault, and the image alone can't decrypt the vault.

### Compared to

| | Server breach entropy | KDF factors |
|---|---|---|
| LastPass | ~40-60 bits (master password only) | 1 |
| Bitwarden | ~40-60 bits (master password only) | 1 |
| 1Password | password + 128-bit Secret Key | 2 |
| **Relicario** | **password + 256-bit image secret** | **2** |

### What we don't protect against

- A compromised device with active malware. No software password manager can.
- Weak passphrases with a stolen reference image. Use 4+ diceware words.
- Rubber-hose cryptanalysis.

## Quick start

```bash
# Build from source
cargo build --release

# Create a vault (pick any JPEG as the carrier)
relicario init --image vacation.jpg --output reference.jpg

# Add a credential
relicario add

# Retrieve it
relicario get github

# List everything
relicario list

# Sync with your git remote
relicario sync

# Generate a random password
relicario generate -l 32
```

### Environment variable

Set `RELICARIO_IMAGE=/path/to/reference.jpg` to avoid being prompted for the image path on every command.

## The reference image

The reference JPEG is generated once during `relicario init`. It looks like a normal photo — because it is one. The 256-bit secret is embedded in the DCT coefficients of the luminance channel using Quantization Index Modulation, with heavy redundancy and Reed-Solomon-style majority voting across multiple copies.

The embedding survives:
- JPEG recompression (tested down to quality 85)
- Up to ~10-15% cropping from any edge
- Social media re-encoding (Instagram, Discord, etc.)

This means your reference image can live on your Instagram, your personal website, or anywhere else. It's useless without your passphrase.

## Architecture

```
relicario/
├── crates/
│   ├── relicario-core/     # Platform-agnostic library (no filesystem, no network)
│   │   ├── crypto.rs    # Argon2id KDF + XChaCha20-Poly1305 AEAD
│   │   ├── imgsecret.rs # DCT steganography: embed/extract 256-bit secrets in JPEGs
│   │   ├── entry.rs     # Entry, Manifest data model (serde)
│   │   └── vault.rs     # Encrypt/decrypt entries and manifests
│   └── relicario-cli/      # CLI binary: filesystem, git, terminal I/O
└── docs/
    └── superpowers/
        └── specs/       # Design specification with full threat model
```

`relicario-core` takes bytes and returns bytes. It has no knowledge of filesystems, git, or networks. This makes it portable to WASM (browser extension), Android (JNI), and iOS (Swift bridge).

### Crypto primitives

| Primitive | Purpose | Why this one |
|---|---|---|
| Argon2id (64 MiB, 3 iter, 4 parallel) | Key derivation from passphrase + image secret | Memory-hard, GPU-resistant, OWASP recommended |
| XChaCha20-Poly1305 | Authenticated encryption of vault entries | 192-bit nonce (no collision risk), fast in WASM/ARM without AES-NI |
| ed25519 | Device key signing | Per-device commit authorization, revocable without KDF rotation |

### Encrypted file format

```
version (1 byte) | nonce (24 bytes) | ciphertext (variable) | auth tag (16 bytes)
```

Every write generates a fresh random nonce. The version byte allows future format changes.

## Vault layout

```
my-vault.git/
├── manifest.enc          # Encrypted entry index (names, URLs, timestamps)
├── entries/
│   ├── a1b2c3d4.enc     # One encrypted entry per file
│   └── e5f6a7b8.enc
└── .relicario/
    ├── salt              # 32-byte random salt (not secret)
    ├── params.json       # KDF parameters
    └── devices.json      # Authorized device public keys
```

Entry IDs are random hex strings. Git history is preserved — every add/edit/delete is a commit. "When was this password last rotated?" is answered by `git log`.

## Device management

Each device generates its own ed25519 keypair. The public key is stored in `.relicario/devices.json` (committed to the repo). Device keys are used for commit signing — they do NOT participate in vault decryption.

Revoking a device: remove its key from `devices.json` and commit. No passphrase or reference image rotation needed.

```bash
relicario device add --name laptop
relicario device list
relicario device revoke laptop
```

## Building

Requires Rust stable (1.70+).

```bash
git clone ssh://git@git.adlee.work:2222/alee/relicario.git
cd relicario
cargo build --release
cargo test
```

The binary is at `target/release/relicario`.

## Roadmap

- [ ] WASM build + Chrome browser extension (inline crypto, no native messaging)
- [ ] Secure notes (free-form encrypted text entries)
- [ ] Secure document storage (encrypted file attachments up to 5-10 MB)
- [ ] `relicario unlock` daemon (ssh-agent-style, holds master key for a TTL)
- [ ] Android/iOS clients (Rust core compiles to ARM)
- [ ] Import from LastPass/Bitwarden/1Password
- [ ] Firefox/Safari extensions

## License

MIT

---

Built by [Aaron Lee](https://adlee.work). Design spec and threat model in `docs/superpowers/specs/`.