Joe Julian
97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
## Default Listener
|
|
|
|
On desktop KeePassGO listens on a Unix socket by default:
|
|
|
|
- primary location: under the user runtime directory
|
|
- fallback: `/run/user/<uid>` if present
|
|
- final fallback: a private directory under the system temp directory
|
|
|
|
Override the listener with `-grpc-addr` or `KEEPASSGO_GRPC_ADDR`, for example:
|
|
|
|
```bash
|
|
KEEPASSGO_GRPC_ADDR=tcp://127.0.0.1:47777 ./keepassgo
|
|
```
|
|
|
|
## 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-key-file /path/to/chromium-extension-public-key.txt
|
|
```
|
|
|
|
Chrome and Chromium require the actual extension id in the native host manifest. KeePassGO can derive that id from the Chromium manifest public key so you do not have to type it separately.
|
|
|
|
For a fixed Chromium ID:
|
|
|
|
1. Keep a stable Chromium extension signing key outside the repo.
|
|
2. Add the corresponding public key to the Chromium manifest as `"key": "<base64-public-key>"`.
|
|
3. Use the same public key with `install-native-host --extension-key-file ...` so the native host manifest is locked to that stable extension ID.
|
|
|
|
## 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. Leave the gRPC address blank to use the local default Unix socket, or set an explicit address if you overrode the listener.
|
|
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
|