dcosnet
/
Vestibule
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Vestibule/QUICKSTART.md

7.0 KiB
Executable File
Raw Blame History

Quickstart

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

Prerequisites

  • LibreWolf 115+ installed (librewolf.net) — or Firefox 115+ / Firefox ESR (works identically: the extension, usher, and policies are engine-standard)
  • Rust 1.70+ installed via rustup
  • 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

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.

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

./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 -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:

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:

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

# 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 for the architecture and security model.
  • Read DEPLOYMENT.md to provision a real kiosk machine (OS lockdown included) — the natural next step after this quickstart.
  • Read BLOG.md for the narrative behind the rewrite.
  • Read docs/QA-PASS.md for the production readiness review.