Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
Guide de test (FR) — Cloud Bridge : enregistrement et approbation du navigateur
Guide pas à pas pour installer l'extension en mode développeur et tester la feature de bout en bout. Pour la description technique du protocole, voir cloud-bridge-browser-approval.md.
Schémas
Architecture
flowchart LR
subgraph Browser["Navigateur de l'utilisateur (Chrome)"]
direction TB
S["Settings → Bridge<br/>URL · token · nom du navigateur"]
ST[("chrome.storage.local<br/>url, token, browserId, installationId")]
BG["Background (cloud-runs.js)<br/>lit la config, exécute les cloud_*"]
OFF["Offscreen (cloud-bridge.js)<br/>socket WebSocket + état d'approbation"]
AG["Agent WebBrain<br/>+ permissions navigate / click…"]
TAB["Onglets web<br/>(sessions de l'utilisateur)"]
S --> ST --> BG
BG -- "cloud-bridge-start + identité" --> OFF
OFF -- "commandes approuvées" --> BG
BG --> AG --> TAB
end
subgraph Backend["Backend (aujourd'hui : ws:// en local uniquement)"]
SRV["Serveur WebSocket<br/>prouve le token, vérifie la preuve du navigateur<br/>approuve / refuse"]
end
OFF <== "WebSocket initié par l'extension" ==> SRV
Échange de messages
sequenceDiagram
participant E as Extension (offscreen)
participant B as Backend
participant U as Utilisateur
E->>B: connexion WebSocket
E->>B: hello {auth.nonce, navigateur, version, plateforme, capabilities}
B-->>E: auth_challenge {nonce serveur, preuve HMAC(token)}
alt preuve du serveur invalide
Note over E: rien n'est envoyé, socket fermée, nouvel essai avec délai croissant
else preuve du serveur valide
E->>B: auth_response {preuve HMAC(token), browserId, installationId}
end
alt preuve du navigateur invalide
B-->>E: connection_rejected
Note over E: socket fermée, pas de reconnexion auto
else preuve du navigateur valide
B-->>E: connection_pending
B->>E: cloud_run (avant approbation)
E-->>B: ok:false, connection_not_approved (403)
B->>U: demande de validation du navigateur
U-->>B: approuve
B-->>E: connection_approved
B->>E: cloud_run {task}
E-->>B: runId, status running
Note over E: l'agent agit dans le navigateur
E-->>B: needs_user_input (permission navigate)
B->>E: cloud_respond {answer: once}
B->>E: cloud_status {runId}
E-->>B: status completed + résultat
end
Note over E,B: coupure réseau → nouvelle socket → nouveau hello et nouveau challenge → repart en pending
1. Prérequis
- Node.js 22 ou plus (
node -v) - Google Chrome (ou Chromium)
- Le dépôt, sur la branche de la feature :
cd ~/Documents/webbrain
git checkout feat/cloud-bridge-browser-approval
npm ci --ignore-scripts # une seule fois, installe les dépendances de dev
2. Installer l'extension en mode développeur
L'extension Chrome est directement chargeable depuis src/chrome (pas de build nécessaire).
- Ouvrir
chrome://extensions. - Activer Mode développeur (interrupteur en haut à droite).
- Cliquer sur Charger l'extension non empaquetée.
- Sélectionner le dossier
~/Documents/webbrain/src/chrome(celui qui contientmanifest.json). - WebBrain apparaît dans la liste. Épingler l'icône dans la barre d'outils si besoin.
Après chaque modification du code : sur
chrome://extensions, cliquer sur l'icône ↻ de WebBrain, puis recharger la page Settings.
Firefox
- Ouvrir
about:debugging#/runtime/this-firefox. - Charger un module complémentaire temporaire… et choisir
~/Documents/webbrain/src/firefox/manifest.json. - Ouvrir les préférences de WebBrain (
about:addons→ WebBrain → Préférences, ou la page Settings du panneau latéral) et aller dans l'onglet Cloud Bridge. Le reste du guide (serveur de test, scénarios A à F) est identique.
Le module est temporaire : il disparaît au redémarrage de Firefox. Sur Firefox, la socket vit dans la page d'arrière-plan (pas de document offscreen) ; pour déboguer, about:debugging → WebBrain → Inspecter.
Alternative (copie construite) : npm run build:chrome génère build/chrome, à charger de la même façon.
3. Lancer le serveur de test local
Dans un terminal (le laisser ouvert) :
cd ~/Documents/webbrain
node examples/cloud-bridge-approval-server.mjs --token dev-token
Vous devez voir : Listening on ws://127.0.0.1:17374/extension.
Options : --port 17374 (défaut), --auto-approve (approuve automatiquement, pratique pour tester les commandes), --legacy-bearer (accepte aussi l'ancien hello qui contenait le token, voir le scénario G).
Ce terminal sert à la fois de backend (il affiche tout ce que l'extension envoie, préfixé par <-) et de console d'approbation.
4. Configurer l'extension
- Ouvrir les Settings de WebBrain (clic droit sur l'icône → Options, ou la roue dentée du panneau latéral).
- Aller dans l'onglet Cloud Bridge.
- Remplir :
- Backend WebSocket URL :
ws://127.0.0.1:17374/extension(seulws://en local est accepté) - Cloud Bridge token :
dev-token(le même que--tokendu serveur) - Browser name : par exemple
mon-chrome(optionnel ; sinon l'ID d'installation sert de nom)
- Backend WebSocket URL :
- Cliquer sur Save & test connection (cela active aussi l'interrupteur).
Le statut passe à : Connected — waiting for the backend to approve this browser.
Dans le terminal du serveur, vous voyez le hello reçu, puis la réponse au challenge, par exemple :
{"type":"hello","client":"webbrain-extension","protocolVersion":2,
"capabilities":["saved_workflows_v1","run_modes_v1","scheduled_jobs_v1"],
"auth":{"type":"challenge","method":"hmac-sha256-v1","nonce":"…"},
"browser":{"name":"Chrome","version":"…"},"extensionVersion":"38.0.13","platform":"Linux", …}
{"type":"auth_response","method":"hmac-sha256-v1","proof":"…","browserId":"mon-chrome","installationId":"…"}
Le token n'apparaît jamais : le serveur prouve d'abord qu'il le connaît (auth_challenge), puis l'extension envoie sa propre preuve avec browserId et installationId.
5. Scénarios à tester
A. Commande avant approbation (doit être refusée)
Dans le terminal du serveur, taper :
send {"id":"1","action":"cloud_status","payload":{"runId":"x"}}
Réponse attendue (affichée par le serveur) :
{"id":"1","ok":false,"error":"Connection not approved","code":"connection_not_approved","status":403}
B. Approbation, puis commande
approve
Le statut dans Settings devient Connected and approved. (il se rafraîchit toutes les 2 s). Puis :
send {"id":"2","action":"cloud_status","payload":{"runId":"x"}}
Réponse attendue : "ok":false,"error":"Unknown cloud run." — c'est normal, le run x n'existe pas ; ce qui compte est que la commande a atteint WebBrain (plus de connection_not_approved).
Pour lancer un vrai run, voir le format existant de cloud_run dans la doc technique (même payload qu'avant la feature).
C. Refus
Dans le terminal : reject. Le statut devient Rejected by the backend: …, la socket est fermée et l'extension ne se reconnecte plus toute seule. Pour réessayer : Save & test connection.
D. Reconnexion
- Arrêter le serveur (Ctrl+C) puis le relancer : l'extension se reconnecte automatiquement (délai croissant, jusqu'à 30 s).
- Elle renvoie un
helloavec un nouveau nonce, refait le challenge, et la connexion est de nouveau en attente : toute commande est refusée tant que vous n'avez pas retapéapprove.
Note connue : juste après une reconnexion, le texte de statut de la page Settings peut rester sur « approved » alors que la connexion est repassée en attente ; les commandes sont bien refusées. Cliquer sur Save & test connection pour resynchroniser l'affichage.
E. Mauvais token
Mettre un autre token dans Settings puis Save & test connection : la preuve du serveur ne correspond plus, l'extension ferme la socket sans rien envoyer d'autre et affiche Connection error: Bridge controller failed authentication. Elle réessaie ensuite avec un délai croissant (jusqu'à 30 s), sans jamais passer en approved.
F. Mode historique (sans token)
Vider le champ token et sauvegarder : plus aucune approbation n'est exigée, le comportement est celui d'avant la feature (serveur MCP local inchangé). Le serveur de test ne l'acceptera pas (il exige un token) ; ce mode se teste avec le serveur MCP du dépôt (mcp-server/). Attention : sans token, n'importe quel programme qui écoute le premier sur le port configuré peut piloter le navigateur.
G. Ancien hello avec token (déprécié)
Pour un backend qui n'implémente pas encore le challenge : lancer le serveur avec --legacy-bearer, puis dans la console du service worker chrome.storage.local.set({webbrainCloudBridgeLegacyBearerAuth: true}). Le hello contient alors de nouveau "auth":{"type":"bearer","token":"dev-token"}. Sans ce drapeau, l'extension n'envoie jamais le token. Le retirer ensuite : chrome.storage.local.remove('webbrainCloudBridgeLegacyBearerAuth').
6. Inspecter / déboguer
- Console du service worker :
chrome://extensions→ WebBrain → service worker → Console. - Voir la config stockée (même console) :
chrome.storage.local.get(null, v => console.log(
Object.fromEntries(Object.entries(v).filter(([k]) => k.startsWith('webbrainCloudBridge')))))
- Statut du bridge : dans cette console,
chrome.runtime.sendMessage({target:'background', action:'cloud_bridge_status'}).then(console.log)— renvoieapproval(not_required | pending | approved | rejected), jamais le token. - Repartir de zéro :
chrome.storage.local.remove(['webbrainCloudBridgeToken','webbrainCloudBridgeBrowserId','webbrainCloudBridgeInstallationId','webbrainCloudBridgeEnabled']).
Problèmes fréquents :
| Symptôme | Cause probable |
|---|---|
| Backend unreachable | Le serveur n'est pas lancé, mauvais port, ou URL autre que ws://127.0.0.1/localhost |
| Rien ne change après modification du code | Extension non rechargée (↻ sur chrome://extensions) |
| Reste « Rejected » | Normal : pas de reconnexion auto après un refus, cliquer sur Save & test connection |
| Connection error: Bridge controller failed authentication | Le token du serveur diffère de celui de Settings, ou un autre programme occupe le port |
| Rejected by the backend: Invalid token avec un ancien backend | Le backend attend encore le token dans le hello : l'adapter au challenge, ou scénario G |
| Port 17374 déjà utilisé | Un serveur MCP tourne déjà : l'arrêter ou utiliser --port (et changer l'URL dans Settings) |
7. Tests automatisés
npm run test:cloud-bridge-approval # Chrome + Firefox : hello, challenge, faux serveur sur le port, mauvais token, pending, approved, rejected, commande avant/après, reconnexion, minuteur annulé après refus, mode sans token, drapeau historique, identité unique, e2e vs serveur d'exemple
node test/run.js # suite complète existante (≈ 2400 tests)
8. Bonnes pratiques de sécurité pour vos essais
- Utilisez un token de test (
dev-token), jamais une vraie clé API de provider : le token du Cloud Bridge est distinct. - Le token est stocké en clair dans
chrome.storage.localmais n'est jamais envoyé sur la socket (sauf avec le drapeau historique du scénario G). - Le serveur d'exemple est un outil de test local, pas un backend de production.
9. Test réel : lancer une vraie tâche (cloud_run)
Pré-requis côté WebBrain : un provider LLM configuré (onglet Providers, avec sa clé API) et un onglet web ouvert (le run s'exécute dans l'onglet actif). Les permissions habituelles de WebBrain s'appliquent comme pour un utilisateur humain.
Avec le serveur d'exemple, après approve :
run Ouvre example.com et dis-moi le titre de la page
status # liste les runs
status run_xxxxx # état d'un run (l'id est dans la réponse de cloud_run)
run <texte> envoie {"action":"cloud_run","payload":{"task":"<texte>","mode":"act"}} ; la réponse contient un runId et status: "running". Interrogez ensuite avec cloud_status. Si l'agent pose une question (pendingInput), répondez avec send {"id":"r1","action":"cloud_respond","payload":{"runId":"run_xxxxx","clarifyId":"…","answer":"…"}} ; cloud_abort (payload: {"runId":"…"}) interrompt le run.
Avec votre propre backend
Votre backend doit :
- Écouter en WebSocket sur une URL
ws://127.0.0.1/localhost/::1(l'extension se connecte vers lui). Un backend distant n'est pas accepté tel quel : utilisez un relais local ou voyez la décision « URL localhost uniquement » dans la doc technique. - À la réception du
hello, répondreauth_challengeavec son propre nonce et sa preuve HMAC, puis vérifier la preuve de l'auth_response(calcul exact dans la doc technique, section « Messages »). Ensuite seulement répondre{"type":"connection_pending"}puis, après validation côté utilisateur,{"type":"connection_approved"}(ouconnection_rejected). L'extension ignore toute approbation reçue avant que le serveur ait prouvé le token. - Envoyer ensuite les commandes
{"id","action","payload"}et lire les réponses{"id","ok","result"|"error"}.