# 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.