OAuth-вход: пошаговый разбор

mockarty-cli auth login — рекомендуемый способ аутентификации CLI на
admin-узле Mockarty. Команда выполняет OIDC-discovery, запускает
OAuth Device Flow (RFC 8628),
если сервер его анонсирует, и откатывается к вводу API-токена в противном
случае.

Сценарии работы:

1. Локальная машина с браузером. По умолчанию: CLI открывает браузер
   на URL верификации; вы подтверждаете; CLI получает токен и пишет его
   в ~/.mockarty/auth.json.
2. Self-hosted / корпоративный Mockarty. То же самое, только нужно
   передать --server https://mockarty.company.com.
3. Headless / SSH-сессия. CLI определяет отсутствие GUI и печатает
   URL верификации + короткий user-code. Откройте URL на машине с
   браузером, подтвердите — CLI автоматически продолжит.

Быстрый старт

mockarty-cli auth login --server https://mockarty.company.com

Без --server CLI читает (в этом порядке): MOCKARTY_SERVER из
окружения, поле server_url в ~/.mockarty/config.yaml.

После успешного входа CLI выводит примерно так:

✓ Logged in as alice@company.com (https://mockarty.company.com)
  Run any mockarty-cli command to start using the full feature surface.

Шаги

1. Discovery

CLI делает GET <server>/.well-known/openid-configuration, чтобы узнать,
какие grant’ы сервер поддерживает. Если OIDC недоступен (404, refused,
кривой JSON) — CLI откатывается к вводу API-токена (см.
Fallback: API-токен).

→ Discovering authentication endpoints…

2. Запрос device-кода

Если сервер поддерживает grant
urn:ietf:params:oauth:grant-type:device_code, CLI POST’ит на
device-authorization endpoint и получает:

• device_code — непрозрачный идентификатор, CLI хранит у себя.
• user_code — восьмисимвольный сгруппированный код (XXXX-XXXX),
  который человек вводит в браузере.
• verification_uri / verification_uri_complete — куда идти.
• expires_in — обычно 600 с.
• interval — минимальный интервал опроса (по умолчанию 5 с).

Дальше CLI печатает:

Your one-time code is: ABCD-EFGH
Open in a browser: https://mockarty.company.com/oauth/device?user_code=ABCD-EFGH
The code expires in 600 seconds.

3. Подтверждение в браузере

На машине с GUI CLI попытается открыть verification_uri_complete
(с уже встроенным кодом) в браузере по умолчанию. Если запуск браузера
не удался или вы передали --no-browser, CLI напечатает подсказку
Paste the URL into a browser to continue. и будет ждать.

В браузере:

1. Аутентифицируйтесь у вашего IdP (Google, VK, Yandex или локальная БД
   паролей — зависит от настройки админа).
2. На странице device-approval сверьте, что user-code совпадает с тем,
   что показал CLI.
3. Нажмите Approve.

4. Поллинг

Пока вы возитесь с браузером, CLI опрашивает token endpoint с интервалом,
указанным сервером (обычно 5 с):

⠋ Waiting for browser approval…

Спиннер крутится только на TTY; для не-TTY (CI, перехваченный stdout) —
обычная строка плюс точки. Поллинг прекращается при:

• Approved → CLI получает access_token, разбирает identity,
  пишет токен в ~/.mockarty/auth.json.
• Denied → выход с кодом 3 и сообщением
  OAuth device flow failed: access_denied.
• Expired → через expires_in секунд device-код становится
  недействительным; перезапустите auth login.

5. Сохранение учётки

На успехе CLI пишет:

• ~/.mockarty/auth.json — токен формата mk_…, режим 0600.
• ~/.mockarty/config.yaml — server_url: … (если ещё не задан).
• Опционально namespace: … — если был флаг --namespace.

Headless / SSH fallback

CLI решает, что GUI нет, в двух случаях:

1. Явно передан --no-browser.
2. stdin — не TTY ИЛИ ОС сообщает, что нет GUI-сессии (нет DISPLAY
   на Linux, нет Aqua-сессии на macOS).

В обоих случаях CLI печатает URL и user-code и ждёт. Откройте URL на
машине с браузером, подтвердите — CLI продолжит. User-code короткий,
его можно продиктовать по телефону.

ssh server-without-browser
$ mockarty-cli auth login --server https://mockarty.company.com --no-browser

Your one-time code is: ABCD-EFGH
Open in a browser: https://mockarty.company.com/oauth/device
Waiting for browser approval…

Справочник флагов

mockarty-cli auth login [flags]

Flags:
  --server string       URL Mockarty-сервера (перекрывает config)
  --client-id string    Идентификатор OAuth-клиента (по умолчанию — встроенный CLI-клиент)
  --no-browser          Печатать URL вместо запуска браузера
  --namespace string    Активный namespace, сохраняемый после логина
  --insecure            Пропускать TLS-валидацию (также реагирует на глобальный --insecure)
  --name string         Имя контекста (зарезервировано для будущего)

Logout

mockarty-cli logout

Удаляет токен из ~/.mockarty/auth.json и оставляет server_url
нетронутым (чтобы следующий auth login мог не передавать --server).

Проверка статуса

Чтобы проверить, под каким пользователем вас видит сервер, откройте экран
авторизации:

mockarty-cli tui auth

Чтобы проверить работоспособность сервера, выполните:

mockarty-cli health

После успешной проверки пользователя TUI покажет логин, роль, адрес сервера
и активное пространство имён. health проверяет состояние сервера, а не
действительность вашего токена; используйте её как проверку доступности в CI.

Несколько серверов

auth login хранит один OAuth-токен или введённый API-токен в
~/.mockarty/auth.json и один адрес сервера в config.yaml. Его параметр
--name пока не создаёт именованный профиль. Для отдельных интерактивных
OAuth-сеансов задайте разные пути MOCKARTY_AUTH_FILE и MOCKARTY_CONFIG
для каждого окружения либо входите заново при переключении сервера.

Если у вас уже есть API-токены нескольких серверов, используйте именованные
контексты CLI:

mockarty-cli login --server https://staging.example.com --token "$STAGING_TOKEN" --name staging
mockarty-cli login --server https://production.example.com --token "$PRODUCTION_TOKEN" --name production
mockarty-cli config get-contexts
mockarty-cli config use-context staging

Для автоматических запусков также можно задавать MOCKARTY_API_TOKEN и
MOCKARTY_SERVER отдельно в каждой оболочке. Не записывайте токены
продуктивного сервера в общие скрипты и историю команд.

Fallback: API-токен

Если discovery не удался или сервер не анонсирует device-code grant,
CLI спросит:

This server does not advertise OAuth device flow.
Paste an API token (mk_…):

API-токен можно создать в UI Settings → Tokens (или через
POST /api/v1/auth/tokens для CI). Вставьте строку mk_… — CLI
сохранит её идентично OAuth-токену.

Для unattended-CI обычно проще задать MOCKARTY_API_TOKEN в окружении
ранера — auth login интерактивный и не рассчитан на не-TTY вызовы.

Диагностика

Безопасность

• Токен в auth.json — bearer-credential. Любой с правом чтения файла
  действует от вашего имени. CLI пишет файл с 0600 и родителя
  ~/.mockarty/ с 0700. Не кладите такой файл в контейнерные образы.
• Токены ограничиваются на стороне сервера: admin-токен даёт admin-
  действия, user-токен — только namespaces и фичи пользователя. CLI
  не может расширить authority токена.
• --insecure отключает TLS-валидацию только OAuth-клиента; он НЕ
  пробрасывается на последующие API-вызовы — они смотрят глобальный
  --insecure отдельно. Не запускайте --insecure против продакшна.

Запасной вход: пароль, когда провайдер недоступен

Если вы обычно входите через внешнего провайдера (Google, VK, Яндекс), а он
стал недоступен — региональная блокировка, корпоративный файрвол, сбой IdP —
держите локальный пароль как запасной вариант:

1. Будучи в системе, откройте меню аватара (справа вверху) → Профиль.
2. Если у аккаунта ещё нет пароля, показывается форма Задать пароль —
   задайте его (минимум 8 символов).
3. После этого форма входа принимает ваш логин или email плюс этот
   пароль — без участия провайдера.

Email должен принадлежать ровно одному аккаунту; адрес, с которым вы входили
через провайдера, подставляется автоматически.