Подключение, pairing и разрешения

Pairing

Файл обнаружения указывает адрес и идентификатор активного Host, но не разрешает доступ. Клиент не может самостоятельно подтвердить свой запрос pairing.

Прочитайте текущий файл через ApiHostDiscovery.ReadAsync, создайте StreamingHubApiClient(discovery) и вызовите RequestPairingAsync. Передайте постоянный ID клиента, заявленные имя и издателя, а также запрашиваемые разрешения.

Пользователь принимает или отклоняет запрос через Tray Core. Проверяйте возвращённый запрос методом PollPairingAsync: учётные данные возвращаются только после подтверждения и только один раз. Подключайтесь через ConnectWithCredentialAsync, указав необходимые возможности.

Сохраняйте учётные данные в защищённом локальном хранилище. Не записывайте учётные данные, сеансы и идентификаторы запросов pairing в журналы, URL, командные строки и файлы проектов.

Запрос pairing действует две минуты; одновременно могут ожидать не более 16 запросов. Учётные данные действуют 30 дней и привязаны к постоянному ID клиента. HTTP-сеанс действует не более двух минут и не дольше самих учётных данных. Для продления обменяйте ещё действующие учётные данные снова и выполните handshake: существующие разрешения при этом не меняются. Имя клиента и издатель — заявленный текст, а не проверенная идентификация издателя.

Выбор разрешений

• host.status — идентификатор и безопасное состояние Host; host.shutdown — отдельное разрешение на выключение.
• project.read / project.configuration.read — структура проекта / конфигурация с содержимым.
• project.write / project.files — применение и восстановление изменений / операции с файлами проекта.
• catalog.read — объявленные действия, сигналы и схемы.
• settings.read / settings.write — чтение настроек Core и плагинов / запись с проверкой версии.
• runtime.read / runtime.control — наблюдение и восстановление / управление выполнением.
• runtime.values.read — текущие переменные, значения сервисов и статистика.
• diagnostics.read / diagnostics.content.read — ограниченные диагностические сведения / содержимое журналов и очищенные примеры сигналов.
• inspector.read — ограниченные трассы выбранного запуска с учётом владельца.
• history.read / history.manage — чтение сохранённой истории / управление хранением и очисткой.
• updates.read / updates.manage / updates.prepare — наблюдение обновлений / управление конкретным планом / подготовка клиента.
• plugins.trust.read / plugins.trust.manage — просмотр кандидатов / решения о доверии.
• interaction.read / interaction.respond — просмотр ожидающих взаимодействий / получение, освобождение и ответ.
• components.read / components.install — каталог компонентов / планирование установки.
• project.layout.read / project.layout.write — устарели: расположение интерфейса хранится у клиента, маршруты возвращают editor_layout_local.

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

Динамические варианты Editor требуют одновременно catalog.read, project.configuration.read и settings.read. Выбор файлов контекста требует project.files: чтение каталога не даёт доступа к папкам. Для ответа на чувствительное взаимодействие также нужно разрешение самой операции. runtime.control не разрешает чтение результатов runtime-команд.

В requiredCapabilities при handshake явно перечислите нужные возможности из подтверждённого набора. Клиенту только для статуса достаточно host.status; для чтения проекта добавьте project.read, для применения изменений — project.write. Не копируйте полный набор разрешений Editor каждому клиенту.

Продление не расширяет разрешения. При действующих и неотозванных учётных данных отключённый сеанс можно восстановить. Просроченный или отозванный доступ нужно получить заново; новый pairing создаёт другую идентичность для восстановления команд.

Отключение одного сеанса не отзывает учётные данные. Отзыв завершает связанные сеансы и подписки. Этими действиями управляют доверенные средства Core; публичного HTTP-метода, которым клиент подтверждает доступ сам себе, нет.

Ограничение для браузера

Сейчас API принимает локальных нативных клиентов. Core не открывает доступ в локальную сеть, не включает CORS и не разрешает запросы из браузера. Не используйте веб-прокси как замену согласованной модели безопасности браузерного клиента.