Invictum Browser Bridge

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

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

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

Зачем это нужно?

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

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

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

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

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

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

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

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

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

• Перечислять, открывать, закрывать, активировать вкладки и переещаться по их истории.

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

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

• Читать компактные, струkturные (outline), полные, интерактивные или ограниченные областью семантические сники.

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

• Кликать, делать двойной клик, клик правой кнопкой, наводить курсо, фокусировать, вводить текst, нажимать клавиши, выбирать, отмечать флажки, прокручивать к элементу или позиции докуента и перетаскивать элементы (drag and drop).

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

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

• Заполнять нативные поля input, textarea, select, checkbox, radio, облаstи contenteditable и WYSIWYG-редакторы.

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

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

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

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

Поддержка WordPress

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

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

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

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

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

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

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

• использовать общие инструменты форм, загрузки, редактora, DOM, консоли и same-origin API для настрок плагинов, медиафайлов, элементов управения, подобых ACF, и пользовательских страниц админ-панели.

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

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

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

• распознавать настоящий терминал, а не пое Search Tools в WHM;

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

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

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

• блокировать отправку при сбое (fail closed), не отправлять Enter и пытаться очистить непроверенный черновик;

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

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

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

Figma в Chrome

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

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

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

• читать отрисованные строки дерева слоёв и свойства инспектора;

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

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

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

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

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

• Запросы к API страницы с того же источника (same-origin) с опциональной обработкой nonce WordPress.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Site access в значение On all sites. Это избавляет от ручного подтверждения на панели инструментов для каждого нового источника 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

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

Приветствуются issue и pull request. Держите политики, проверку, аудит, резервирование и очистку в пути Desktop Authority; не добавляйте второй маршрут управления к расширению. Перед открытием pull request пройдите все локальные проверки и следуйте CONTRIBUTING.md.

Before publishing changes, use the private-data checklist in GIT_PUBLISHING.md.

License

Invictum Browser Bridge is open-source software licensed under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies subject to the license terms.

Made by invictum.hr