alexveley
74 lines
3.4 KiB
Markdown
74 lines
3.4 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.
|
||
|
||
**Repo:** [git.easygoingaming.com/Davoguha/bookmarks-api](https://git.easygoingaming.com/Davoguha/bookmarks-api)
|
||
|
||
The shipped product is the add-on in `extension/`. This is not a bookmark sync engine, and it is not a Mozilla product.
|
||
|
||
## Who can use this
|
||
|
||
The HTTP API listens on **127.0.0.1 only** — the same computer that is running this Firefox. A local script, an editor agent, or a session you have opened on that machine (SSH, remote desktop) can call it, if it presents a secret you issued.
|
||
|
||
It does **not** work from chatgpt.com or other sites in a browser tab. Those programs run somewhere else and cannot see this port. Pages open in Firefox are also blocked (requests that carry a browser `Origin` are rejected).
|
||
|
||
You can sit at a different computer and still use it *if* your tooling is actually running on the Firefox machine — for example you SSH in and run the client there. Pointing a remote tool at some other host’s loopback will not work.
|
||
|
||
If this Firefox profile syncs bookmarks with a Mozilla account, edits made here can appear on your other devices. Sync is Firefox’s feature; the API itself still only accepts connections on this machine.
|
||
|
||
The listen port defaults to **17634**. Change it under Manage clients if that port is already taken, and point your tools at the same port (`FAB_URL`).
|
||
|
||
## 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:<port>` (default `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.
|