POST/DELETE /v1/account/avatar (session, exact Origin, CSRF) and public GET /v1/avatars/<id>. Uploads are sniffed, size and dimension limited, fully decoded, re-encoded to a 256x256 PNG without metadata and stored in SQLite, one per account. avatar_url in the session points to it, with the provider avatar as fallback.
12 KiB
Vnox: регистрация, устройства и аватары
Статус: продуктовая и техническая спецификация. Регистрация Hub пока не реализована. Клиентский редактор аватара реализуется отдельно; до появления API сохраняет реальное изображение локально.
Вход и создание аккаунта
Для первого Hub: «Продолжить с GitHub» и «Войти по почте» с одноразовым кодом. Регистрация и вход — один понятный поток; после подтверждения нового аккаунта выбираются свободный handle, отображаемое имя и необязательный аватар. Пароль Vnox на первом этапе не требуется. Google и другие провайдеры добавляются позже при необходимости.
Постоянный user_id создаёт Hub; он не равен ни email, ни GitHub username. Провайдер GitHub идентифицируется origin/provider + стабильным числовым ID из проверенного API-ответа. Для будущих OIDC-провайдеров — issuer + subject. Ник провайдера и совпадающий email не используются для автоматического объединения аккаунтов.
Связать второй способ входа можно из аутентифицированного аккаунта после повторного подтверждения; требуется доказать владение добавляемым способом. Отвязка последнего способа входа запрещена без настроенного восстановления. Добавление/отзыв устройств, email и способов входа сопровождаются уведомлениями.
Статус реализации (Hub, этап 1): вход по почте с одноразовым кодом работает (hub/AUTH.md). Новый аккаунт получает сгенерированный handle u_... и нейтральное имя; выбор handle и отображаемого имени после первого подтверждения ещё не реализован. Собственный аватар можно загрузить и убрать на странице аккаунта сайта (реализовано в Hub, см. ниже). Связывание второго способа входа, passkey/MFA и уведомления о новых способах входа тоже впереди.
GitHub OAuth
Клиент открывает системный браузер. Hub хранит OAuth client_secret, принимает provider callback, проверяет state/PKCE и получает подтверждённую identity через GitHub API. Клиенту возвращается одноразовый код Vnox для конкретного login attempt с PKCE, а не GitHub bearer token в URL.
Запрашиваются минимальные права для identity; доступ к репозиториям не нужен. Если email не используется для входа/backup, не требовать дополнительный доступ к приватной почте. Provider tokens не передаются серверам сообществ; если после входа API не нужен, не держать долгоживущие GitHub refresh/access tokens без причины.
Системный браузер предпочтительнее embedded webview. Callback/loopback адреса фиксируются, одноразовые коды короткоживущие и связаны с инициировавшим их клиентом. GitHub OAuth и собственный обмен app↔Hub имеют отдельные state/PKCE-контексты.
Почта
Код одноразовый, криптографически случайный, с коротким сроком, ограниченным числом попыток и rate limits по попытке/адресу/источнику. Ответы не раскрывают существование аккаунта. Коды и ссылки не логируются; хранить защищённое проверяемое представление с серверным секретом, не голый hash низкоэнтропийного кода.
Email подтверждает контроль почтового ящика, а не сильную защищённость аккаунта. Для владельцев серверов и авторов пакетов нужны усиленная проверка/passkey либо другое явно выбранное MFA перед чувствительными действиями. В обычном интерфейсе passkey можно предложить после первого входа. Конкретную WebAuthn библиотеку и платформенную поддержку проверить перед реализацией.
Устройства и E2EE
У каждого устройства отдельный ключ и список активных сессий с возможностью отзыва. Способ входа в профиль не является ключом расшифрования переписки. Восстановление GitHub/email не расшифровывает старые E2EE сообщения автоматически.
Для добавления доверенного устройства требуется подтверждение действующим устройством или секрет восстановления зашифрованной копии ключей. При полной потере ключей возможен возврат к профилю с новым crypto identity, но старую историю обещать нельзя; контакты видят смену identity. Максимальная задержка отзыва сессий и режим при недоступном Hub определяются общим протоколом.
Существующая локальная identity переносится в Hub только после доказательства владения, не по совпадению nickname. Аккаунт Hub и криптографическая identity нельзя склеивать неявно.
Редактор аватара
В профиле: «Изменить фото» → нативный выбор PNG/JPEG/WebP → квадратный диалог с круглой маской. Пользователь двигает изображение, меняет масштаб ползунком или колесом, видит итог в круге; доступны «Сбросить», «Отмена», «Сохранить».
При открытии кадр центрирован и заполняет круг без пустых краёв. Смещение ограничивается так, чтобы итоговый квадрат полностью покрывался изображением. Ориентация фотографии учитывается до расчёта размеров. Сохраняется квадратный PNG 256×256; круг — маска отображения, а не потеря пикселей по краям. Никакого растягивания исходника по осям.
Первоначальные ограничения клиента: исходный файл до10MiB, сторона до4096px, лимит памяти декодера64MiB. Ограничения проверяются при чтении/декодировании, ошибки показываются в диалоге. SVG, внешние URL и анимации не поддерживаются в первой версии. Оригинал не сохраняется после нормализации; выходной PNG не переносит исходные EXIF/геометки. Отмена и ошибка не заменяют прежний аватар; запись атомарная.
Реализация в Hub (веб): POST/DELETE /v1/account/avatar, GET /v1/avatars/<id> (hub/AUTH.md). Hub принимает PNG/JPEG/WebP до 2 МиБ и 4096 px, проверяет тип по сигнатуре, полностью декодирует и заново кодирует в PNG 256×256 без метаданных, хранит один аватар на аккаунт в SQLite BLOB; адрес содержит хеш содержимого и кэшируется как immutable. Для сайта кадрирование делается на canvas до отправки, Hub дополнительно обрезает по центру. Для аккаунта GitHub «Убрать фото» возвращает аватар GitHub. Клиент Vnox пока не использует этот API. Резервные копии базы могут хранить удалённые данные до 30 дней (решение владельца; ротацию копий ещё нужно реализовать).
До Hub API аватар собственный/локальный и не выдаётся за синхронизированный с друзьями. Впоследствии Hub принимает нормализованное изображение, повторно проверяет/перекодирует его, обновляет avatar_id/revision и доступ по политике профиля. Изображение хранится до замены/удаления профиля; правило DM-вложения «4 дня» не применяется. Старые версии и кэши очищаются по отдельной политике.
Ещё решения до публичного запуска
- Подтверждение первого владельца сервера и его восстановление без захвата чужого сервера.
- Сроки сессий, отзыв устройств, резервные коды и политика восстановления ключей.
- Email delivery: SMTP, ограничения, защита от рассылочного абьюза и доступность писем.
- Видимость профиля/email/присутствия; жалобы, блокировки и ограничения поиска.
- Приглашения с сроком/числом использований, закрытые сообщества и удаление аккаунта.
- Хранение аватаров отдельно от временных DM-файлов и версий marketplace.
Источники: GitHub OAuth, RFC8252: native apps, OWASP: linking/authentication, email verification.
Размещение сервера за NAT требует отдельного решения по доступности: публикация в Hub не открывает TCP/UDP-порты. Для первого self-hosted этапа нужен доступный адрес/IPv6 или настройка port forwarding/VPN; центр не обещает автоматически проксировать голос.