CyberMind-FR
79d6e08ffc
Document the persona model: a named, browser-encrypted group of site sessions the operator picks from a tick-list of their live logins, reapplied with one Become click on any same-LAN box. Explains the <all_urls> read / ticked-write posture and that ciphertext never leaves the SecuBox.
6.0 KiB
🟠 SecuBox Companion (Firefox WebExtension)
Browser companion for a SecuBox appliance — live status, quick access, credential relay, and an on-box, client-encrypted session vault. Package:
secubox-webext· Issues: #401, #402, #409
🟠 AUTH (credentials/login) · 🟢 ROOT (system metrics) — the Companion
touches several modules but lives in the AUTH family because its core job is
brokering browser authentication to the box.
What it does
| Surface | What you get |
|---|---|
| Toolbar popup | Module health dots, quick links, a badge with the down-count |
| Quick metrics | Live CPU / RAM / Disk / Temp (/api/v1/system/metrics), red ≥ 90% |
| Login sync | "Sync browser logins" — relays your live cookies to the avatar broker for backend services (e.g. YouTube → PeerTube import) |
| Avatar personas | Group several site sessions under a named persona, encrypted in the browser; reapply a persona with one Become click to quick-switch profiles on your own boxes |
Everything talks to your SecuBox over your LAN and rides the SSO-lite session (#400). Nothing is published off-box.
Install (development / self-hosted)
Firefox requires signing for permanent installs, so for a self-hosted box:
- Build the
.xpi:cd packages/secubox-webext && ./build.sh # → ../secubox-webext-<ver>.xpi about:debugging→ This Firefox → Load Temporary Add-on → pick the.xpi(ormanifest.json). (Temporary add-ons reset on Firefox restart.)- Toolbar icon → Settings → set Hub base URL
(e.g.
https://admin.gk2.secubox.in) → Save.
For a permanent install: sign with web-ext sign (AMO) or run Firefox
Developer/ESR with xpinstall.signatures.required=false.
Features
Status + metrics
The popup polls each configured module's /api/v1/<module>/health and
/api/v1/system/metrics. The background event-page refreshes a toolbar badge
every 5 min (the down-module count).
Login sync (avatar peek/poke broker)
"Sync browser logins" reads your live cookies for each service the avatar
broker registers (GET /api/v1/avatar/cred/peek) and pokes them to
POST /api/v1/avatar/cred/poke/{service}. For youtube the box installs them
into the PeerTube LXC (via a root path-unit, no sudo — see #407) so yt-dlp
import can use your session.
Avatar personas (client-encrypted) 🟠 AUTH
A persona is the avatar wearing a named set of site sessions — a group of logins you can save once and reapply on your own boxes.
- A passphrase you type in the popup derives an AES-GCM key (PBKDF2,
200 000 iters, WebCrypto). Sessions are encrypted in the browser before
upload. The avatar module stores opaque ciphertext only under
/var/lib/secubox/avatar/vault/(0700) — it never sees plaintext or the key. - Pick what's in it — open edit under the persona and the popup lists the
sites you're currently signed into (with cookie counts). Tick the ones the
persona should hold; your selection is remembered (
vaultDomains). You can also type a site to add it. - Save persona encrypts + uploads the ticked group under the persona name.
- Become decrypts the whole group locally with your passphrase and
cookies.set()s every site back at once — a one-click profile quick-switch. Run it on another machine on the same LAN and that box adopts the persona's logins (passwordless), without the sessions ever leaving the SecuBox.
🔒 The passphrase never leaves the browser. Lose it and the personas are unreadable (by design).
Settings (about:addons → options, or popup → Settings)
| Field | Meaning |
|---|---|
| Hub base URL | Your dashboard, no trailing slash |
| Modules | Comma-separated slugs to monitor |
| Cookie endpoint | Avatar poke endpoint (default /api/v1/avatar/cred/poke/youtube) |
vaultDomains (the persona selection) is stored in extension storage and is
managed from the popup picker (Avatar persona → edit) — no manual editing
needed. The manifest grants <all_urls> so the picker can list every site
you're signed into; ticking is what scopes a persona.
Security model
- LAN/SSO only — never expose the avatar webui / vault on clearnet. A public cookie vault is a total-account-compromise target.
- Client-side encryption — the box stores ciphertext; a server breach yields unreadable blobs.
- Broad read, narrow write — the persona picker needs
<all_urls>to list the sites you're signed into, but only the sites you tick are ever encrypted and uploaded. Nothing is captured silently; selection is the gate. Manifest V3. - Auth — API calls send the SecuBox Bearer token (popup login) and ride the
SSO-lite cookie (#400). Backend endpoints are
require_jwt.
YouTube import note
YouTube blocks server IPs ("Sign in to confirm you're not a bot") and now
requires a PO token (SABR). The Companion relays your browser's cookies (and,
experimentally, a captured PO token) so the box uses your good session instead
of fighting from its flagged IP. If imports still fail, the box IP needs a
cooldown / fresh cookies — your workstation's yt-dlp is the reliable fallback.
Build a distributable XPI
cd packages/secubox-webext
./build.sh # zip → ../secubox-webext-<ver>.xpi
# permanent install: web-ext sign (needs AMO API creds)
Troubleshooting
| Symptom | Fix |
|---|---|
| All dots grey / "Set the hub URL" | Settings → set Hub base URL |
| "SecuBox login required" | Enter your SecuBox user/pass in the popup |
| Module red but it's up | Its /api/v1/<m>/ route must be in secubox-routes.d/ |
| "Restore failed (wrong passphrase?)" | Re-enter the exact vault passphrase |
| Persona list empty | Save a persona with at least one ticked, logged-in site first |
See also: Architecture-Security, Developer-Guide.