# Browser extension (ChatGPT, Claude, Gemini)

The extension checks text **pasted or dropped** into ChatGPT (`chatgpt.com`, `chat.openai.com`),
Claude (`claude.ai`) and Gemini (`gemini.google.com`) with your own Grodmir data plane before
the page receives it. It replaces or blocks according to the signed policy. It talks to nothing
but your data plane (SPEC §14 Phase 6).

What it does **not** cover (the product reports these as unprotected): typed text, other sites,
other browsers, mobile apps, and anything the user does outside Chrome/Edge. Pasted files and
images are blocked, because they cannot be inspected. Pasted rich text is reduced to plain text.

## Fail closed, never silent

A paste is blocked with a message (Polish, German or English, following the browser language)
when the data plane is unreachable, the key is wrong, the extension is not configured, the answer
is not understood, the text is too large, the clipboard cannot be read, or **the page layout is
not recognised** (no known prompt box on a chat page). The last case is also reported per site
to the panel ("Browser extension coverage"): a site shows *PAGE LAYOUT NOT RECOGNISED* until the
extension is updated.

## 1. Data plane

Create a dedicated key that has only the `inspect` scope (it cannot reach any model provider):

```sh
uv run aiguard key-create --keys keys.yaml --id browser-ext --kind service --scope inspect
```

In a control-plane managed environment create the key in the panel/API with
`"scopes": ["inspect"]` instead. Allow the extension's origin in `config.yaml` (exact id, no
wildcards):

```yaml
extension_origins:
  - chrome-extension://abcdefghijklmnopabcdefghijklmnop
```

The key is held by the browser profile, so treat it as low-privilege and rotate it like any
other (Q-041). Use HTTPS for the data plane; plain `http` is accepted by the extension only for
`localhost` and `127.0.0.1`.

## 2. Build and publish the extension

```sh
make extension-test      # unit and static tests (Node)
make extension           # dist/aiguard-extension.zip
```

Upload the zip to the Chrome Web Store (unlisted) or Edge Add-ons, or host it yourself as a CRX
with an update manifest. The extension id is fixed by the store or by your signing key; use it in
`extension_origins` and in the policies below.

## 3. Force-install and configure through browser policy

Do not write the policies by hand. `aiguard extension-policy` generates them for Windows
(a merging PowerShell script), macOS (a configuration profile), Linux, and the Google Admin
console. Its `--check` option tests the gateway, the key and the origin first. Follow
[Rolling out the browser extension](https://grodmir.com/en/integrations/chatgpt-browser#rollout). That page also covers key
rotation, incognito and guest modes, other browsers, and what the helpdesk tells employees.

Managed values (`gatewayUrl`, `apiKey`, `supportContact`) always override the options page.
With managed values present, the options page hides the evaluation form and shows only the
status, the help contact and **Test connection**. The extension follows policy changes without
a restart.

## 4. Local network access

- Chrome for Testing 139 refused the service worker's request to a loopback gateway
  (`LocalNetworkAccessPermissionDenied`).
- Chrome for Testing 156 and Debian Chromium 156 allow it (2026-10-29: the real-browser test
  runs with Chrome's default settings, and `make extension-policy-e2e` reaches a private-address
  gateway).
- The generated policies also allow the extension's own origin in
  `LocalNetworkAccessAllowedForUrls`, `LocalNetworkAllowedForUrls` and
  `LoopbackNetworkAllowedForUrls`, for older versions (Q-043).

## Testing

```sh
make extension-test            # Node: logic, manifest and "no other network" checks
make extension-e2e             # real Chrome for Testing, look-alike pages, live gateway
```

`make extension-policy-e2e` (Docker) installs the extension only through a generated policy on
Chromium 156 and checks the Windows script against a simulated registry.

`extension-e2e` needs Chrome for Testing (`AIGUARD_CHROME` or `~/.cache/puppeteer`) because
branded Chrome ignores `--load-extension`. The pages mimic the three sites under their real host
names; the real sites were **not** exercised (Q-042). Update `browser-extension/src/sites.js`
when a site changes its markup, and check the real sites before each release.

The real-browser fixture test uses reserved `example.com`, `example.org` and `example.net`
hosts mapped to loopback in a temporary extension copy. This avoids HTTPS upgrades of real
provider domains; shipped selectors and event handlers are unchanged. It also exercises text
dropped onto non-editable elements. Passing fixtures does not verify live sites or MDM/LNA.
