# 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 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/` 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 ``` On Linux desktop builds, KeePassGO now refreshes the user-scoped native messaging manifests on launch. That automatic update always installs the Firefox manifest and also installs Chrome or Chromium manifests when it finds an installed `KeePassGO Browser` extension in that browser profile. The Arch package also ships the extension assets under `/usr/share/keepassgo/browser-extension/`. 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": ""`. 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. Paste an API token scoped for browser login lookup and credential copy. Chromium / Chrome: 1. Load a Chromium manifest based on `browser/extension/manifest.chromium.json`, or install the published extension when that distribution exists. 2. Start KeePassGO once so it can refresh the native host manifest for the discovered extension id. 3. Configure the API token in the extension settings page. ## Current Browser Flow - The extension checks sign-in pages in the background and caches per-tab match state instead of waiting for the popup to be opened first. - The toolbar badge shows when KeePassGO found matches for the current page. - Username and password fields get an inline KeePassGO affordance that opens a candidate chooser anchored to the focused field and keeps fills scoped to that field's form when possible. - If a fill request needs user approval, the extension keeps the pending state visible in both the page affordance and the popup until KeePassGO resolves it, using the token-scoped pending-approval count from the local gRPC API. ## Search And Matching User story: - When a page has no obvious match, the popup still lets the user search the vault without leaving the browser. - Search results must stay scoped to what the current API token can actually access. - Browser matching must treat common KeePass data conventions as real browser targets, not just the primary `URL` field. - Users who prefer narrow suggestions can ask the extension to show only the strongest match quality returned by KeePassGO. Expected behavior: - The popup exposes a `Search Vault` field that queries KeePassGO directly. - Search results use the same fill path as page matches. - Search never leaks entries outside the token's authorized group scope. - A browser match can come from: - the primary `URL` field - scheme-less host values such as `gitlab.com` - custom URL fields such as `URL1`, `URL2`, and similar KeePass-style URL slots - The extension settings page exposes `Best match only`. - When `Best match only` is enabled, page suggestions and popup search results only show the strongest quality band returned by KeePassGO. ## Locked Vault Workflow User story: - When the current page has a login form but KeePassGO is locked, the browser must still make that state visible on the page and in the popup. - Unlocking KeePassGO should not require the user to reopen the popup multiple times or reload the page before the extension becomes usable again. Expected behavior: - The popup shows a locked-state message instead of silently falling back to "no matches." - The inline page affordance stays visible on login forms while KeePassGO is locked and tells the user to unlock the vault. - After the vault is unlocked, the extension rechecks the page automatically and turns the locked affordance back into live matches without requiring a page reload. ## Save And Update Workflow User story: - After the user submits a login form, the browser extension should help store that credential instead of forcing the user back into KeePassGO manually. - If KeePassGO already has a matching entry for that site and username, the popup should offer an update. - If the user is creating a new login, the popup should let the user save it into a relevant vault group without leaving the browser. Expected behavior: - Submitted login forms queue a pending browser save/update state for the active tab. - The popup shows that pending save/update state prominently instead of hiding it behind page matches alone. - When KeePassGO finds an exact browser match for the submitted username and site, the popup offers an `Update` action for that entry. - When there is no exact entry match, the popup offers a `Save` action using a relevant group path from the current page matches or a user-selected search result. - The browser save/update action writes through KeePassGO's existing secure gRPC mutation API and stays scoped to the browser token's allowed groups. For extension-side regression checks, run: ```bash node --test browser/extension/background.test.cjs browser/extension/content.test.cjs ``` For a reproducible real-browser Chromium validation harness, run: ```bash make browser-extension-validate ``` That target: - validates the Firefox flow by default with a temporary addon install - can also validate Chromium with `make browser-extension-validate BROWSER=chromium` - builds the native messaging bridge - starts a stub KeePassGO gRPC server and a local login page - drives the browser through inline match discovery, approval visibility, and fill completion If validation fails, the script preserves its temporary workspace path so the captured HTML, screenshots, logs, and native-host files can be inspected. ## 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