Разработчикам
На URnetwork можно строить три вещи, и у них три разных вида учётных данных. Выбрать верный — первое решение, и разница не косметическая.
| Что вы строите | С чего начать | Учётные данные |
|---|---|---|
| Приложение или устройство, которое подключается к URnetwork | SDK, затем тур по SDK | JWT аккаунта, который обменивается на JWT с clientId |
| Прикладной клиент, использующий TCP, UDP, TLS/DTLS или Direct Sockets через Device | Сокеты | Инициализированный Device с доступным путём соединения |
| Автоматизация в вашей собственной сети | API оператора | JWT вашей сети или API-ключ urn_ |
| Продукт, в который люди входят, допуская его в свою сеть | Вход через URnetwork (Sign in with URnetwork) | Выданный вам OAuth client_id |
Важная граница — в чьей сети вы действуете. С SDK и API оператора вы действуете в своей сети, с учётными данными, которые держите и контролируете сами. Вход через URnetwork — это человек, допускающий ваше ПО в свою сеть: эти учётные данные никогда не бывают у вас, их выдаёт человек, и он же может их отозвать.
SDK
Начните с установки, затем откройте обозреватель примеров с исполняемыми программами на двенадцати языках. Для каждого языка есть руководство по установке и каталог socket с запускаемыми интеграциями HTTP-клиентов.
Go SDK, JS/WASM SDK и CGo ABI работают на одном сетевом движке. Десктопные языковые пакеты оборачивают модуль CGo; Android использует AAR от gomobile, а Swift — Apple XCFramework. Для JavaScript есть примеры и для Node, и для браузера, использующие размещённый Device.
Руководство по сокетам объясняет, как использовать соединения TCP, UDP, TLS/DTLS и Direct Sockets, которые Device держит в пользовательском пространстве. Приложения могут пользоваться этими сокетами, не устанавливая системную VPN. DeviceRemote в браузере использует пакетный путь своего размещённого Device; TUN-интерфейс, которым владеет браузер, ему не нужен.
Раздел Какой биндинг выбрать раскладывает компромиссы бок о бок. Примите это решение до того, как напишете код: оно определяет вашу модель процессов, а не только синтаксис.
API оператора
HTTP API, стоящий за URnetwork. Через него проходит бутстрап протокола connect, он выдаёт JWT, которыми аутентифицируются клиенты, и открывает транзакции подбора (match-making), на которых работает сеть. Каждый маршрут и каждая схема описаны на /docs/api, и эта страница сгенерирована из спецификации.
Его область действия — ваша сеть. Название подталкивает к прочтению, будто он действует на сеть вообще; это не так.
На одном шаге спотыкаются почти все: маршруты /auth возвращают JWT без clientId, а протоколу connect нужен JWT с ним. Обменяйте его через маршруты /network. Сеть — это глобально уникальная подсеть (xyz.ur.network); clientId — 16-байтовый адрес, эквивалентный адресу IPv6 и выраженный в виде UDID.
Вход через URnetwork
Позволяет людям допускать ваше приложение или агента в свою приватную сеть, чтобы оно могло координироваться со всем остальным, что у них там работает. Это в разработке и ещё не запущено — что существует уже сегодня, смотрите на самой странице.
Сервер MCP — не четвёртая категория. Это один сервер ресурсов, доступный по токену входа через URnetwork, и разобранный пример этого паттерна.
Границы токенов
Две системы учётных данных подписываются непересекающимися наборами ключей. Это граница безопасности, а не соглашение: токен входа через URnetwork — не учётные данные платформы, и попытка предъявить его там, где ожидается JWT платформы, проваливается по построению. Токены доступа OAuth к тому же привязаны к аудитории: каждый проходит проверку ровно для одного ресурса и отвергается везде ещё.
Есть один санкционированный переход, и это мост, а не обход: допущенное приложение обменивает свой токен OAuth на JWT платформы с clientId, ограниченный сетью, в которую его допустили. Обмен — это решение об авторизации, принимаемое на сервере; ни один токен не проходит проверку в двух местах.
Если у вас на руках два вида учётных данных и один из них не работает, дело обычно именно в этом.