# Theseus Navigator

The browser — the consumer face of the stack. Native `.bch` support with the
resolver built in, so a user installs **one app** instead of modifying their
operating system. Named for the thread through the labyrinth: the chain is the
thread.

## Scope
- Electron shell (Chromium engine, no forking): tabs, address bar, history.
- **In-process `.bch` resolution** — no system daemon, no NRPT, no OS
  trust-store changes; reuses `bns.js` from the BNS repo as a library.
- Record handling: `h` render, `ip` connect, `p`/`s3` via in-app gateway,
  `u` redirect.
- **TLS via cert-verify hook** (Electron `setCertificateVerifyProc`) against the
  BNS root / on-chain `tls` fingerprints — no OS store touched.
- **Provenance indicator**: shows whether a page came from the chain / Sia / a
  direct server, with NFT category and record type — the decentralized padlock.

## Status: not started
Build it in its own session/repo. The ready-to-paste brief is
**`BROWSER-PROMPT.md`** (a reference copy in this folder; canonical source is
`D:\Dev\NameCoin\BROWSER-PROMPT.md` — if they diverge, NameCoin wins). It points
here and reuses the resolver core. `theseus.bch` is registered and should
eventually serve the browser's own homepage over the protocol it implements.

## Roadmap
[BUILD-ROADMAP.md](../BUILD-ROADMAP.md) Stage 5.

## Claude connector (MCP)
A built-in extension, **off by default**, that lets Claude Code or Claude
Desktop on the same computer work in your signed-in Theseus tabs: open and
read pages, click, type into rich editors, paste formatted text, upload
files. Design: [DESIGN-claude-connector.md](DESIGN-claude-connector.md).

**Turn it on.** Settings › Extensions › Claude connector. Its panel opens by
itself the first time; later it is the connector icon in the toolbar dock.
It shows the address, the token, the approved sites, the upload folders and
a live log of every action.

**Connect Claude.** In the panel, click **Connect** next to Claude Code or
Claude Desktop. Theseus registers itself in that app's own configuration
(Claude Code through its `claude mcp` command, user scope; Claude Desktop in
`claude_desktop_config.json`, backup kept beside it) and keeps the entry
current: the token changes whenever the connector stops or is revoked, and
the entry follows. **Remove** takes it out again. Claude Desktop needs a
restart after a change; a running Claude Code session picks it up with `/mcp`.

**By hand**, if you prefer (panel › *Set up by hand*), the same entry for
Claude Code is (once; `--scope user` makes it available in every project):

```bash
claude mcp add --scope user --transport http theseus http://127.0.0.1:47800/mcp --header "Authorization: Bearer <token from the panel>"
```

Check it with `claude mcp list`. **Claude Desktop** speaks stdio only; the
panel's *Claude Desktop* entry is a ready `claude_desktop_config.json` entry
that runs `stdio-shim.cjs` through the Theseus executable itself
(`ELECTRON_RUN_AS_NODE=1`), so nothing else needs installing.

**What protects you**
- Listens on `127.0.0.1` only, behind a random 256-bit token. Requests from
  web pages (any `Origin` header) and foreign `Host` headers are refused.
  No `--remote-debugging-port`: each tab is driven through its own
  `webContents.debugger`.
- Theseus asks the first time Claude acts on each site (*Allow*, *Until
  Theseus restarts*, *Don't allow*). Approved sites are listed in the panel.
- Never types or pastes into password or one-time-code fields.
- Uploads only from folders you add in the panel (none by default).
- `evaluate` (arbitrary page JavaScript) is a separate switch, off by default.
- A **Claude** chip in the toolbar shows while a client is connected, and the
  tabs it controls get a dashed outline. The chip's ✕ stops the connector at
  once; *Revoke token* in the panel issues a new token, cutting off every
  configured client.

**Tools:** `list_tabs`, `open_tab`, `navigate`, `activate_tab`, `close_tab`,
`screenshot`, `read_page_text`, `snapshot` (accessibility tree with element
refs), `click`, `type`, `press_key`, `paste_html`, `paste_text`,
`upload_file`, `wait_for`, and `evaluate` while allowed.

**Tests**

```bash
node tests/claude-connector-unit.test.mjs
```

```bash
node tests/claude-connector.test.mjs
```

The second starts this checkout on a throwaway profile (`THESEUS_USER_DATA`,
`THESEUS_NO_UPDATE_CHECK`) and drives a local test page over MCP: typing into
a contenteditable editor, `paste_html` with a heading and a link, a PNG upload,
and the refusals (password fields, a file outside the upload folder, no token,
a browser origin).