Davoguha/bookmarks-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Present the repo as a scoped bookmarks API product and drop homelab-only notes.

Browse Source
This commit is contained in:
alexveley
2026-09-22 08:10:02 -04:00
parent c19e619b2f
commit cfda629418
10 changed files with 123 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+46 -12
View File
@@ -1,25 +1,59 @@
# Bookmarks API for Scripting and AI
An API add-on for Firefox to allow agentic and script-based management of user bookmarks.
An API add-on for Firefox so agents and scripts can manage your bookmarks while the browser is open.
The published product is the add-on in `extension/`. Issue a secret in **Manage clients**, store it with your secrets, and keep Firefox open so those tools can talk to this add-on.
The shipped product is the add-on in `extension/`. This is not a bookmark sync engine, and it is not a Mozilla product.
This is not a bookmark sync engine, and it is not a Mozilla product.
## What it does
## Setup
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 (temporary via `about:debugging`, or a signed `.xpi` — [docs/signing.md](docs/signing.md)).
2. Toolbar → **Manage clients** → generate a secret → store it with your secrets.
3. To let scripts call in, register the native host once (`tools/install-native-host.ps1` on this workstation).
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>`.
Authenticated calls use `Authorization: Bearer <secret>` on `http://127.0.0.1:17634`. Method list for people working in this repo: [AGENTS.md](AGENTS.md).
```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
- Binds **127.0.0.1** only. Browser `Origin` headers are rejected.
- Client hashes live in the add-on’s storage. The host asks the add-on whether a token is valid.
- Only `bookmarks.*` (plus `meta.*`). No history, cookies, tabs, or `onMessageExternal`.
- 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.
MIT. Copyright EasyGoin.