relicario/user_docs/the-browser-extension.md

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 available in your terminal. Open a terminal in the root of the Relicario source tree and run these commands in order:

# 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:

npm run build:firefox
# Output goes to extension/dist-firefox/

To build everything in one shot:

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 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