mkdev

Настоящий HTTPS для локальной разработки — с TUI и расшариванием в LAN.

mkdev запускает доверенный HTTPS на *.local. Один Go-бинарник: центр сертификации (CA) + обратный прокси + /etc/hosts + mDNS-вещание + полноценный TUI.

Что отличает его от других:

• Расшаривание в LAN. Пометьте маршрут как общий и заходите на https://app.local с телефона или любого устройства в той же Wi-Fi-сети.
• TUI, а не просто CLI. Живая таблица маршрутов, журналы запросов, просмотр сертификатов, проверка здоровья. mkdev без аргументов сразу открывает TUI.
• Ужесточённая граница привилегий. Проверки владельца, прав на запись и символических ссылок для sudo-хелпера перед любым вызовом с повышением привилегий (internal/safeexec). Никакой подмены через PATH, никаких group-writable лазеек.
• Выпуск сертификатов по SNI. Листовые сертификаты выдаются по запросу и ограничены явным списком разрешённых knownHost. Не wildcard, не предзаготовленные.

Что делает

mkdev install                    # CA + trust + daemon service + menu bar autostart
mkdev add myapp localhost:3000   # routes https://myapp.local → localhost:3000
curl https://myapp.local         # 200 from your local app

install — разовая операция: генерирует CA, заносит его в системное хранилище доверия, устанавливает и включает пользовательский сервис демона (launchd / systemd), регистрирует автозапуск панели в строке меню при входе в систему и сразу запускает панель при наличии GUI-сессии. Демон владеет прокси; TUI (mkdev без аргументов) и mkdev add | remove | list общаются с ним через ~/.mkdev/daemon.sock.

Расшаривание в LAN

Фирменная функция mkdev. Расшарьте маршрут на любое устройство в той же Wi-Fi-сети с настоящим TLS — без предупреждений и туннельных сервисов.

1. Во вкладке Domains в TUI выберите маршрут и нажмите s, чтобы переключить колонку SHARE в LAN.
2. Маршрут анонсируется через mDNS как <name>.local → LAN-IP этой машины.
3. На телефоне / втором ноутбуке откройте https://<name>.local. После того как устройство один раз доверится CA mkdev, предупреждений не будет.

Ограничения

• По mDNS вещаются только маршруты .local. Другие TLD тоже проксируются, но недоступны в LAN по имени.
• Корпоративный / облачный Wi-Fi часто блокирует multicast. Домашний и офисный Wi-Fi работают.
• Переключение s происходит на лету — mDNS-анонс и ACL со стороны LAN обновятся при следующем запросе. Без перезапуска.
• Не расшаренные маршруты отдают 403 на запросы не с loopback как дополнительный уровень защиты.
• Любой в LAN может обращаться к вашим расшаренным маршрутам. Не включайте это в недоверенном Wi-Fi.

Установка

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

Обновление позже:

brew update
brew upgrade mkdev

Go

go install github.com/venkatkrishna07/mkdev/cmd/mkdev@latest

Обновление до конкретной версии:

go install github.com/venkatkrishna07/mkdev/cmd/[email protected]

Прямая загрузка

Готовые бинарники для macOS (Intel + Apple Silicon), Linux (amd64 + arm64) и Windows (amd64) публикуются на странице релизов. Каждый релиз включает checksums.txt и бесключевую подпись cosign (checksums.txt.sig + .pem) — команду проверки см. в SECURITY.md#verifying-releases.

На macOS, если Gatekeeper блокирует бинарник, скачанный напрямую:

xattr -d com.apple.quarantine ./mkdev

Из исходников

git clone https://github.com/venkatkrishna07/mkdev.git
cd mkdev
task build
cp bin/mkdev ~/bin/        # or /usr/local/bin

Требуется Go 1.25+.

Первый запуск

mkdev install   # CA, trust, daemon service, bar autostart — one command
mkdev           # launch TUI

После install демон работает в фоне, а в строке меню появляется панель (macOS, Linux GNOME/KDE, Windows). Панель показывает статус демона, список маршрутов и переключатели включения / расшаривания в LAN для каждого маршрута; Quit закрывает панель, не останавливая демон.

Панель в строке меню

Панель — это постоянно доступный UI. Она живёт в системном трее и общается с демоном через ~/.mkdev/daemon.sock. Запускается при входе в систему (автозапуск регистрируется install); также запускается в foreground командой mkdev bar.

Что показывает:

• Цветовая точка статуса — зелёная: работает, красная: не работает, жёлтая: проверка, серая: выключено. Отражает здоровье демона.
• Заголовок — mkdev v0.4.0 + PID демона + время работы + порт прослушивания прокси.
• Маршруты — все маршруты из хранилища сверху вниз. Каждая запись показывает name.tld → target и суффикс-бейджи ( · disabled, · LAN).

Что делает (клик по маршруту):

• Открыть в браузере — открывает https://name.tld системным обработчиком по умолчанию.
• Копировать URL — копирует URL прокси в буфер обмена (pbcopy / wl-copy / xclip / clip.exe).
• Включить / Выключить — переключает флаг Enabled маршрута. Выключенные маршруты остаются в хранилище, но перестают проксироваться.
• Расшарить в LAN — включает mDNS-анонс + ACL со стороны LAN.

Действия панели в целом:

• Остановить демон — сначала вызывает DisableUnit, чтобы launchd / systemd KeepAlive не поднял его снова, затем отправляет команду завершения через сокет.
• Quit — завершает только процесс панели. Демон и прокси продолжают работать.

Заметки:

• Два экземпляра панели не могут работать одновременно (блокировка через PID-файл; второй сразу завершается).
• Панель автоматически переподключается при перезапуске демона. Точка статуса обновляется без ручного обновления.
• Только панель (и mkdev daemon stop) корректно останавливают демон под наблюдением — прямое убийство процесса демона приведёт к его повторному запуску через launchd / systemd.

Обновление

Замените бинарник (brew upgrade / go install ...@latest / новая загрузка). При следующем запуске любой подкоманды mkdev бинарник синхронизирует всё, что живёт вне него: перепишет plist демона / systemd-юнит и запись автозапуска панели, чтобы они указывали на новый бинарник, повторно пропишет /etc/hosts для включённых маршрутов и заново добавит CA в доверенные, если его оттуда удалили. Запросы sudo появляются прямо в терминале. Если у вас запущен только демон и вы не трогаете CLI, демон сам выполнит безопасные (без sudo) шаги при своём старте, а остальные поставит в очередь до следующей команды CLI.

Повторный запуск mkdev install делает то же самое явно и всегда безопасен — каждый шаг идемпотентен.

Поддержка платформ

Обнаруживаемые дистрибутивы Linux: Debian/Ubuntu (/usr/local/share/ca-certificates), RHEL/Fedora (/etc/pki/ca-trust/source/anchors), Arch (/etc/ca-certificates/trust-source/anchors), openSUSE (/usr/share/pki/trust/anchors).

Firefox использует собственное хранилище NSS и пока не покрыт — системные Chrome/Safari/Edge/curl/wget работают.

Команды

Флаги и окружение

Форматы target

<target> принимает любой из:

host:port                  e.g. localhost:3000
http://host[:port]/path    e.g. http://localhost:3000/api
https://host[:port]/path   e.g. https://gitlab.example.com

Для HTTPS-апстримов (например, приватный GitLab в корпоративном VPN) TLS-сертификат апстрима должен проверяться системным хранилищем доверия. Для приватных CA нужно добавить их корневой сертификат в системную связку ключей ОС.

hosts-helper не предназначен для прямого вызова. add / remove перезапускают тот же бинарник через sudo для выполнения привилегированной записи в /etc/hosts.

Конфигурация

Заметка про TLD. Для маршрутов .local нужен mDNS-резолвер (всегда включён на macOS, доступен на Linux при установленном nss-mdns). .test / .dev / .localhost работают везде только через /etc/hosts. Задайте tld в конфиге под себя.

Конфиг находится в ~/.mkdev/config.toml. Значения по умолчанию:

tld           = ".local"   # appended to bare names in `add`
proxy_port    = 443        # binding :443 requires sudo on serve
theme         = "auto"     # reserved for future TUI
log_retention = "7d"       # reserved
log_max_size  = "100MB"    # reserved

Переопределите каталог конфигурации через --home <path> или MKDEV_HOME=....

Как это работает

• Генерирует корневой CA ECDSA P-256 в ~/.mkdev/ca/. Приватный ключ имеет режим 0o400.
• Устанавливает CA в системное хранилище доверия ОС: Keychain на macOS (security), каталог CA-бандла Linux + update-ca-*, хранилище ROOT Windows через crypt32.dll. Интеграция с хранилищем доверия адаптирована из mkcert (BSD-3) — см. LICENSE-MKCERT.
• При add демон записывает маршрут в bbolt KV ~/.mkdev/state.db и добавляет строку 127.0.0.1 <name>.<tld> в /etc/hosts через хелпер-подкоманду, вызываемую через sudo.
• Демон слушает TLS на , по запросу с использованием корневого CA и проксирует к сконфигурированному апстриму.

Безопасность

Этот инструмент устанавливает приватный CA в системное хранилище доверия. Любой, у кого есть доступ на чтение к ~/.mkdev/ca/rootCA-key.pem, сможет выпускать TLS-сертификаты, которым ваша машина доверяет. Ключ создаётся с режимом 0o400 (чтение только владельцем).

• Прокси слушает 0.0.0.0, но ACL по источнику соединения отдаёт 403 на LAN-запросы к любому маршруту, не помеченному явно как shared. Loopback всегда проходит.
• Никакой телеметрии. Никаких удалённых вызовов. Никаких проверок обновлений.
• add / remove вызывают sudo для изменения /etc/hosts. Модель угроз и известное ограничение вокруг путей к хелперу, разрешаемых через os.Executable(), описаны в SECURITY.md.

Удаление

mkdev uninstall   # stops + disables daemon, untrusts CA, clears /etc/hosts,
                  # removes daemon service + bar autostart, wipes ~/.mkdev/

Если что-то зависло, откройте Keychain Access.app, найдите mkdev и удалите вручную. Затем grep mkdev /etc/hosts и вычистите остатки.

Демон и API

Демон владеет прокси и хранилищем маршрутов. Он открывает локальный HTTP API на ~/.mkdev/daemon.sock (только для владельца, 0600). TUI, CLI-подкоманды и панель в строке меню — все являются клиентами демона; только демон держит блокировку bbolt.

mkdev install устанавливает демон как пользовательский сервис (launchd LaunchAgent на macOS, systemd --user на Linux) и включает его. Он работает в фоне и переживает выход из системы и повторный вход.

mkdev daemon status                # installed / enabled / running
mkdev daemon stop                  # stop + disable (prevents respawn)
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/status
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/routes
curl --unix-socket ~/.mkdev/daemon.sock -X POST http://x/v1/routes \
     -H 'Content-Type: application/json' \
     -d '{"name":"foo","target":"localhost:3000"}'
curl --unix-socket ~/.mkdev/daemon.sock -X DELETE http://x/v1/routes/foo

Дорожная карта

В ближайших планах:

• Интеграция с хранилищем доверия Firefox / NSS.
• Маршрутизация по путям (/api → 8080, /ws → 9000 на одном домене).

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

• Firefox показывает красную панель. Firefox использует собственное хранилище NSS; системное доверие до него не доходит. Интеграция с NSS в дорожной карте. Пока что импортируйте ~/.mkdev/ca/rootCA.pem вручную: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.
• Демон не может занять :443. На macOS/Linux не-root пользовательские сервисы могут занимать :443 благодаря возможностям launchd / systemd. Если ваш дистрибутив это ограничивает, задайте proxy_port = 8443 в ~/.mkdev/config.toml и используйте https://name.local:8443.
• mkdev add постоянно просит sudo. Кэш sudo на сессию истекает (по умолчанию 5 минут). Используйте вместо этого вкладку Domains в TUI — она повышает привилегии через osascript (графический запрос macOS) или pkexec (Linux Polkit).
• В /etc/hosts уже есть запись для этого имени. mkdev add идемпотентен и добавляет запись, только если управляемой mkdev записи ещё нет. Удалите прежнюю запись вручную или выберите другое имя.

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

См. CONTRIBUTING.md.

Благодарности

Интеграция mkdev с хранилищами доверия — Keychain/security на macOS, CA-бандл + update-ca-* на Linux, хранилище ROOT через crypt32.dll на Windows и смежные пути NSS — адаптирована из mkcert Филиппо Вальсорды, лицензия BSD-3. Без этого задела проект был бы заметно сложнее. Лицензия апстрима — в LICENSE-MKCERT.

TUI построен на Charmbracelet Bubble Tea / Bubbles / Lipgloss. mDNS — через hashicorp/mdns. Локальное KV — через bbolt.

Лицензия

MIT LICENSE.