Invictum Browser Bridge

Открытый контроль браузера для ИИ-агентов, созданный для разработчиков.

Invictum Browser Bridge (IBB, также называемый Invictum Browser Gate или IBG) позволяет авторизованному ИИ-агенту работать в существующем профиле Google Chrome пользователя. Агент может использовать уже авторизованные веб-приложения без экспорта файлов cookie, паролей, профилей браузера или исходного состояния аутентификации.

Проект распространяется под лицензией MIT License. Он предназначен для локальной разработки и продвинутых браузерных рабочих процессов через MCP, CLI, TypeScript SDK или loopback API управления.

Видеодемонстрация

Смотреть полную демонстрацию Invictum Browser Bridge на YouTube, чтобы увидеть, как ИИ-агент работает внутри реального профиля Chrome, понимает публичный веб-сайт семантически, перемещается по его содержимому, тестирует мобильный viewport и создаёт полноэкранные и аннотированные скриншоты, сохраняя управляемую вкладку видимой и явно зарезервированной.

Related MCP server: browser-control

Зачем это использовать?

Большинство браузерной автоматизации запускает чистый профиль браузера или полагается на хрупкие координаты экрана. IBB вместо этого предоставляет типизированные действия с проверкой политик внутри реального профиля Chrome пользователя:

• семантическое чтение страниц и детерминированные ссылки на элементы;

• фоновое управление вкладками, не прерывающее пользователя;

• специализированные адаптеры для WordPress, терминалов WHM/cPanel и Figma;

• надёжные формы, редакторы форматированного текста/кода, загрузки, диалоги, скриншоты и инструменты отладки;

• явная авторизация, резервирование вкладок, User Stop, редактируемые данные аудита и гарантированная очистка.

Установленное расширение сообщает о своих точных возможностях во время выполнения. Агенты всегда должны вызывать system.capabilities вместо того, чтобы предполагать, что документация и загруженная сборка Chrome идентичны.

Основные возможности

Управление браузером и страницами

• Список, открытие, закрытие, навигация, активация и перемещение по истории вкладок.

• Работа в выделенном окне агента и в фоновых вкладках по умолчанию.

• Ожидание URL-адресов, заголовков, текста, селекторов, стабильности DOM или готовности приложения; фокусировка лениво отображаемой вкладки только один раз, когда ограниченное фоновое ожидание доказывает, что фокусировка необходима.

• Чтение компактных, обзорных, полных, интерактивных или ограниченных семантических снимков.

• Извлечение чистого текста или лёгкого Markdown и поиск элементов с помощью детерминированного ранжирования на естественном языке.

• Клик, двойной клик, клик правой кнопкой, наведение, фокусировка, ввод текста, нажатие клавиш, выбор, установка флажков, прокрутка к элементу или позиции документа, перетаскивание.

• Использование координатных кликов только как запасного варианта, привязанного к ревизии.

Формы, редакторы, файлы и аутентификация

• Установка значений в нативных input, textarea, select, checkbox, radio, contenteditable и WYSIWYG-редакторах.

• Синхронизация авторитетных моделей редакторов CodeMirror, Ace, Monaco, Quill, TinyMCE, Gutenberg и подобных, чтобы значения сохранялись после отправки.

• Прикрепление одного или нескольких локальных файлов через нативный API выбора файлов Chrome без раскрытия путей в результатах или журналах аудита.

• Отправка форм только с требуемой авторизацией, включая явно авторизованный путь без запроса для уже одобренной инструкции агента.

• Использование предварительно заполненных форм входа, эфемерной HTTP Basic Auth и нативных диалогов JavaScript alert, confirm, prompt и beforeunload через специальные действия.

Поддержка WordPress

IBB включает типизированные рабочие процессы WordPress вместо того, чтобы просить агентов импровизировать с косметическими изменениями DOM или перетаскиванием координат:

• определение экранов wp-admin, уведомлений, таблиц списков, строк и доступных действий;

• выполнение действий над строками и массовых действий с точными ключами действий WordPress;

• чтение и обновление содержимого Gutenberg или Classic Editor, заголовка, отрывка, слага, статуса, категорий, тегов, метаданных избранного изображения и других поддерживаемых полей;

• отдельный просмотр изменений от сохранения и проверка авторитетной модели редактора после сохранения;

• проверка и редактирование классических деревьев Внешний вид > Меню, включая пользовательские ссылки, обновления, удаления, перемещения полных поддеревьев, вложенность, порядок и сохранение;

• безопасное восстановление, когда запрос WordPress о несохранённых изменениях блокирует навигацию;

• возврат к общим инструментам форм, загрузки, редактора, DOM, консоли и API того же источника для настроек плагинов, медиа, элементов управления типа ACF и пользовательских страниц администрирования.

См. WordPress wp-admin и классическое редактирование меню.

WHM, cPanel и браузерные терминалы

Типизированный адаптер xterm поддерживает браузерные терминалы, такие как WHM/cPanel Terminal:

• обнаружение реального терминала вместо поля Search Tools в WHM;

• чтение ограниченного, редактируемого буфера xterm или одного локального WebSocket терминала для действия;

• фокусировка только вспомогательного ввода терминала и отправка доверенного текста или специальных клавиш в фоновой вкладке;

• подготовка и проверка точной команды перед отправкой одного Enter;

• отказ по умолчанию, удержание Enter и попытка очистить непроверенный черновик;

• ожидание приглашения, текста, изменения вывода или тихого состояния;

• возврат явной проверки черновика и доставки без записи необработанных команд или вывода.

Вывод терминала относится к R2, а каждое текстовое/клавишное действие — к R3. Запрос только на чтение никогда не авторизует команду. См. автоматизация терминала.

Figma в Chrome

Типизированные действия Figma могут проверять интерфейс браузера вокруг файла дизайна:

• проверка работоспособности ожидаемых якорей интерфейса Figma;

• чтение имени файла, страниц, текущего режима и текущего выделения;

• чтение отображаемых строк дерева слоёв и свойств инспектора;

• выбор страницы, режима или видимого слоя с защитой от устаревших строк;

• использование скриншотов для холста WebGL.

Figma виртуализирует своё дерево слоёв и рисует холст дизайна с помощью WebGL, поэтому этот адаптер намеренно не заявляет о полной мутации документа. См. поддержку Figma.

Диагностика разработчика и визуальный вывод

• Ограниченный, редактируемый захват консоли и диагностика сети только с метаданными.

• Запросы к API страницы того же источника с необязательной обработкой nonce WordPress.

• Обратимая эмуляция мобильного viewport, ориентации, DPR и сенсорного ввода.

• Скриншоты viewport, элемента, области и полной страницы.

• Обучающие скриншоты с прямоугольниками, эллипсами, стрелками, подписями и автоматическими нумерованными наложениями set-of-marks.

• Проверка элементов/слушателей/источников, ограниченное наблюдение за событиями, типизированные мутации DOM и инлайн-стилей, обратимое внедрение CSS и ограниченный экспорт PDF.

• Явно авторизованный необработанный JavaScript страницы как крайняя мера R3; чувствительные поверхности, навигация, отправка и неограниченные сетевые запросы остаются запрещёнными.

• Пакетные операции с сохранением политик, пробные запуски, ключи идемпотентности, пост-снимки, семантические дельты DOM, проверка и перемещение устаревших ссылок.

Интеграции с агентами

IBB предоставляет четыре локальные поверхности для разработчиков:

Транспорт Native Host на 127.0.0.1:47821 принадлежит исключительно Desktop Authority. Агенты не должны подключаться к расширению или этому порту напрямую.

Сервер в настоящее время предоставляет 54 действия браузера во время выполнения и 61 инструмент MCP. Это число является снимком релиза, а не контрактом агента: вызывайте invictum_capabilities во время выполнения.

Модель безопасности

• Desktop Authority — единственная граница политик и аудита.

• Каждое действие классифицируется как R0-R3; чувствительные действия требуют соответствующего явного утверждения авторизации.

• Вкладка резервируется перед работой, видимо помечается идентификатором агента и освобождается в finally. Пользователь может немедленно остановить контроль.

• Ссылки на элементы привязаны к ревизиям документа и DOM.

• Снимки редактируют чувствительные значения; загрузки, команды терминала, учётные данные, текст подсказок и тела ответов не записываются в журналы аудита.

• Внутренние страницы браузера, расширения, DevTools, Chrome Web Store, локальные файлы и другие ограниченные поверхности остаются недоступными.

• Фоновая работа — по умолчанию. Агенты не должны запрашивать активацию на переднем плане, если приложение действительно этого не требует.

• Доступ отладчика ограничен вкладкой и ограничен по времени. Постоянные адаптеры освобождают свою аренду при остановке, сбросе, разблокировке, навигации или очистке после сбоя.

IBB не раскрывает файлы cookie, сохранённые пароли, данные автозаполнения, произвольное хранилище браузера, неограниченные загрузки, пассивные тела запросов/ответов, перехват трафика, доверенный ввод на уровне ОС или удалённое управление.

Прочтите SECURITY.md и POLICY_CONFIGURATION.md перед расширением поверхности действий.

Архитектура

AI agent
  |  MCP / CLI / TypeScript SDK / local control API
  v
Desktop Authority :47820
  |  policy -> validation -> reservation -> audit -> cleanup
  v
Native Host -> private loopback WebSocket :47821
  v
Chrome MV3 extension -> typed page/CDP adapters -> authorized tab

См. ARCHITECTURE.md для границ доверия и транспортных контрактов.

Требования

• Windows 11 x64

• Google Chrome 120+

• Node.js 22+

• pnpm 11

• Git

Репозиторий в настоящее время поставляет установку для разработчиков на основе исходного кода, а не подписанный пакет Chrome Web Store или производственный установщик.

Быстрый старт

git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
Set-Location .\ai-invictum-browser-bridge
$env:CI = 'true'
pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm test
pnpm lint

Загрузите apps/extension/dist через chrome://extensions как распакованное расширение, скопируйте сгенерированный ID расширения, затем зарегистрируйте Native Host:

.\scripts\register-native-host-dev.ps1 -ExtensionId "PASTE_EXTENSION_ID"
pnpm browser ping
pnpm browser capabilities

Установите Доступ к сайтам расширения Chrome на На всех сайтах. Это позволяет избежать ручного одобрения на панели инструментов для каждого нового HTTP(S) источника; политика Chrome и собственная модель авторизации Bridge по-прежнему применяются.

Полные инструкции приведены в INSTALL_WINDOWS.md и EXTENSION_INSTALL.md.

Установка с ИИ-агентом на Windows

Скопируйте приведённую ниже подсказку в доверенный ИИ-агент кодирования, имеющий доступ к PowerShell на компьютере с Windows. Агент может установить и собрать локальную среду выполнения, но Chrome требует несколько видимых действий пользователя для распакованного расширения. Поэтому подсказка точно указывает агенту, когда нужно приостановиться и направить пользователя.

Desktop Authority — это локальный процесс, который принимает команды агента на 127.0.0.1:47820; Native Host ретранслирует между ним и расширением Chrome на 127.0.0.1:47821. Поддерживаемая установка не создаёт постоянную службу Windows. MCP и CLI запускают Desktop Authority как скрытый локальный демон при необходимости, а Chrome запускает зарегистрированный Native Host. Не открывайте ни один из этих портов и не создавайте правило брандмауэра.

Install Invictum Browser Bridge from the public repository on this Windows PC:

https://github.com/invictumhr/ai-invictum-browser-bridge.git

Your goal is to install the complete supported local chain:

AI client -> MCP/CLI -> Desktop Authority -> Native Host -> Chrome extension

Work autonomously wherever PowerShell can do the work. Guide me step by step
only for actions Chrome requires me to perform manually. Explain each manual
step in one short message, wait for my confirmation or the extension ID, and
then continue. Do not ask me to execute commands that you can safely execute.

Safety rules:

1. Use only the public repository above and the scripts checked into it.
2. Do not request, copy, print, or store Chrome passwords, cookies, tokens,
   browser-profile files, or browsing data.
3. Do not disable Chrome security, install an unrelated extension, expose a
   loopback port, create a firewall rule, or bind any service publicly.
4. Do not invent a Windows Service or Scheduled Task. This project intentionally
   auto-starts Desktop Authority through MCP/CLI and lets Chrome start the Native
   Host.
5. Do not overwrite an existing checkout. If the target directory exists,
   inspect its Git remote and working tree first. Continue only if it is this
   repository and existing changes are safe; otherwise choose a new directory.
6. Avoid administrator elevation unless a missing prerequisite genuinely
   requires it. Native Host registration itself is per-user under HKCU.
7. Never work around a failed test, Chrome permission, or Native Messaging
   error. Diagnose it and preserve the security model.

Perform these phases:

PHASE 1 — Preflight

- Use PowerShell.
- Check Windows version and availability/versions of Git, Google Chrome,
  Node.js, npm/Corepack, and pnpm.
- Require Node.js 22 or newer and pnpm 11. Use the pnpm version declared in the
  repository package.json.
- If a prerequisite is missing, explain what is missing. Install it through an
  official source or winget only when installation is within my request; report
  any UAC/manual step before continuing.
- Resolve a normal per-user installation directory. Default to
  %USERPROFILE%\invictum-browser-bridge unless I already selected another path.

PHASE 2 — Clone, inspect, install, and build

- Clone the repository with:
  git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
- Enter the repository and verify that origin points to that repository.
- Read README.md, INSTALL_WINDOWS.md, EXTENSION_INSTALL.md, SECURITY.md, and
  AGENT_USAGE.md before installation.
- Run the repository secret scan before installation.
- Set CI=true for the install and run:
  pnpm install --frozen-lockfile
  pnpm build
  pnpm typecheck
  pnpm test
  pnpm lint
- Stop and diagnose any failed gate. Do not continue with a partial build.
- Resolve and show me the exact absolute folder I will need in Chrome:
  <repository>\apps\extension\dist
- Copy that folder path to the Windows clipboard if possible.

PHASE 3 — Guide me through loading the Chrome extension

Pause and ask me to do exactly this:

1. Open Google Chrome and go to chrome://extensions.
2. Turn on Developer mode in the top-right corner.
3. Click Load unpacked.
4. Select the exact apps\extension\dist folder you resolved above.
5. Confirm that Invictum Browser Controller appears and is enabled.
6. Copy its 32-character extension ID and send only that ID back to you.

Do not guess or hardcode the extension ID. Validate that the value I provide
matches Chrome's unpacked-extension ID format before using it.

PHASE 4 — Register the local Native Host

- From the repository root, run:
  .\scripts\register-native-host-dev.ps1 -ExtensionId "THE_ID_I_PROVIDED"
- Confirm that the script created the per-user Native Messaging registration
  for com.invictum.browser_bridge and did not expose a network port.
- If the Windows C# compiler needed by the checked-in launcher is unavailable,
  report that exact blocker; do not download or execute an unverified launcher.

PHASE 5 — Finish Chrome configuration

Pause and guide me through these steps:

1. Return to chrome://extensions.
2. Click Reload on Invictum Browser Controller once.
3. Open Details for the extension.
4. Set Site access to On all sites.
5. Confirm the extension remains enabled and has no current error.
6. Optionally pin its toolbar icon so the ON/AI status and settings are easy to
   see.

Explain that On all sites prevents a new manual approval for every HTTP(S)
domain, but does not bypass Chrome policy, restricted pages, User Stop, or IBB's
own authorization rules. Wait for my confirmation before testing.

PHASE 6 — Start and verify the bridge

- Run pnpm browser health.
- Run pnpm browser ping. The CLI should automatically start Desktop Authority
  as a hidden local daemon if it is offline.
- Run pnpm browser capabilities.
- Verify that Desktop Authority is reachable only through 127.0.0.1:47820, the
  private Native Host transport uses 127.0.0.1:47821, nativeConnected is true,
  and the loaded extension returns its runtime capabilities.
- Treat runtime capabilities as authoritative. The current source expects 54
  browser actions and the built MCP server expects 61 tools, but do not hide a
  mismatch or force those numbers if the checked-out release differs.
- If the badge briefly shows ON and disconnects, diagnose Desktop Authority,
  the HKCU Native Messaging manifest, its allowed extension ID, the built Native
  Host paths, and extension errors. Rebuild/reregister/reload only the component
  that is stale.
- Do not ask for a second extension reload unless extension files or its Native
  Host registration actually changed.

PHASE 7 — Configure AI clients

- Ask whether I want global IBB/IBG discovery for installed AI clients. If yes,
  run:
  powershell -ExecutionPolicy Bypass -File
  .\scripts\install-agent-discovery.ps1
- This should preserve unrelated Codex, Cursor, and Claude configuration.
- Tell me to start a new AI-agent session after MCP registration changes.
- Verify with a harmless request that performs only IBB ping and capabilities;
  do not open a browser tab for this verification.

PHASE 8 — Final report

Report:

- repository installation path and checked-out revision;
- Node.js and pnpm versions;
- build/typecheck/test/lint results;
- Chrome extension ID and loaded dist path (the ID is not a secret);
- Native Host registration status;
- Desktop Authority health and nativeConnected state;
- runtime action count and MCP tool count;
- which AI clients were configured;
- whether any manual action or known limitation remains.

Do not claim success until ping and capabilities work through the normal local
authority. Do not use a temporary test harness that takes over port 47821.

Настройка ИИ-агентов

После pnpm build установите регистрации MCP и правила триггеров для поддерживаемых локальных агентов:

powershell -ExecutionPolicy Bypass -File .\scripts\install-agent-discovery.ps1

Фразы use IBB, use IBG, use Invictum Browser Bridge и use Invictum Browser Gate (а также их хорватские эквиваленты) выбирают этот Bridge. Начните новую сессию агента после изменения регистрации MCP.

См. конфигурацию MCP, обнаружение агентов и компактный контракт триггеров агента.

Рекомендуемый рабочий процесс агента

ping -> capabilities -> open/navigate in background -> identify agent -> wait
     -> outline/snapshot -> find -> typed action -> verify -> unlock in finally

Предпочитайте типизированные действия и семантические ссылки. Используйте скриншоты для визуального понимания, координаты — только как запасной вариант, а необработанный JavaScript — только когда пользователь явно авторизовал его и никакое более безопасное типизированное действие не может решить задачу.

Полное руководство по эксплуатации — AGENT_USAGE.md.

Документация

Начните с индекса документации. Важные руководства включают:

• Разработка и контроль качества

• Устранение неполадок

• WordPress wp-admin

• Классические меню WordPress

• Автоматизация терминала WHM/cPanel

• Figma в Chrome

• Загрузка файлов

• Продвинутые DOM, CSS, события и JavaScript

• Скриншоты и аннотации для обучающих материалов

• Аутентификация и нативные диалоги

• Эргономика MCP

Структура репозитория

apps/
  cli/           JSON CLI and authority auto-start
  desktop/       policy/audit authority and loopback control API
  extension/     Manifest V3 Chrome controller
  mcp/           stdio MCP adapter
  native-host/   Native Messaging stdio <-> private local WebSocket
packages/
  agent-sdk/     control client and reserved-tab lifecycle helpers
  audit-log/     redacted audit contract and development sink
  policy-engine/ fail-closed action classification
  protocol/      strict IBP schemas and factories
  shared-types/  transport-neutral contracts
tests/
  fixtures/      deterministic local browser pages
  integration/   emulated transport and real-Chrome smoke tests

Участие в разработке

Приветствуются issues и pull request'ы. Оставляйте политику, валидацию, аудит, резервирование и очистку в пути Desktop Authority; не добавляйте второй контур управления расширением. Запустите полный набор локальных проверок перед открытием pull request и следуйте CONTRIBUTING.md.

Используйте структурированные формы GitHub для сообщений об ошибках и запросов новых функций. Прочитайте SUPPORT.md для получения рекомендаций по диагностике и CODE_OF_CONDUCT.md перед участием. Проблемы безопасности должны сообщаться через приватный отчет об уязвимостях, а не через публичный issue.

Перед публикацией изменений воспользуйтесь чек-листом приватных данных в GIT_PUBLISHING.md.

Лицензия

Invictum Browser Bridge — это программное обеспечение с открытым исходным кодом, распространяемое по лицензии MIT. Вы можете использовать, копировать, изменять, объединять, публиковать, распространять, сублицензировать и продавать копии в соответствии с условиями лицензии.

Сделано invictum.hr