windows/CONNECTION-ROADMAP.md

Подключение MusicBridge — Windows

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

Что работает

• dotnet run -c Release -- --lan запускает HTTPS/WSS и mDNS для домашней IPv4-сети.
• B открывает новое окно сопряжения; I открывает отдельное Windows-окно QR.
• В окне можно выбрать адрес адаптера. QR обновляется при смене адреса или кода, убирается при истечении кода/успешном сопряжении. Проверка состояния — каждые 500 мс.
• QR генерируется локально через QRCoder. Внешних сайтов и временных файлов с кодом нет.
• Payload: musicbridge://pair?data=<base64url UTF-8 JSON>, поля version:1, endpoint, certificateSha256, code, expiresAt.
• Сервис DNS-SD: _musicbridge._tcp.local., имя MusicBridge-<12 символов SHA-256>. SRV указывает порт HTTPS; A — адреса домашних адаптеров; TXT — версия и ID. Библиотека также добавляет служебный txtvers. Кодов и токенов в объявлениях нет.
• mDNS обслуживает запросы, повторяет объявление раз в 30 секунд. При изменении списка IPv4-адресов снимает старое объявление и создаёт новое. При остановке отправляет goodbye. При исчезновении сети ждёт её возвращения.
• /v1/info требует Bearer-токен и возвращает идентификатор, равный SHA-256 сертификата.

Без --lan mDNS выключен, а окно QR сообщает, что нужен адрес домашней сети. Поиск не доказывает подлинность ПК: клиент всегда сверяет закреплённый TLS-сертификат.

Что проверено

Release-сборка без ошибок/предупреждений. Итоговый прогон — 95 проверок:

dotnet run --project tests/MusicBridge.Agent.Tests.csproj -c Release --no-build -- --qr-window-smoke --mdns-smoke --live-read

QR декодирован независимой библиотекой ZXing в исходный payload. Окно проверено в скрытом режиме, его снимок просмотрен, просроченный QR удаляется. Независимый mDNS-слушатель на этом же ПК получил объявление и goodbye. Это ещё не проверка доступности с iPhone/другого компьютера. Smoke-тест объявляет временный тестовый сервис и снимает его после проверки; реальное воспроизведение не меняется.

Что остаётся на Windows

• Проверить сканирование с физического устройства и обнаружение со второго ПК.
• Проверить смену Wi-Fi/IP, сон/пробуждение, несколько адаптеров и VPN.
• Полноценное разрешение конфликтов имён DNS-SD; сейчас имя строится по хешу сертификата, а второй локальный экземпляр блокируется хранилищем.
• Tray и окно управления: --tray --lan, кнопки сопряжения/отзыва, управление музыкой.
• Автозапуск из меню трея, самостоятельная ZIP-упаковка Windows x64, установка/удаление.
• Проверка реального входа в Windows с включённым автозапуском.
• Подготовить правила брандмауэра для частной сети, без автоматического открытия портов сейчас. HTTPS использует выбранный TCP-порт, mDNS — UDP 5353.

Порядок подключения будущего нативного клиента

1. Считать QR внутри приложения; проверить схему/версию, размер payload, HTTPS-адрес, формат отпечатка/кода и срок. Не использовать Safari как клиент.
2. Сверить сертификат с отпечатком из QR до POST /v1/pair.
3. Сохранить токен и отпечаток в Keychain. Код сопряжения не является постоянным секретом.
4. Получить /v1/info, /v1/state, открыть WSS /v1/events.
5. При переподключении найти ПК по DNS-SD, сопоставить ID и снова проверить TLS. При 401 запросить новое сопряжение; не повторять команды автоматически.

Схема musicbridge:// пока не зарегистрирована на iPhone. Swift/Xcode-проект и приложение ещё не создавались.

Реализация использует QRCoder и Makaretu.Dns.Multicast.