211 lines
7.0 KiB
Markdown
Executable File
211 lines
7.0 KiB
Markdown
Executable File
# 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.
|