Initial Firefox Agent Bridge: allowlisted bookmarks RPC for local scripts.

2026-09-22 06:24:31 -04:00
commit 6dcf068365
11 changed files with 690 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Firefox Agent Bridge
+
+A small Firefox extension that exposes an **allowlisted** WebExtension API to local scripts and agents.
+
+This is **not** a bookmark sync engine. Firefox already has `browser.bookmarks`. The extension is a bridge: while Firefox is open, a script on the same machine can call those functions over `http://127.0.0.1:17634`.
+
+Agents: start at [AGENTS.md](AGENTS.md).
+
+## Why this exists
+
+Firefox will not let an outside process talk to Places. Editing `places.sqlite` while the browser is running loses deletes. The supported path is `browser.bookmarks` inside an extension, plus [native messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) so a localhost HTTP host can reach that extension.
+
+## Pieces
+
+| Piece | Role |
+|-------|------|
+| `extension/` | WebExtension (`bookmarks` + `nativeMessaging`) |
+| `host/` | Native host: stdio to Firefox, HTTP to scripts |
+| `tools/client.py` | Stdlib Python caller |
+| `examples/replace_named_folder.py` | Sample "replace this folder" script |
+
+## Install (this workstation)
+
+1. Register the native host (once):
+
+   ```powershell
+   powershell -NoProfile -File tools\install-native-host.ps1
+   ```
+
+   That writes `%LOCALAPPDATA%\firefox-agent-bridge\token` and
+   `HKCU\Software\Mozilla\NativeMessagingHosts\com.easygoingaming.firefox_agent_bridge`.
+
+2. Load the extension. Firefox Release will not keep an unsigned add-on across restarts:
+
+   - `about:debugging#/runtime/this-firefox`
+   - **Load Temporary Add-on**
+   - pick `extension\manifest.json`
+
+   Permanent install later = AMO-signed (unlisted is enough).
+
+3. Leave Firefox open. The extension starts the host; `GET http://127.0.0.1:17634/health` should return JSON.
+
+## Call it
+
+```powershell
+$token = Get-Content $env:LOCALAPPDATA\firefox-agent-bridge\token -Raw
+curl.exe -s -H "Authorization: Bearer $token" http://127.0.0.1:17634/v1/methods
+python tools/client.py bookmarks.search "[{\"title\":\"10.132.x.x\"}]"
+```
+
+See [AGENTS.md](AGENTS.md) for the method list, HTTP surface, and failure modes.
+
+## Security
+
+- Binds **127.0.0.1 only**.
+- Every mutating call (and most reads) needs `Authorization: Bearer <token>`.
+- Only the methods in `extension/background.js` `ALLOWED` run. No history, cookies, or tabs in v0.1.
+
+## License
+
+MIT.