From de0814f3ed19107a934ac0596537cfa5140ee834 Mon Sep 17 00:00:00 2001 From: alexveley Date: Tue, 22 Sep 2026 07:33:35 -0400 Subject: [PATCH] Rename the add-on Bookmarks API and drop CLI copy from the product UI. --- AGENTS.md | 6 +++-- README.md | 47 +++++++---------------------------- docs/signing.md | 2 +- extension/manifest.json | 9 ++++--- extension/options.html | 11 ++++---- extension/popup.html | 2 +- tools/install-native-host.ps1 | 4 +-- 7 files changed, 27 insertions(+), 54 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ff2794e..e61fa0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,6 @@ -# Agent handshake — Firefox Agent Bridge +# Agent handshake — Bookmarks API for Scripting and AI + +Use this when working **in this repo**. The shipped product is the add-on under `extension/` only. Do not treat `tools/` as part of the listing. Use this when a script or coding agent needs to **create, update, move, or delete Firefox bookmarks while Firefox is open**. Do not edit `places.sqlite` if this bridge is reachable. @@ -15,7 +17,7 @@ If `http://127.0.0.1:17634/health` fails, the host is not up. If `/health` works This is a normal API token, not an SSH key. -1. In Firefox, open the Agent Bridge toolbar icon → **Manage clients**. +1. In Firefox, open the Bookmarks API toolbar icon → **Manage clients**. 2. Name the client (e.g. `cursor-agent`) and click **Generate secret**. 3. Copy the `fab_…` value **once**. Store it however you already store secrets: env var, Vaultwarden, `.env`, CI secret, Cursor env. 4. Give tooling only that string: diff --git a/README.md b/README.md index b5b82ec..061c90b 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,24 @@ -# Firefox Agent Bridge +# Bookmarks API for Scripting and AI -A small Firefox add-on that exposes an **allowlisted** WebExtension API to local scripts and agents — after you issue them a secret from inside Firefox. +A Firefox add-on that lets **local** scripts and agents call an allowlisted `browser.bookmarks` API — after you issue them a secret from inside the browser. -This is **not** a bookmark sync engine. Firefox already has `browser.bookmarks`. The add-on is a bridge: while Firefox is open, a script on the same machine can call those functions over `http://127.0.0.1:17634` with a Bearer token. +The published product is the add-on in `extension/`. It does not ship helper scripts. Callers use ordinary HTTP and a Bearer token, stored however they already keep secrets. -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. +This is not a bookmark sync engine, and it is not a Mozilla product. Mozilla’s add-on naming rule is “Name for Firefox,” never “Firefox Name”; this listing uses neither form in the title. ## Setup -1. Register the native host (once): +1. Register the native host once (`tools/install-native-host.ps1` on this workstation). +2. Load the add-on (temporary via `about:debugging`, or a signed `.xpi` — [docs/signing.md](docs/signing.md)). +3. Toolbar icon → **Manage clients** → generate a secret → store it with your secrets. - ```powershell - powershell -NoProfile -File tools\install-native-host.ps1 - ``` - -2. Load the add-on (`about:debugging` temporary, or a signed `.xpi` — [docs/signing.md](docs/signing.md)). - -3. Click the toolbar icon → **Manage clients** → name a client → **Generate secret**. Copy the `fab_…` token into whatever secret store you already use. - -4. Leave Firefox open. `GET http://127.0.0.1:17634/health` should return JSON. - -## Call it - -```powershell -$env:FAB_TOKEN = "fab_…" # the value from the Manage clients modal -python tools/client.py meta.methods -python tools/client.py bookmarks.search '[{"title":"10.132.x.x"}]' -``` - -`curl` works the same: `Authorization: Bearer fab_…`. +While Firefox is open, `http://127.0.0.1:17634/health` answers if the host is up. Authenticated calls use `Authorization: Bearer ` on `/v1/call`. Method list: the repo [AGENTS.md](AGENTS.md) (for people working on this codebase, not for the AMO listing). ## Security - Binds **127.0.0.1** only. Browser `Origin` headers are rejected. - Each caller is an issued token. The add-on stores a hash, not the secret. -- Only `bookmarks.*` (plus `meta.*`) in `extension/background.js`. No history, cookies, tabs, or `onMessageExternal`. - -## Pieces - -| Piece | Role | -|-------|------| -| `extension/` | Add-on, popup, Manage clients page | -| `host/` | Native host: stdio to Firefox, HTTP to scripts | -| `tools/client.py` | Bearer caller (`FAB_TOKEN`) | -| `examples/replace_named_folder.py` | Sample folder replace | +- Only `bookmarks.*` (plus `meta.*`). No history, cookies, tabs, or `onMessageExternal`. ## License diff --git a/docs/signing.md b/docs/signing.md index 38b3118..fcc4969 100644 --- a/docs/signing.md +++ b/docs/signing.md @@ -42,4 +42,4 @@ Bump `version`, sign again on the same channel and id. For unlisted self-distrib ## 5. Listed (later) -`web-ext sign --channel=listed` plus an AMO metadata JSON (name, summary, license MIT). Expect listing copy that says: local scripts only, loopback HTTP, bearer token, bookmarks allowlist. Do not claim it is a general Firefox remote-control tool. +`web-ext sign --channel=listed` plus an AMO metadata JSON (name **Bookmarks API for Scripting and AI**, license MIT). Listing copy: local scripts only, loopback HTTP, bearer token, bookmarks allowlist. Do not title it “Firefox …”. Mozilla only allows “Name for Firefox”; this add-on uses neither form. diff --git a/extension/manifest.json b/extension/manifest.json index 1ee54b1..f4ff318 100644 --- a/extension/manifest.json +++ b/extension/manifest.json @@ -1,8 +1,9 @@ { "manifest_version": 3, - "name": "Firefox Agent Bridge", - "version": "0.2.0", - "description": "Let local scripts and agents call an allowlisted WebExtension API after you issue them a secret.", + "name": "Bookmarks API for Scripting and AI", + "short_name": "Bookmarks API", + "version": "0.3.0", + "description": "Issue a secret, then let local scripts and agents call an allowlisted bookmarks API.", "browser_specific_settings": { "gecko": { "id": "firefox-agent-bridge@easygoingaming.com", @@ -14,7 +15,7 @@ "scripts": ["background.js"] }, "action": { - "default_title": "Firefox Agent Bridge", + "default_title": "Bookmarks API", "default_popup": "popup.html" }, "options_ui": { diff --git a/extension/options.html b/extension/options.html index 24f7cef..192accd 100644 --- a/extension/options.html +++ b/extension/options.html @@ -2,18 +2,18 @@ - Firefox Agent Bridge + Bookmarks API
-

Firefox Agent Bridge

-

Issue a secret to each script or agent. The add-on keeps only a hash. Put the secret in an env var, vault, or .env — whatever you already use.

+

Bookmarks API for Scripting and AI

+

Issue a secret to each client. Store it with your secrets. This add-on keeps only a hash.

- +
@@ -34,10 +34,9 @@

Copy this secret now

-

It will not be shown again. Store it the same way you store any other API token.

+

It will not be shown again. Store it with your secrets.

-

Example: set FAB_TOKEN=<secret> then python tools/client.py meta.methods

diff --git a/extension/popup.html b/extension/popup.html index 3b581e2..571b4f6 100644 --- a/extension/popup.html +++ b/extension/popup.html @@ -5,7 +5,7 @@ -

Agent Bridge

+

Bookmarks API

Checking host…

diff --git a/tools/install-native-host.ps1 b/tools/install-native-host.ps1 index 82cd91b..88891e2 100644 --- a/tools/install-native-host.ps1 +++ b/tools/install-native-host.ps1 @@ -23,7 +23,7 @@ if (Test-Path $TokenPath) { $manifest = @{ name = $HostName - description = "Firefox Agent Bridge native host" + description = "Bookmarks API native host" path = $CmdPath type = "stdio" allowed_extensions = @($ExtensionId) @@ -38,4 +38,4 @@ Write-Host "registered $regPath" Write-Host "" Write-Host "Load the add-on, then use the toolbar icon → Manage clients to generate a secret." -Write-Host "Put that fab_… token in FAB_TOKEN for scripts. Do not store it under $StateDir." +Write-Host "Store that secret with your other secrets. Do not keep it under $StateDir."