alexveley
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# Bookmarks API for Scripting and AI
|
||
|
||
An API add-on for Firefox so agents and scripts can manage your bookmarks while the browser is open.
|
||
|
||
The shipped product is the add-on in `extension/`. This is not a bookmark sync engine, and it is not a Mozilla product.
|
||
|
||
## What it does
|
||
|
||
Scripts and local agents call a loopback HTTP API. The add-on performs only `browser.bookmarks` operations (create, search, move, delete, and related reads). It does not read tabs, history, cookies, or the open web.
|
||
|
||
1. Load the add-on.
|
||
2. Toolbar → **Manage clients** → generate a secret → store that secret yourself.
|
||
3. Register the native host once if scripts should call in (`tools/install-native-host.ps1` on Windows).
|
||
4. Keep Firefox open. Call `http://127.0.0.1:17634` with `Authorization: Bearer <secret>`.
|
||
|
||
```http
|
||
POST /v1/call
|
||
Authorization: Bearer fab_…
|
||
Content-Type: application/json
|
||
|
||
{"method": "bookmarks.search", "args": [{"title": "Research"}]}
|
||
```
|
||
|
||
```text
|
||
set FAB_TOKEN=fab_…
|
||
python tools/client.py meta.methods
|
||
python tools/client.py bookmarks.search "[{\"title\":\"Research\"}]"
|
||
```
|
||
|
||
Method list and failure modes: [AGENTS.md](AGENTS.md). Signing for Firefox Release: [docs/signing.md](docs/signing.md).
|
||
|
||
## Permissions
|
||
|
||
| Permission | Why |
|
||
|------------|-----|
|
||
| `bookmarks` | The only WebExtension API this add-on calls |
|
||
| `storage` | SHA-256 hashes of issued client secrets |
|
||
| `nativeMessaging` | The only inbound path from local scripts (Mozilla does not allow a raw listening socket in the extension) |
|
||
|
||
It does **not** request `tabs`, `history`, `cookies`, `<all_urls>`, `webRequest`, or `runtime.onMessageExternal`.
|
||
|
||
## Security
|
||
|
||
- HTTP binds **127.0.0.1** only. Requests with a browser `Origin` header are rejected.
|
||
- The native host may talk only to this add-on’s gecko id.
|
||
- The add-on stores **hashes**, not secrets. Revoke from Manage clients.
|
||
- Both the host and the add-on allowlist the same `meta.*` / `bookmarks.*` methods.
|
||
|
||
See [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md).
|
||
|
||
## What this is not
|
||
|
||
- Not bidirectional bookmark sync
|
||
- Not a general Firefox remote-control surface
|
||
- Not a reason to edit `places.sqlite` while Firefox is running
|
||
|
||
## License
|
||
|
||
MIT. Copyright EasyGoin.
|