Установка

Требования, запуск из исходников и десктопное приложение для macOS.

Traffic Jam можно запустить двумя способами: веб-приложение из исходников (фронтенд на Vite + API на Go) или упакованное десктопное приложение Electron для macOS arm64, которое само встраивает Go-бэкенд и управляет им.

Требования

Зависимость	Для чего нужна
Node.js и npm	Фронтенд-инструментарий, dev-сервер, сборка Electron
Go	Сборка и запуск API-бэкенда (`go run ./server`)
`mitmdump` в `PATH`	Захват трафика в реальном времени
`tshark` в `PATH`	Только для захвата пакетов в реальном времени

Бэкенд разбирает pcap/pcapng внутри процесса с помощью gopacket и расшифровывает поддерживаемые сессии TLS 1.2/1.3 из keylog-файлов NSS или блоков Decryption Secrets Blocks в pcapng. TShark не требуется для импорта захватов — он используется только в опциональном сценарии захвата пакетов в реальном времени (см. /docs/ru/capture/). Разобранные сессии сохраняются в SQLite, поэтому импортированные сессии переживают перезапуски API.

Запуск веб-приложения из исходников

Запустите API, затем фронтенд в двух терминалах:

npm ci               # or: make install
npm run dev:api      # go run ./server — listens on 127.0.0.1:8790
npm run dev:web      # Vite dev server; proxies /api to http://127.0.0.1:8790

Автономный API для разработки по умолчанию принимает запросы без capability-токена, но разрешены только браузерные origin на loopback-адресах (localhost, 127.0.0.1, ::1) и десктопный origin (traffic-jam://app); любой другой Origin отклоняется с HTTP 403.

Чтобы требовать токен, задайте TRAFFIC_JAM_API_TOKEN для API и запустите фронтенд с тем же значением в VITE_TRAFFIC_JAM_API_TOKEN. Клиенты API отправляют токен в заголовке X-Traffic-Jam-Token. Дополнительные точные origin можно внести в белый список через переменную TRAFFIC_JAM_ALLOWED_ORIGINS со значениями через запятую.

Хранилище и переменные окружения

Переменная	По умолчанию	Назначение
`TRAFFIC_JAM_ADDR`	`127.0.0.1:8790`	Адрес прослушивания бэкенда
`TRAFFIC_JAM_DB_PATH`	`.traffic-jam/traffic-jam-v2.sqlite3`	Файл базы данных SQLite
`TRAFFIC_JAM_CAPTURE_DIR`	`.traffic-jam/live-captures` (или рядом с настроенной базой данных в десктопных сборках)	Каталог артефактов захвата в реальном времени
`TRAFFIC_JAM_API_TOKEN`	не задана (dev-API работает без токена)	Capability-токен, требуемый API
`VITE_TRAFFIC_JAM_API_TOKEN`	не задана	Тот же токен, читается веб-фронтендом при сборке/разработке
`TRAFFIC_JAM_ALLOWED_ORIGINS`	не задана	Дополнительные разрешённые браузерные origin через запятую

Десктопное приложение для macOS arm64

Оболочка Electron запускает Go API на свободном порту 127.0.0.1, при каждом запуске генерирует криптографически случайный capability-токен и передаёт оба значения только своему бэкенду и рендереру через изолированный preload-мост (contextIsolation: true, nodeIntegration: false). Бинарник бэкенда включён как дополнительный ресурс; в режиме разработки оболочка использует dist-electron/backend/traffic-jam-api, если он существует, и откатывается на go run ./server. Упакованное приложение дополняет PATH значением PATH из login-оболочки плюс типовыми расположениями Homebrew, такими как /opt/homebrew/bin, поэтому mitmdump, установленный через Homebrew, находится без дополнительной настройки. База данных SQLite хранится в пользовательском каталоге данных приложения (traffic-jam-v2.sqlite3).

Запуск локально (собирает фронтенд и бэкенд для macOS arm64, затем запускает Electron):

npm run desktop:dev

Упаковка и релиз

make pack          # or: npm run desktop:pack — unpacked .app in release/mac-arm64/
make dist          # or: npm run desktop:dist — DMG, ad-hoc codesigned for local use
make release-signed SIGN_IDENTITY='Developer ID Application: Your Name (TEAMID)'
make version VERSION=1.2.3   # set package.json version before packaging

make dist создаёт DMG с ad-hoc подписью (electron-builder identity: null плюс ad-hoc скрипт afterPack), пригодный для локального использования; make release-signed требует действующий сертификат Developer ID в связке ключей и быстро завершается ошибкой, если SIGN_IDENTITY пуст. Все десктопные артефакты записываются в release/.

[!NOTE] Приложения с ad-hoc подписью вызывают предупреждение Gatekeeper на других машинах. Для использования другими людьми распространяйте DMG, подписанный Developer ID, из make release-signed.

Цели Makefile

Цель	Описание
`make install`	`npm ci`
`make check`	Линт + тесты логики + тесты Go
`make check-ui`	`make check` + тесты отрисованного UI и axe
`make test-e2e`	Изолированный браузерный smoke-тест Playwright
`make test-electron`	Изолированный smoke-тест запуска Electron для macOS arm64
`make build-all`	Фронтенд + бэкенд для macOS arm64
`make pack`	Распакованный `.app`
`make dist`	DMG (ad-hoc codesign)
`make release-signed`	DMG с подписью Developer ID (`SIGN_IDENTITY=…`)
`make clean`	Удалить каталоги `dist`, `dist-electron`, `release` и вывода Playwright

[!TIP] Типичный локальный поток проверки — make install check build-all перед make pack или make dist. Браузерные тесты один раз устанавливают Chromium через npx playwright install chromium; и браузерные, и Electron-тесты используют изолированные базы данных и каталоги пользовательских данных, поэтому они никогда не затрагивают обычное состояние разработчика.

[!WARNING] Traffic Jam предназначен для авторизованного тестирования систем, которые вам разрешено тестировать. Replay, зондирующие мутации и генерация тестовых JWT-токенов (включая токены alg=none и RS-to-HS) отправляют реальные запросы — направляйте их только на цели, которые вам разрешено оценивать.