relicario/docs/superpowers/specs/2026-04-12-relicario-init-wizard-design.md

relicario — Standalone Vault Initialization Wizard Design

A browser-based wizard that guides new users through creating an relicario vault from scratch. Lives at extension/setup.html, uses the same WASM module as the extension, same terminal dark aesthetic. No server, no Rust toolchain required.

Scope

• Single HTML page with inline JS (bundled by webpack) at extension/setup.html
• 4-step wizard: choose host → configure connection → create vault → finish
• Pushes vault files directly to Gitea/GitHub via API
• Downloads reference image to user's machine
• Optionally pushes config to the Chrome extension if installed

Flow

Step 1: Choose Git Host

Toggle between Gitea and GitHub. Below the toggle, show inline setup instructions:

Gitea instructions:

1. Log in to your Gitea instance
2. Create a new empty repository (no README, no .gitignore)
3. Go to Settings → Applications → Generate New Token
4. Select scope: repo (read/write)
5. Copy the token

GitHub instructions:

1. Go to github.com → New Repository
2. Create an empty repository (no README, no .gitignore, no license)
3. Go to Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
4. Generate new token, select only the target repository
5. Permissions: Contents → Read and write
6. Copy the token

Step includes a "Next" button. No validation needed at this step.

Step 2: Configure Connection

Fields:

• Host URL (e.g. https://git.adlee.work or https://github.com) — pre-filled based on host type selection
• Repository path (e.g. alee/relicario-vault)
• API token (password field)

"Test Connection" button:

• Hits the git API to verify the token works and the repo exists
• Checks that the repo is empty (no files) or contains only a README
• Shows green checkmark on success, red error on failure
• Must pass before "Next" is enabled

Uses the same GitHost interface (GiteaHost/GitHubHost) from the extension's service worker code.

Step 3: Create Vault

Two inputs:

• Carrier image: File picker for a JPEG. Shows preview thumbnail after selection. Minimum size guidance ("use a photo from your phone — at least 400x300").
• Passphrase: Password field with confirmation. Minimum 8 characters enforced. Shows basic strength indicator (weak/ok/strong based on length + character variety).

"Create Vault" button triggers:

1. Load WASM module
2. Generate random 32-byte image_secret via crypto.getRandomValues()
3. Embed secret into carrier JPEG via WASM extract_image_secret — wait, that's extract. We need embed. Check: the WASM crate currently only exposes extract_image_secret, not embed. We need to add a embed_image_secret function to relicario-wasm.
4. Generate random 32-byte salt via crypto.getRandomValues()
5. Create params.json with default KDF params ({"argon2_m":65536,"argon2_t":3,"argon2_p":4})
6. Derive master_key via WASM derive_master_key(passphrase, image_secret, salt, params_json)
7. Encrypt empty manifest ({"entries":{},"version":1}) via WASM encrypt_manifest
8. Push files to repo via git API:
   • .relicario/salt (raw 32 bytes)
   • .relicario/params.json (JSON string)
   • .relicario/devices.json ([])
   • manifest.enc (encrypted manifest bytes)
9. Show progress bar during push operations

Spinner/progress during the Argon2id derivation (~1-2 seconds) and API calls.

Step 4: Finish

Two things happen:

Download reference image:

• Browser downloads the steganographic JPEG as reference.jpg
• Show warning: "Keep this image safe. You need it alongside your passphrase to unlock the vault. Store it somewhere you won't lose it."

Push config to extension (if available):

• Try to detect the relicario extension via chrome.runtime.sendMessage with a get_setup_state message
• If extension responds: push save_setup message with { config: { hostType, hostUrl, repoPath, apiToken }, imageBase64 }. Show "Extension configured! You can now open the extension and unlock your vault."
• If extension not detected: show the config as a copyable JSON blob with instructions: "Install the relicario extension, then paste this into the setup wizard." (Or just tell them to run through the extension setup manually with the same host/token/repo.)

WASM Crate Change

The relicario-wasm crate needs one new function:

#[wasm_bindgen]
pub fn embed_image_secret(carrier_jpeg: &[u8], secret: &[u8]) -> Result<Vec<u8>, JsValue>

This wraps relicario_core::imgsecret::embed. Currently only extract_image_secret is exposed.

File Structure

extension/
├── setup.html              # standalone wizard page
├── src/
│   └── setup/
│       └── setup.ts        # wizard logic (4-step state machine)
├── webpack.config.js        # add 'setup' entry point

The setup page reuses:

• extension/wasm/ — same WASM module
• extension/src/service-worker/git-host.ts, gitea.ts, github.ts — git API layer
• extension/src/popup/styles.css — terminal dark theme (imported or linked)
• extension/src/shared/types.ts — VaultConfig type

UI Design

Same terminal dark aesthetic as the popup but in a full-page layout (not 360px constrained). Centered content area, max-width ~600px. Same color scheme (#0d1117 bg, #58a6ff blue, monospace font).

Progress bar at top showing step 1-4. Each step is a full-page view with back/next navigation.

Extension Detection

// Try to send a message to the extension
function detectExtension(): Promise<boolean> {
  return new Promise((resolve) => {
    try {
      chrome.runtime.sendMessage(
        { type: 'get_setup_state' },
        (response) => {
          if (chrome.runtime.lastError || !response) {
            resolve(false);
          } else {
            resolve(true);
          }
        }
      );
    } catch {
      resolve(false);
    }
  });
}

Note: this only works if setup.html is served from the extension itself (chrome-extension://<id>/setup.html) or if we use externally_connectable in the manifest. For a local file, extension detection won't work — fall back to manual config copy.

If we add setup.html to the extension's web_accessible_resources and the user opens it via chrome-extension:// URL, messaging works natively.

manifest.json Changes

Add setup.html to the extension so it can be opened as a chrome-extension page:

{
  "web_accessible_resources": [{
    "resources": ["setup.html", "setup.js", "styles.css", "relicario_wasm_bg.wasm", "relicario_wasm.js"],
    "matches": ["<all_urls>"]
  }]
}

The setup page can then be opened at chrome-extension://<extension-id>/setup.html. The extension popup can link to it, or the user can navigate directly.

Security

• Passphrase never leaves the browser
• image_secret generated client-side, embedded client-side, never transmitted
• master_key derived and used in-browser only, then discarded
• API token used only for pushing vault files and optionally passed to extension storage
• The reference image download is the only artifact the user needs to keep safe

Non-Goals

• Creating repos via API (user creates the repo manually — API permissions for repo creation vary widely)
• Git operations beyond file CRUD (no commits history, no branches)
• Password strength estimation beyond basic length/variety checks
• Mobile support (desktop Chrome only for now)