From 79d6e08ffc5b4e8fd29f79200735ef97933ba049 Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Thu, 28 May 2026 14:15:02 +0200 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20SecuBox=20Companion=20=E2=80=94?= =?UTF-8?q?=20avatar=20personas,=20selectable=20picker,=20Become=20(ref=20?= =?UTF-8?q?#409)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 read / ticked-write posture and that ciphertext never leaves the SecuBox. --- docs/wiki/SecuBox-Companion.md | 146 +++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/wiki/SecuBox-Companion.md diff --git a/docs/wiki/SecuBox-Companion.md b/docs/wiki/SecuBox-Companion.md new file mode 100644 index 00000000..41093aca --- /dev/null +++ b/docs/wiki/SecuBox-Companion.md @@ -0,0 +1,146 @@ +# ๐ŸŸ  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: + +1. Build the `.xpi`: + ```bash + cd packages/secubox-webext && ./build.sh # โ†’ ../secubox-webext-.xpi + ``` +2. `about:debugging` โ†’ **This Firefox** โ†’ **Load Temporary Add-on** โ†’ pick the + `.xpi` (or `manifest.json`). *(Temporary add-ons reset on Firefox restart.)* +3. 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//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 `` 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 `` 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 + +```bash +cd packages/secubox-webext +./build.sh # zip โ†’ ../secubox-webext-.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//` 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](Architecture-Security.md), +[Developer-Guide](Developer-Guide.md).*