Add browser extension gRPC bridge

2026-04-11 00:52:01 -07:00
parent 885d599db1
commit c017308aa1
23 changed files with 2437 additions and 280 deletions
@@ -0,0 +1,76 @@
+# Browser Extension
+
+KeePassGO browser integration uses:
+
+- the existing local gRPC API in KeePassGO
+- API tokens for authorization
+- a tiny native messaging host for browser-to-gRPC transport adaptation
+
+The browser extension does **not** talk to vault files directly.
+
+## Security Model
+
+- KeePassGO remains the source of truth for authentication, authorization, approvals, and audit events.
+- The browser extension stores the gRPC address and API token in browser extension storage.
+- The native messaging host receives the token on each request from the extension.
+- The native messaging host uses the token only to attach `authorization: Bearer ...` metadata to the local gRPC request.
+- The native messaging host does not persist the token to disk.
+
+The native messaging host is therefore part of the trusted client for that browser profile. Scope the API token accordingly.
+
+## RPCs Used
+
+The browser integration uses:
+
+- `GetSessionStatus`
+- `FindBrowserLogins`
+- `GetBrowserCredential`
+
+The browser feature intentionally stays on the same secure gRPC surface used by other trusted automation.
+
+## Native Host
+
+Build the bridge:
+
+```bash
+go build ./cmd/keepassgo-browser-bridge
+```
+
+Install a Firefox native messaging manifest:
+
+```bash
+./keepassgo-browser-bridge install-native-host --browser firefox --binary /absolute/path/to/keepassgo-browser-bridge
+```
+
+Install a Chromium native messaging manifest:
+
+```bash
+./keepassgo-browser-bridge install-native-host --browser chromium --binary /absolute/path/to/keepassgo-browser-bridge --extension-id <your-extension-id>
+```
+
+Chrome and Chromium require the actual extension id in the native host manifest.
+
+## Extension Setup
+
+Firefox:
+
+1. Load `browser/extension/manifest.firefox.json` as a temporary add-on or package it as an extension.
+2. Open the extension settings page.
+3. Set the KeePassGO gRPC address, usually `127.0.0.1:47777`.
+4. Paste an API token scoped for browser login lookup and credential copy.
+
+Chromium / Chrome:
+
+1. Load `browser/extension/` with `manifest.chromium.json`.
+2. Note the extension id the browser assigns.
+3. Install the native host manifest with that extension id.
+4. Configure the gRPC address and API token in the extension settings page.
+
+## Required Token Scope
+
+At minimum, the browser token should have policy rules allowing:
+
+- `list_entries` for the groups you want the browser to search
+- `copy_username` for entries the browser may fill
+- `copy_password` for entries the browser may fill
+- `copy_url` for entries the browser may confirm against page URL