# Codex Edge Browser Bridge

A personal Microsoft Edge extension that gives a local Codex session on-demand access to tabs, bookmarks, and ordinary web-page content. The extension's toolbar switch is the authority: Codex cannot turn access on, and every browser-data tool is unavailable while the switch is off.

> [!WARNING]
> This is an experimental, local-only bridge for a browser profile you control. While ON, Codex can read supported existing tabs and bookmarks. Actions are restricted to tabs the bridge created during that ON session, but those tabs still share the profile's cookies and signed-in state.

## What it does

- Lists non-incognito Edge tabs and reads semantic page content while access is on.
- Lists or searches bookmarks without changing them.
- Opens URLs and bookmarks in inactive, agent-owned tabs.
- Clicks, types, scrolls, navigates, reloads, goes back, and closes only agent-owned tabs.
- Keeps existing tabs read-only.
- Returns to off after Edge, the extension service worker, or the native host restarts.

The bridge is on-demand. It does not watch tab changes or copy page content until Codex invokes a tool.

## Supported environment

- Ubuntu/Linux with Microsoft Edge Stable 120 or newer.
- Node.js 18 or newer and npm.
- An authenticated Codex CLI with local MCP support.

The installer currently targets Edge Stable's Linux native-messaging directory. Other Edge channels and operating systems need different manifest locations and are not supported yet.

## Quick start

```bash
git clone https://github.com/rakaar/codex-edge-browser-bridge.git
cd codex-edge-browser-bridge
npm ci
npm run check
npm run install:local
```

Then complete the one-time Edge setup:

1. Open `edge://extensions` in the Edge profile you want Codex to use.
2. Turn on **Developer mode**. If the sidebar is collapsed, open the menu in the upper-left.
3. Select **Load unpacked** and choose this repository's `dist/extension/` directory.
4. Optionally pin **Codex Edge Bridge** to the toolbar.
5. Restart Codex once and resume the same saved thread so it loads the `edge_browser` MCP server.
6. Open the extension popup and turn access ON. Approve the first-use permission prompt.

The popup should report **Access is on** and **Native host: Connected**. It always starts OFF after an Edge, extension, service-worker, or native-host restart.

## Security model

```text
Codex -> stdio MCP server -> user-only Unix socket
      -> Edge native-messaging host -> MV3 extension -> browser APIs
```

- No TCP listener and no OpenAI API key.
- The Edge native host allowlists the deterministic extension ID `jkknljmfkjdieackklpojdgfphdinnkm` and verifies the caller origin again at runtime. The manifest's `key` value is public key material used only to keep that sideloaded ID stable; it is not a private signing key or credential.
- The Unix socket lives under `$XDG_RUNTIME_DIR/codex-edge-bridge/` with mode `0600`.
- Browser content, bookmark data, URLs, and form values are never written to disk or logs by the bridge.
- Optional `tabs`, `bookmarks`, `scripting`, HTTP, and HTTPS permissions are requested only from the popup's ON gesture.
- OFF disconnects the native host and clears in-memory ownership and element references. **Turn off and revoke permissions** also removes the optional Edge permissions.
- Password, payment, OTP, file, hidden, read-only, and disabled fields cannot be typed into.
- `edge://`, extension, `file://`, data, JavaScript, incognito, and unscriptable PDF-viewer pages are rejected.
- Page content is labeled as untrusted in the MCP server instructions and must never be treated as agent instructions.

The Unix account is the local trust boundary: another process already running as the same user can connect to the socket while the bridge is ON. The bridge also cannot prevent a permitted click in an agent-owned tab from using that Edge profile's existing login state. See [SECURITY.md](SECURITY.md) for the complete threat model and review notes.

Turning off stops future reads. It cannot erase browser content already included in a Codex conversation.

## Build and verify

```bash
npm ci
npm run check
```

The build outputs:

- `dist/extension/` — unpacked Edge extension.
- `dist/native-host.cjs` — Edge native-messaging host and Unix-socket broker.
- `dist/mcp-server.mjs` — local stdio MCP server for Codex.

## Install locally

```bash
npm run install:local
```

The installer performs only these user-scoped changes:

- Copies the host binaries to `~/.local/lib/codex-edge-bridge/`.
- Writes `~/.config/microsoft-edge/NativeMessagingHosts/com.codex.edge_bridge.json`.
- Registers the local MCP server as `edge_browser` with `codex mcp add`.

The install command is idempotent for files created by this project. It refuses to overwrite an unrelated native-messaging manifest or an unrelated MCP entry named `edge_browser`.

## Updating an installation

```bash
git pull --ff-only
npm ci
npm run check
npm run install:local
```

Then click **Reload** on the extension card in `edge://extensions` and turn access ON again. Reloading deliberately resets access to OFF. Restart Codex only when the MCP registration or server bundle changed.

## MCP tools

Read-only tools:

- `edge_status`
- `edge_list_tabs`
- `edge_list_bookmarks`
- `edge_snapshot`

Agent-owned tab tools:

- `edge_open_tab`
- `edge_open_bookmark`
- `edge_click`
- `edge_type`
- `edge_scroll`
- `edge_navigate`
- `edge_go_back`
- `edge_reload`
- `edge_close_tab`

`edge_snapshot` returns normalized text, headings, links, and ephemeral element references. References expire after navigation or the next snapshot.

## Safe browser fixture

Run the local fixture without touching logged-in sites:

```bash
npm run fixture
```

It listens on `http://127.0.0.1:43119` and provides safe input, click, scroll, and navigation targets for the real Edge acceptance test.

## Project layout

- `extension/` — MV3 popup, service worker, content bridge, and tab-ownership policy.
- `native/` — Edge native-messaging framing and the user-only Unix-socket broker.
- `mcp/` — stdio MCP server and local socket client.
- `shared/` — protocol, URL policy, sensitive-field checks, and runtime paths.
- `scripts/` — reproducible build, install, uninstall, and fixture commands.
- `tests/` — unit and process-level integration tests for policy, framing, the native host, and MCP.

## Troubleshooting

- **Developer mode is not visible:** maximize `edge://extensions` or open its upper-left sidebar menu.
- **Native host is disconnected:** run `npm run install:local`, reload the unpacked extension, and turn it ON again.
- **`edge_browser` tools are missing:** restart Codex and resume the same thread; MCP configuration is read when a session starts.
- **The extension immediately returns to OFF:** open its popup and read the red error. The fail-closed behavior usually means the native host could not start or disconnected.
- **A page cannot be read:** internal Edge pages, built-in PDF pages, `file://` URLs, incognito tabs, and other unscriptable pages are intentionally unsupported.

## Uninstall

First turn the extension off. Then run:

```bash
npm run uninstall:local
```

The uninstaller removes only the matching native-host files and `edge_browser` MCP entry. Remove the unpacked extension separately from `edge://extensions`.