go-learn/docs/design/oauth-vk-yandex.md

Дизайн: вход через VK ID и Яндекс ID (этап 8.2, запланирован)

Дата: 2026-08-06. Статус: дизайн (реализация — отдельной командой, когда владелец получит ключи). Оба провайдера — российские юрлица; зарубежные провайдеры исключены решением владельца.

Что нужно от владельца (действия вне репозитория)

1. VK ID: кабинет https://id.vk.com/business/go → создать приложение (веб-сайт) → получить client_id и client_secret (secure key) → указать redirect URI: https://<домен>/api/oauth/vk/callback.php.
2. Яндекс ID: https://oauth.yandex.ru → новое приложение → права: «Доступ к адресу электронной почты» (login:email), при желании «имя и аватарка» → получить ClientID/Client secret → redirect URI: https://<домен>/api/oauth/yandex/callback.php.
3. Вписать ключи в config.php на хостинге (не в репо!): 'vk_client_id', 'vk_client_secret', 'yandex_client_id', 'yandex_client_secret'.
4. Домен обязан быть на HTTPS — оба провайдера требуют https redirect URI (включается панелью хостинга, не .htaccess).

Архитектура (когда будем делать)

• Таблица oauth_accounts(user_id INTEGER, provider TEXT ('vk'|'yandex'), provider_user_id TEXT, PRIMARY KEY(provider, provider_user_id)); связь с users — по email (провайдер отдаёт подтверждённый email → ищем/создаём users-запись, пароль при этом NULL-able или случайный хэш — вход по паролю для такой учётки отключён до установки пароля через «сменить пароль»).
• Эндпоинты: GET /api/oauth/<provider>/start.php → 302 на авторизацию провайдера (state = random в сессии, anti-CSRF); GET /api/oauth/<provider>/callback.php?code&state → проверка state → обмен code на token (server-side, client_secret в теле POST) → получение email (VK: метод id.vk.com/oauth2/user_info; Яндекс: https://login.yandex.ru/info?format=json с Bearer) → find-or-create user + oauth_accounts → сессия → 302 на /account.html.
• VK ID — OAuth 2.1 + PKCE (code_verifier/code_challenge в сессии); Яндекс — классический OAuth 2.0 code flow.
• Кнопки «Войти через VK ID» / «Войти через Яндекс ID» на /account.html и /register.html; официальные бренд-ресурсы кнопок — из пресс-китов провайдеров (лицензии — в CREDITS.md).
• Rate limit на start/callback; ошибки провайдера → /account.html с тихой пометкой «вход через … не удался».

Правовые заметки (не юридическая консультация)

• VK ID и Яндекс ID — сервисы российских юрлиц (ООО «В Контакте», ООО «Яндекс»); требование владельца «без зарубежной аутентификации» соблюдено.
• 152-ФЗ: email/идентификаторы — персональные данные; при целевой аудитории РФ рекомендуется хостинг с серверами в РФ и уведомление Роскомнадзора как оператора ПДн (если применимо к проекту — вопрос к юристу; сайт учебный, без монетизации).
• В privacy-заметку сайта (если появится) — перечислить, что храним: email, хэш пароля, прогресс обучения.

Объём реализации (оценка этапа 8.2)

server/: oauth/start+callback ×2 провайдера, миграция oauth_accounts, smoke (моки token/userinfo через GOLEARN_TEST-хук); apps/web: кнопки, строки; docs: обновить deploy.md (шаги ключей). ~1 сессия.