2026-07-29 13:54:34 +02:00
|
|
|
|
# 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.
|
Theseus: Claude connector, an opt-in MCP server for the signed-in profile
Claude sessions could not work inside the user's own profile: the desktop
app's browser lost synthetic pastes and typing in Medium's editor, and a
browser-wide --remote-debugging-port would hand every session to any local
process. The connector is a built-in extension, off until turned on in
Settings > Extensions, that serves MCP on 127.0.0.1 behind a per-install
token and drives one tab at a time through that tab's webContents.debugger.
- Host: a "tab-control" capability (built-in add-ons only) for listing,
opening, navigating, closing and focusing tabs, handing out web tabs'
webContents (never Settings, extension or home tabs), and a toolbar chip
plus tab outline while a client is connected; the chip's X stops it.
Built-in add-ons can ship "defaultEnabled": false.
- Tools: list_tabs, open_tab, navigate, activate_tab, close_tab, screenshot,
read_page_text, snapshot (accessibility tree with refs), click, type
(insertText + real Enter), press_key, paste_html / paste_text (system
clipboard + webContents.paste, clipboard restored), upload_file
(DOM.setFileInputFiles), wait_for, and evaluate behind its own switch.
- Safety: first use of each site asks the user; password and one-time-code
fields are refused; uploads only from folders the user added; requests
from web pages or foreign Host headers are refused; every action is
logged with a timestamp in the panel and actions.log.
- Claude Desktop runs stdio-shim.cjs through the Theseus executable in Node
mode.
- Tests: unit (protocol, auth, policy, shim) and an end-to-end run on a
throwaway profile that types, pastes HTML with a heading and a link, and
uploads a PNG on a local page.
2026-10-23 17:04:03 +03:00
|
|
|
|
|
|
|
|
|
|
## 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).
|
|
|
|
|
|
|
2026-10-24 00:32:06 +03:00
|
|
|
|
**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.
|
Theseus: Claude connector, an opt-in MCP server for the signed-in profile
Claude sessions could not work inside the user's own profile: the desktop
app's browser lost synthetic pastes and typing in Medium's editor, and a
browser-wide --remote-debugging-port would hand every session to any local
process. The connector is a built-in extension, off until turned on in
Settings > Extensions, that serves MCP on 127.0.0.1 behind a per-install
token and drives one tab at a time through that tab's webContents.debugger.
- Host: a "tab-control" capability (built-in add-ons only) for listing,
opening, navigating, closing and focusing tabs, handing out web tabs'
webContents (never Settings, extension or home tabs), and a toolbar chip
plus tab outline while a client is connected; the chip's X stops it.
Built-in add-ons can ship "defaultEnabled": false.
- Tools: list_tabs, open_tab, navigate, activate_tab, close_tab, screenshot,
read_page_text, snapshot (accessibility tree with refs), click, type
(insertText + real Enter), press_key, paste_html / paste_text (system
clipboard + webContents.paste, clipboard restored), upload_file
(DOM.setFileInputFiles), wait_for, and evaluate behind its own switch.
- Safety: first use of each site asks the user; password and one-time-code
fields are refused; uploads only from folders the user added; requests
from web pages or foreign Host headers are refused; every action is
logged with a timestamp in the panel and actions.log.
- Claude Desktop runs stdio-shim.cjs through the Theseus executable in Node
mode.
- Tests: unit (protocol, auth, policy, shim) and an end-to-end run on a
throwaway profile that types, pastes HTML with a heading and a link, and
uploads a PNG on a local page.
2026-10-23 17:04:03 +03:00
|
|
|
|
|
2026-10-24 00:32:06 +03:00
|
|
|
|
**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):
|
Theseus: Claude connector, an opt-in MCP server for the signed-in profile
Claude sessions could not work inside the user's own profile: the desktop
app's browser lost synthetic pastes and typing in Medium's editor, and a
browser-wide --remote-debugging-port would hand every session to any local
process. The connector is a built-in extension, off until turned on in
Settings > Extensions, that serves MCP on 127.0.0.1 behind a per-install
token and drives one tab at a time through that tab's webContents.debugger.
- Host: a "tab-control" capability (built-in add-ons only) for listing,
opening, navigating, closing and focusing tabs, handing out web tabs'
webContents (never Settings, extension or home tabs), and a toolbar chip
plus tab outline while a client is connected; the chip's X stops it.
Built-in add-ons can ship "defaultEnabled": false.
- Tools: list_tabs, open_tab, navigate, activate_tab, close_tab, screenshot,
read_page_text, snapshot (accessibility tree with refs), click, type
(insertText + real Enter), press_key, paste_html / paste_text (system
clipboard + webContents.paste, clipboard restored), upload_file
(DOM.setFileInputFiles), wait_for, and evaluate behind its own switch.
- Safety: first use of each site asks the user; password and one-time-code
fields are refused; uploads only from folders the user added; requests
from web pages or foreign Host headers are refused; every action is
logged with a timestamp in the panel and actions.log.
- Claude Desktop runs stdio-shim.cjs through the Theseus executable in Node
mode.
- Tests: unit (protocol, auth, policy, shim) and an end-to-end run on a
throwaway profile that types, pastes HTML with a heading and a link, and
uploads a PNG on a local page.
2026-10-23 17:04:03 +03:00
|
|
|
|
|
|
|
|
|
|
```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
|
2026-10-24 00:32:06 +03:00
|
|
|
|
panel's *Claude Desktop* entry is a ready `claude_desktop_config.json` entry
|
Theseus: Claude connector, an opt-in MCP server for the signed-in profile
Claude sessions could not work inside the user's own profile: the desktop
app's browser lost synthetic pastes and typing in Medium's editor, and a
browser-wide --remote-debugging-port would hand every session to any local
process. The connector is a built-in extension, off until turned on in
Settings > Extensions, that serves MCP on 127.0.0.1 behind a per-install
token and drives one tab at a time through that tab's webContents.debugger.
- Host: a "tab-control" capability (built-in add-ons only) for listing,
opening, navigating, closing and focusing tabs, handing out web tabs'
webContents (never Settings, extension or home tabs), and a toolbar chip
plus tab outline while a client is connected; the chip's X stops it.
Built-in add-ons can ship "defaultEnabled": false.
- Tools: list_tabs, open_tab, navigate, activate_tab, close_tab, screenshot,
read_page_text, snapshot (accessibility tree with refs), click, type
(insertText + real Enter), press_key, paste_html / paste_text (system
clipboard + webContents.paste, clipboard restored), upload_file
(DOM.setFileInputFiles), wait_for, and evaluate behind its own switch.
- Safety: first use of each site asks the user; password and one-time-code
fields are refused; uploads only from folders the user added; requests
from web pages or foreign Host headers are refused; every action is
logged with a timestamp in the panel and actions.log.
- Claude Desktop runs stdio-shim.cjs through the Theseus executable in Node
mode.
- Tests: unit (protocol, auth, policy, shim) and an end-to-end run on a
throwaway profile that types, pastes HTML with a heading and a link, and
uploads a PNG on a local page.
2026-10-23 17:04:03 +03:00
|
|
|
|
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).
|