keepassgo/docs/browser-extension.md

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:

go build ./cmd/keepassgo-browser-bridge

Install a Firefox native messaging manifest:

./keepassgo-browser-bridge install-native-host --browser firefox --binary /absolute/path/to/keepassgo-browser-bridge

Install a Chromium native messaging manifest:

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