3ab1320f42
A friendly, task-oriented guide for non-technical users: README index, getting-started, concepts, items, passwords-and-generators, totp, attachments-and-documents, organizing, sync-and-backup, the-browser-extension, recovery, faq. Every command/flag derived from the actual CLI surface (`relicario --help` tree) and real extension behavior — no invented flags. Org item-type parity is covered high-level pending the v0.8.1 B/C merge (two TODO markers left for the rebase).
76 lines
4.2 KiB
Markdown
76 lines
4.2 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.
|
|
|
|
Org vault support is actively evolving. Item-type parity (Card, Key, Document, TOTP) in the org vault is coming soon.
|
|
|
|
<!-- TODO: revisit org item types after rebase on final main -->
|
|
|
|
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)
|