alee/relicario
1
0
Fork 0
Code Issues Pull Requests 8 Actions Packages Projects Releases Wiki Activity

docs(user): add user_docs/ end-user guide (12 pages)

Browse Source 
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).
This commit is contained in:
adlee-was-taken
2026-06-20 21:05:04 -04:00
parent b09e0ce036
commit 3ab1320f42
12 changed files with 1698 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
user_docs/the-browser-extension.md Normal file
View File

@@ -0,0 +1,163 @@
# The Browser Extension
This page covers how to build and install the Relicario browser extension, set it up for the first time, and use it for everyday password unlocking, autofill, and vault management.
---
## What it is
The Relicario browser extension brings your vault into your browser. It works in **Chrome and Chromium** (the primary target) and **Firefox** (Manifest V3). It gives you a popup for quick unlock, search, and field copying; in-page autofill on login forms; live TOTP codes; and, on Chrome, a fullscreen vault tab where you can add, edit, and manage everything.
There is no listing in the Chrome Web Store or Firefox Add-ons yet — you build and load it from source.
---
## Build it from source
You need the Relicario source code and [Node.js](https://nodejs.org) available in your terminal. Open a terminal in the root of the Relicario source tree and run these commands in order:
```bash
# Step 1 — build the WebAssembly crypto module
npm run build:wasm
# Step 2 — build the Chrome extension (output goes to extension/dist/)
npm run build
```
If you also want a Firefox build:
```bash
npm run build:firefox
# Output goes to extension/dist-firefox/
```
To build everything in one shot:
```bash
npm run build:all
```
---
## Install it in your browser
### Chrome / Chromium
1. Go to `chrome://extensions` in the address bar.
2. Turn on **Developer mode** (toggle in the top-right corner).
3. Click **Load unpacked**.
4. Select the `extension/dist/` folder inside the Relicario source tree.
The Relicario icon should appear in your browser toolbar.
### Firefox
1. Go to `about:debugging#/runtime/this-firefox` in the address bar.
2. Click **Load Temporary Add-on**.
3. Navigate to `extension/dist-firefox/` and select the `manifest.json` file inside it.
> **Note:** Firefox loads extensions temporarily — they are removed when you close and reopen the browser. Rebuild and reload after each browser restart.
---
## First-run setup wizard
The first time you click the Relicario toolbar icon, a short setup wizard walks you through connecting the extension to a vault.
### Option A — Create a new vault
1. Choose **Create a new vault**.
2. Select your git host: **Gitea** or **GitHub**. Enter the host URL (for Gitea), your repository, and an access token.
3. Upload a carrier photo — any JPEG you own. Relicario will embed a hidden 256-bit secret inside it and produce a **reference image**. Set a strong passphrase (a strength meter guides you; you need a high score to proceed).
4. Relicario creates the vault in your remote repository and stores the reference image inside the browser. The reference image is your second factor — it never leaves the browser or goes to your git remote.
5. Give this device a name (e.g. "Laptop") and click **Done**.
### Option B — Attach this device to an existing vault
1. Choose **Attach to existing vault**.
2. Enter your git host details (host URL, repository, access token).
3. Upload your existing reference JPEG — the one produced when the vault was first created.
4. Enter your passphrase.
5. Give this device a name and click **Done**.
---
## Everyday use
Click the Relicario toolbar icon. Type your passphrase and click **Unlock**.
You only type your passphrase — the reference image is stored once in the browser and re-read automatically on every unlock. All cryptography runs on-device inside WebAssembly; nothing secret is sent over the network.
Once unlocked, the popup shows your item list. You can:
- **Search** by typing any part of an item's title.
- **Reveal or copy** fields (passwords, card numbers, notes, etc.).
- **View live TOTP codes** — they count down and refresh every 30 seconds.
When you're done, close the popup. The vault locks automatically based on your configured idle timeout (see [Auto-lock](#auto-lock) below).
---
## Autofill
When you land on a login page, Relicario shows a small icon inside the username or password field. Click it to fill the matching login.
Matching is done by **hostname** — Relicario looks for a login whose URL matches the current page's hostname.
**The first time you use autofill on a site**, Relicario shows a Trust-On-First-Use prompt asking you to confirm. Once you confirm, it remembers.
**On form submit**, Relicario can offer to **save a new login** or **update an existing one** if it detects that the credentials differ from what it has stored.
> **Heads-up on hostname matching:** matching is coarse. `github.com` and `www.github.com` are treated as separate hosts, so a login saved for one will not autofill on the other. You can add both URLs to a login item to cover both.
**Syncing** is always manual — click **Sync now** in the popup. There is no background polling.
---
## The fullscreen vault tab (Chrome only)
On Chrome, you can open a **fullscreen vault tab** for complete vault management. This is not available in Firefox.
From the fullscreen tab you can:
- **Add, edit, and delete** all 7 item types: Login, Secure Note, Identity, Card, SSH/API Key, Document, and TOTP.
- Manage **settings**, **devices**, **trash**, and **field history**.
- Run a **backup export or restore** (`.relbak` files).
- **Import from LastPass** (CSV export).
For day-to-day password filling the popup is enough; the fullscreen tab is for vault housekeeping.
---
## Permissions the extension requests
| Permission | Why |
|---|---|
| `storage` | Saves your configuration and the reference image inside the browser. |
| `activeTab` | Reads the current tab's URL to match logins for autofill. |
| `clipboardWrite` | Copies secrets to the clipboard when you click Copy. |
| Host access | Injects the autofill icon into login pages; communicates with your Gitea/GitHub API for sync. |
---
## Auto-lock
You can configure an idle timeout in the extension settings. Options include locking after N minutes of inactivity, or locking immediately when the popup closes. To change it, open the popup while unlocked and look for **Settings → Auto-lock**.
---
## Current limits
A few things to be aware of before you rely on the extension:
- **No org/enterprise vault support.** If you use Relicario's multi-user org vault, the extension cannot browse, read, or write to it yet. Org support is planned but has no release date.
- **Fullscreen vault tab is Chrome-only.** Firefox users get the popup and autofill, but not the full management UI.
- **Hostname matching is coarse.** `github.com` and `www.github.com` are separate entries. Save both URLs on a login item if you need both covered.
- **One vault per browser install.** You cannot switch between personal vaults in the same browser profile.
- **Sync is manual.** There is no push/pull happening in the background — you initiate sync by clicking **Sync now**.
- **No mobile apps.** The extension is desktop-browser only.
- **No Relicario-run server.** You need your own Gitea instance or a GitHub account. Relicario does not provide hosted storage.
---
**Next:** [Recovery](recovery.md)