d0f757b66d
All four v0.8.1 streams merged (main 4c0a289): org add now supports all 7 item
types (card/key/totp/document) and org edit is interactive. Flip the two
high-level org sections from "coming" to shipped, grounded in the real merged
`relicario org add <type> --collection …` surface; remove the rebase TODO markers.
74 lines
4.3 KiB
Markdown
74 lines
4.3 KiB
Markdown
# How Relicario works
|
|
|
|
This page explains the core ideas behind Relicario — no technical jargon required. Read this before anything else and the rest of the docs will make much more sense.
|
|
|
|
---
|
|
|
|
## Two factors, one key
|
|
|
|
Relicario requires **two things** to unlock your vault:
|
|
|
|
1. **Your passphrase** — something you remember and type. Think of it like the combination to a safe.
|
|
2. **Your reference photo** — a JPEG image you chose when you set up your vault. Relicario hid a random secret inside the photo's pixels at setup time. You keep this file safe; it never gets uploaded to your git repository.
|
|
|
|
Neither one alone does anything. They're like two keys that must turn at the same time — if either is missing, the vault stays shut.
|
|
|
|
A helpful way to picture it: imagine a safety deposit box that needs both your key *and* the bank's key to open. Your passphrase is your key; your reference photo is the other. Lose either one, and you can't get in.
|
|
|
|
> **For the curious:** Relicario derives the vault key using Argon2id (a memory-hard key derivation function) and encrypts everything with XChaCha20-Poly1305. See [../docs/CRYPTO.md](../docs/CRYPTO.md) for the full pipeline.
|
|
|
|
---
|
|
|
|
## Your data lives on your own git server
|
|
|
|
Relicario stores your vault in a **git repository that you control** — hosted on your own Gitea instance or on GitHub. There is no Relicario-run cloud, no Relicario account, and no subscription.
|
|
|
|
**The trust model in one sentence:** the server only ever stores ciphertext — your passphrase, your image secret, and your decrypted data never leave your device.
|
|
|
|
Even if someone broke into your git server and downloaded every file, all they would have is encrypted noise. The keys to decrypt it never leave your machine.
|
|
|
|
---
|
|
|
|
## What's stored where
|
|
|
|
When you initialize a vault, Relicario creates a few files inside your repository:
|
|
|
|
| Path | What it is |
|
|
|---|---|
|
|
| `.relicario/` | Config directory: key-derivation salt and parameters (not secret) |
|
|
| `manifest.enc` | Encrypted index — lets the app list item titles without decrypting everything |
|
|
| `settings.enc` | Encrypted vault settings |
|
|
| `items/<id>.enc` | One encrypted file per item |
|
|
| `attachments/<item-id>/<att-id>.enc` | Encrypted attachment blobs |
|
|
| `reference.jpg` | Your reference photo — **gitignored, never committed** |
|
|
|
|
The last line is the important one: **your reference photo is deliberately excluded from git.** If you only back up your git remote, you have only backed up half of what you need. See [the golden rule](#the-golden-rule) below.
|
|
|
|
Because your vault is a normal git repository, its full history is preserved automatically. Every change you make creates a new commit, giving you an audit trail you can browse with any standard git tool.
|
|
|
|
---
|
|
|
|
## Personal vault vs. org (team) vault
|
|
|
|
Most people use a **personal vault** — one vault, one person, one set of two factors. That's what the rest of these docs cover.
|
|
|
|
Relicario also supports a **multi-user org vault** for teams: an owner can add members, create collections (groups of items), and grant or revoke access per collection. Roles (owner, admin, member) control what each person can do, and every action is recorded in a signed audit log. The same trust model applies — the server only ever sees ciphertext, and access is enforced by collection grants, not by server-side permissions.
|
|
|
|
An org vault stores the same seven item types as a personal vault — logins, secure notes, identities, cards, keys, documents, and TOTP codes — added with `relicario org add <type> --collection <name> …`. Members only ever see the collections they have been granted.
|
|
|
|
For day-to-day use, see [Sync & backup](sync-and-backup.md) for syncing an org vault across devices.
|
|
|
|
---
|
|
|
|
## The golden rule
|
|
|
|
> **Never forget your passphrase, and always keep at least one safe copy of your reference photo.**
|
|
>
|
|
> Losing your passphrase means your vault cannot be decrypted — there is no password reset and no backdoor. Losing your reference photo *and* your recovery QR (even if you still know your passphrase) has the same result. Losing both factors means your data is gone for good, by design.
|
|
>
|
|
> **What to do:** print or photograph your recovery QR and store it somewhere safe and offline. See [Recovery](recovery.md) for the full instructions.
|
|
|
|
---
|
|
|
|
**Next:** [Items](items.md)
|