alexveley
70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# 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` | Signed Python caller (`FAB_KEY_FILE`) |
|
|
| `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 registers
|
|
`HKCU\Software\Mozilla\NativeMessagingHosts\com.easygoingaming.firefox_agent_bridge`.
|
|
|
|
Then create a client key **outside** that state directory and give the file to tooling:
|
|
|
|
```powershell
|
|
python tools\register_client.py add --name cursor-agent --write-key $HOME\.fab\cursor-agent.json
|
|
$env:FAB_KEY_FILE = "$HOME\.fab\cursor-agent.json"
|
|
```
|
|
|
|
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: Mozilla-signed `.xpi` — [docs/signing.md](docs/signing.md). Start with `--channel=unlisted`.
|
|
|
|
3. Leave Firefox open. The extension starts the host; `GET http://127.0.0.1:17634/health` should return JSON.
|
|
|
|
## Call it
|
|
|
|
```powershell
|
|
$env:FAB_KEY_FILE = "$HOME\.fab\cursor-agent.json"
|
|
python tools/client.py meta.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**. Browser `Origin` headers are rejected; `Host` must be loopback.
|
|
- Calls (except `/health`) must be signed by a **registered Ed25519 client**. The host keeps public keys only.
|
|
- Only the methods in `extension/background.js` `ALLOWED` run. No history, cookies, tabs, or `onMessageExternal` in v0.1.
|
|
- Another add-on with `bookmarks` already has Places; this bridge does not give it a new path in.
|
|
|
|
## License
|
|
|
|
MIT.
|