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).
164 lines
6.9 KiB
Markdown
164 lines
6.9 KiB
Markdown
# 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)
|