# Quickstart

Get Vestibule running in under five minutes on a Linux or Windows
development machine. For architecture and security model, see
[README.md](README.md).

## Prerequisites

- **LibreWolf** 115+ installed ([librewolf.net](https://librewolf.net))
  — or **Firefox** 115+ / Firefox ESR (works identically: the
  extension, usher, and policies are engine-standard)
- **Rust** 1.70+ installed via [rustup](https://rustup.rs)
- **Python 3** for the smoke test
- **Node.js** for the URL policy unit tests (`node
  scripts/test-url-policy.js`; CI runs them on every push)

## Build

```sh
cd helper
cargo build --release
cd ..
```

The usher binary lands at `helper/target/release/usher`
(Linux) or `helper\target\release\usher.exe` (Windows).

## Verify usher

Run the smoke test without LibreWolf. Exercises the Native Messaging
protocol end-to-end: hello handshake, ping/pong, unlock refusal, and
wake event simulation.

```sh
python3 scripts/test-native-messaging.py
```

Expected last line:

```
OK — usher production protocol works: Argon2id unlock + wake events.
```

The smoke test exercises the full production protocol: hello, ping,
set-unlock (stores Argon2id hash to disk), unlock with wrong password
(refused), unlock with correct password (granted), and wake simulation.
It cleans up the hash file after itself.

If this fails, usher will not work in LibreWolf either. Fix before
proceeding.

## Register usher as a Native Messaging host

### Linux

```sh
./scripts/install-native-host.sh
```

Installs to `~/.local/bin/usher` and registers the manifest in both
`~/.librewolf/native-messaging-hosts/` and
`~/.mozilla/native-messaging-hosts/`. No sudo required.

### Windows (PowerShell)

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install-native-host.ps1
```

Installs to `%LOCALAPPDATA%\Vestibule\usher.exe` and registers under
`HKCU\Software\Mozilla\NativeMessagingHosts\com.vestibule.usher`. No
admin elevation required.

## Load the extension in LibreWolf

1. Open LibreWolf (or Firefox — the steps are identical).
2. Navigate to `about:debugging#/runtime/this-firefox`.
3. Click **Load Temporary Add-on...**.
4. Select `extension/manifest.json`.
5. Open the Browser Console (`Ctrl+Shift+J`).
6. Verify these lines appear:

```
[vestibule] background loaded, version 1.2.2
[vestibule] admin wizard: Ctrl+Shift+V or gear icon
[vestibule] usher hello: usher 1.2.2
```

If `[vestibule] usher hello` does not appear, usher failed to connect.
Re-run the install script and restart LibreWolf.

## Configure the kiosk

1. Press `Ctrl+Shift+V`, or move the mouse to the top 3px of the
   viewport and click the gear icon.
2. On first run, the wizard forces you to set an admin password (8+
   characters). This password gates the wizard; it is separate from
   the kiosk unlock password.
3. Walk through the six steps:
   - **Kiosk identity** — name, home URL. In safelist mode the wizard
     shows the home URL's domain and whether it is on the safelist,
     with a one-click add button.
   - **URL policy** — safelist (default: block every domain except the
     listed ones), or open / blocklist / allowlist for advanced needs
   - **Session behavior** — idle timeout (default 300s), onReset
     (default "both"), per-domain persistence allowlist
   - **Power management** — aware (default) or always-on
   - **Unlock method** — password (default); PIN selects a numeric
     unlock code; TOTP arrives with Phase 5+
   - **Review and save** — a safelist configuration whose home domain
     is not listed is refused at save time
4. Save. The new policy takes effect immediately — no restart required.

## Verify the pieces work

### Hidden menu

Navigate to any website. Move the mouse to the top 3px of the
viewport. A small dark toolbar slides down with Back, Forward,
Refresh, Home, Unlock, and Admin buttons.

### URL safelist

Until configured otherwise, the kiosk blocks every external domain.
With the default policy (safelist mode, empty list), navigate to
`https://example.org`. The navigation lands on the Vestibule block
page, which names the blocked domain. The Browser Console shows:

```
[vestibule] blocked: https://example.org/
```

Add `example.org` on wizard step 2 and navigate again — the site
loads, subdomains included. Every domain the kiosk content pulls from
(CDNs, SSO, fonts) must be listed the same way; a missing one shows
as a broken resource on an otherwise-working page, and the console
logs the exact blocked URL.

### Wake detection (Linux)

Suspend the system:

```sh
systemctl suspend
```

Wake the system. The Browser Console shows:

```
[vestibule] wake event from usher, reason: suspend
[vestibule] resetting session (reason: wake:suspend)
[vestibule] all browsing data cleared
```

### Unlock path

Click the lock icon in the hidden menu. A dedicated popup window opens
(not `window.prompt`). Enter the kiosk unlock password. If correct, the
lock overlay clears and admin grace mode activates (10 minutes of
no-reset for maintenance). If wrong, the popup shows an error.

The unlock password is verified by usher against an Argon2id hash stored
at `~/.config/vestibule/unlock.hash` (Linux) or
`%APPDATA%\Vestibule\unlock.hash` (Windows), file mode 0600. The hash
never touches browser storage.

### Optional: install usher as a system service

For crash recovery and pre-LibreWolf power monitoring:

```sh
# Linux (systemd user service)
./scripts/install-usher-service.sh
systemctl --user start vestibule-usher.service

# Windows (Scheduled Task)
powershell -ExecutionPolicy Bypass -File scripts\install-usher-task.ps1
```

### Optional: install LibreWolf overrides

For SSO and telehealth compatibility (relaxes resistFingerprinting,
enables WebGL/WebRTC/EME for patient portals):

```sh
# Linux
sudo cp config/librewolf.overrides.cfg /usr/lib/librewolf/

# Windows (run as admin)
copy config\librewolf.overrides.cfg "C:\Program Files\LibreWolf\distribution\"
```

## Troubleshooting

| Symptom | Fix |
|---|---|
| `usher hello` does not appear in console | Re-run `install-native-host.sh`; restart LibreWolf |
| `Error: Native host exited` | Check `usher` is executable (`chmod +x ~/.local/bin/usher`); run it manually to see stderr |
| Hidden menu does not appear | The content script may have failed on a specific page; check the console for `[vestibule] content script loaded` |
| Wake events do not fire on Linux | Verify D-Bus is running (`dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames`); usher logs `[usher] power: D-Bus connect failed` if not |
| Wake events do not fire on Windows | Verify usher is running (`Get-ScheduledTask -TaskName VestibuleUsher`); check Event Viewer > Windows Logs > Application for `[usher] power:` messages |

## Next steps

- Read [README.md](README.md) for the architecture and security model.
- Read [DEPLOYMENT.md](DEPLOYMENT.md) to provision a real kiosk machine
  (OS lockdown included) — the natural next step after this quickstart.
- Read [BLOG.md](BLOG.md) for the narrative behind the rewrite.
- Read [docs/QA-PASS.md](docs/QA-PASS.md) for the production readiness
  review.