VNOX-Server/docs/design/accounts-and-avatars.md

10 KiB
Raw Blame History

Vnox: регистрация, устройства и аватары

Статус: продуктовая и техническая спецификация. Регистрация Hub пока не реализована. Клиентский редактор аватара реализуется отдельно; до появления API сохраняет реальное изображение локально.

Вход и создание аккаунта

Для первого Hub: «Продолжить с GitHub» и «Войти по почте» с одноразовым кодом. Регистрация и вход — один понятный поток; после подтверждения нового аккаунта выбираются свободный handle, отображаемое имя и необязательный аватар. Пароль Vnox на первом этапе не требуется. Google и другие провайдеры добавляются позже при необходимости.

Постоянный user_id создаёт Hub; он не равен ни email, ни GitHub username. Провайдер GitHub идентифицируется origin/provider + стабильным числовым ID из проверенного API-ответа. Для будущих OIDC-провайдеров — issuer + subject. Ник провайдера и совпадающий email не используются для автоматического объединения аккаунтов.

Связать второй способ входа можно из аутентифицированного аккаунта после повторного подтверждения; требуется доказать владение добавляемым способом. Отвязка последнего способа входа запрещена без настроенного восстановления. Добавление/отзыв устройств, email и способов входа сопровождаются уведомлениями.

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 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; центр не обещает автоматически проксировать голос.