Провайдер авторизации MAX

Модуль добавляет в @webresto/core вход через чат-бота MAX. Это Sails hook с именем max_auth_provider; он регистрирует адаптер max в общей auth-системе и не содержит отдельного пользовательского интерфейса.

Как работает вход

1. Клиент вызывает startAuth для провайдера max.
2. Core создаёт AuthState, а модуль возвращает deep link вида https://max.ru/<имя-бота>?start=<stateId>.
3. После перехода пользователя MAX отправляет событие bot_started. Модуль связывает пользователя MAX с AuthState и отправляет кнопку «Поделиться контактом».
4. Полученный контакт проверяется по секрету webhook, соответствию идентификатора отправителя и HMAC-подписи MAX. После проверки core создаёт или обновляет User и AuthIdentity(provider="max"), а затем выдаёт обычную сессию UserDevice.

Подключение

1. Добавьте каталог модуля в набор подключаемых модулей приложения обычным для проекта способом. После загрузки Sails hook должен быть доступен под именем max_auth_provider — оно задано в package.json как sails.hookName.
2. Примените миграции приложения. Миграция migrations/20260809000000-init-max-auth-user.js создаёт таблицу maxauthuser, migrations/20260824130000-add-user-to-max-auth-user.js добавляет ссылку на пользователя, migrations/20260824120000-add-max-channel-to-notification-rules.js включает канал max в правилах уведомлений.
3. Перезапустите приложение. После готовности ORM модуль зарегистрирует в core провайдер с идентификатором max.
4. Впишите токен бота и секрет webhook (ниже), подпишите бота на webhook и включите способ входа max на странице способов входа админки.

Конфигурация

Две секретные настройки модуля (settings/): админка («Настройки») и API их не показывают, переменная окружения того же имени важнее записи в базе. Перезапуск не нужен.

Настройка	Назначение
MAX_AUTH_BOT_TOKEN	токен доступа бота (MAX для партнёров, настройки бота)
MAX_AUTH_WEBHOOK_SECRET	секрет подписки на webhook, 5–256 символов: буквы, цифры, _, -

Имя бота для ссылки модуль спрашивает у MAX по токену (GET /me). Адрес API — https://platform-api.max.ru: platform-api2.max.ru отдаёт сертификат Минцифры, которому Node без NODE_EXTRA_CA_CERTS не доверяет.

config строки способа входа max (accessToken, botUsername, webhookSecret, apiBase) и переменные MAX_AUTH_BOT_USERNAME, MAX_AUTH_API_BASE важнее настроек. Метод healthcheck() покажет, каких параметров не хватает.

Настройка webhook в MAX

Настройте endpoint https://<ваш-домен>/auth/max/webhook на следующие типы событий:

• bot_started;
• message_created;
• bot_stopped;
• dialog_removed.

Пример создания подписки:

curl -X POST "https://platform-api.max.ru/subscriptions" \
  -H "Authorization: $MAX_AUTH_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/auth/max/webhook",
    "update_types": ["bot_started", "message_created", "bot_stopped", "dialog_removed"],
    "secret": "значение MAX_AUTH_WEBHOOK_SECRET"
  }'

Значение secret должно совпадать с webhookSecret в конфигурации модуля. В production webhook должен быть доступен по HTTPS на порту 443. Если окружение требует сертификат Минцифры для обращения к API MAX, передайте путь к нему процессу Node.js через NODE_EXTRA_CA_CERTS.

Уведомления через MAX

Модуль регистрирует канал доставки уведомлений max в NotificationManager ядра. Канал виден на странице «Каналы уведомлений» сразу после загрузки модуля, даже без токена: реальное состояние показывают isConfigured() (есть ли accessToken) и isReady() (включён ли провайдер max).

Параметр канала	Значение	Смысл
type	max	идентификатор канала в правилах уведомлений и шаблонах
cost	0	сообщения бота бесплатны, поэтому канал идёт раньше платных
sortOrder	15	после бесплатных push-каналов (10/11), до платных
forGroupTo	["user"]	только пользовательские уведомления, не менеджерские
stopEscalation	true	доставка через MAX завершает waterfall
templateFields	title, body, clickUrl	что показывает редактор шаблонов для канала

Все параметры (включая stopEscalation) оператор меняет на странице каналов; они хранятся в настройке ядра NOTIFICATION_CHANNELS_STATE.

Почему stopEscalation

MAX не сообщает о прочтении сообщения, поэтому Notification.readAt не заполнится никогда. Без этого флага цикл эскалации ядра через NOTIFICATION_UNREAD_ESCALATION_MINUTES продублировал бы каждое доставленное в MAX сообщение платным каналом — то есть съел бы всю экономию. Флаг означает: «канал доставил — дальше не идём». Если для критичных уведомлений дублирование нужно, stopEscalation для канала отключается в админке.

Адресация

Получатель ищется по MaxAuthUser.findForUser(userId):

1. денормализованное поле MaxAuthUser.user (кэш горячего пути);
2. если кэша нет — AuthIdentity(provider="max", user) → MaxAuthUser.maxUserId, после чего ссылка сохраняется, а неактуальный pendingAuthState очищается.

Источником истины остаётся AuthIdentity. Отдельная модель сопоставления не нужна: MaxAuthUser и есть эта модель.

Писать боту первым MAX не разрешает — сообщение уходит только тем, кто нажал «Начать», а это гарантирует сам вход через MAX. Пользователь, который зарегистрировался по телефону и позже вошёл через MAX, получает бесплатный канал автоматически: AuthService привязывает identity к существующему аккаунту по подтверждённому телефону.

Отписка и ошибки

• события bot_stopped / dialog_removed выключают notificationsEnabled у получателя — поэтому эти типы обязательно должны быть в подписке webhook;
• если MAX отвечает «нет диалога / заблокирован» (400 с текстом про chat/user, 404), канал сам выключает notificationsEnabled, чтобы не тратить попытку waterfall на каждом следующем уведомлении;
• 401 (токен) и 5xx не считаются проблемой получателя: канал помечается неисправным, отписка не выставляется;
• если MAX отверг markdown, сообщение повторяется один раз обычным текстом — несбалансированная * в шаблоне оператора не должна выдавливать уведомление в платный канал.

Лимиты

Запросы к API сериализуются общей очередью: не чаще ~16 запросов в секунду на домен (документированный предел — 30) и не чаще одного сообщения в 550 мс в один диалог (предел — 2 в секунду). Текст обрезается до 4000 символов.

Правила уведомлений

Ядро о модуле ничего не знает, поэтому канал прописывает себя сам. В режиме waterfall диспетчер перебирает только каналы из defaultChannels правила, а в правилах ядра указаны лишь push-каналы — без этого шага канал был бы зарегистрирован, но никогда не использовался.

• на уже развёрнутых инсталляциях миграция модуля migrations/20260824120000-add-max-channel-to-notification-rules.js добавляет max в правила order_accepted_push, order_on_the_way_push, order_not_completed_followup, user_birthday_greeting (списки, отредактированные оператором, не трогает);
• на чистой установке правила заливаются сидами уже после миграций, поэтому канал нужно отметить в редакторе правил вручную. Об этом напоминает пункт setup-чеклиста «MAX notifications enabled in rules», который модуль регистрирует на старте.

Отдельный шаблон для канала не обязателен — без него рендерится шаблон правила по умолчанию.

Ссылка из clickUrl добавляется в текст отдельной строкой. Относительный путь достраивается до абсолютного через настройку AUTH_CALLBACK_BASE_URL; если она пуста, ссылка не добавляется (в мессенджере относительный путь всё равно не кликабелен).

OTP-коды через MAX не отправляются: правило user_otp_sms не тронуто.

Безопасность и данные

Каждый webhook проверяется по заголовку X-Max-Bot-Api-Secret. Для контакта дополнительно проверяются совпадение MAX ID отправителя с данными контакта и HMAC-SHA256(access_token, vcf_info). Проверенный телефон считается подтверждённым MAX.

Модель MaxAuthUser хранит MAX ID, chat ID, профиль, подтверждённый телефон, ссылку на пользователя ядра и состояние уведомлений. Бизнес-уведомления идут через канал max (см. выше). Метод адаптера sendNotification(userId, text) остаётся только для служебных сообщений в диалоге бота — он обходит шаблоны, бюджет, логи и историю уведомлений.

Контактные данные можно использовать только для взаимодействия пользователя с ботом, которому он их отправил. Это ограничение MAX необходимо учитывать при рассылках.

Changelog

1.3.1 (2026-10-28)

• The attempt of a login is read by AuthAttempt.load(id, { liveOnly: true }): the core has no AuthAttempt.getActive, and "Начать" in the bot threw - the bot never offered to share the contact.

1.3.0 (2026-10-28)

• The bot token and the webhook secret are secret settings of the module, MAX_AUTH_BOT_TOKEN and MAX_AUTH_WEBHOOK_SECRET (settings/): an operator sets them in the admin panel or by the settings API; an environment variable of the same name still wins.
• The bot's name for the deep link is asked from MAX by the token (GET /me), at the first login, once per token; the healthcheck no longer requires it. botUsername in the method's config and MAX_AUTH_BOT_USERNAME still win.
• The default API is https://platform-api.max.ru: platform-api2.max.ru serves a certificate of the Russian Trusted Root CA, which Node does not trust without NODE_EXTRA_CA_CERTS.
• start gives the link in clientPayload.url, as every bot_dialog way (was botDeepLink, botUsername, qr): the login window of the storefront opens url.

1.2.0 (2026-10-22)

• Moved to the new core auth layer: AuthAdapter with offers instead of AuthProviderAdapter, AuthAttempt instead of AuthState, the provider row is read through AuthMethod.getBySlugOffer.
• canVerifyPhone is declared by the adapter (the vCard is HMAC-signed); requirePhoneVerification now defaults to true.
• The MAX dialog tells the user that a code went out by SMS; the code itself is never sent there.
• The AuthProviderAdapter export from index.js is removed.

1.1.0

• MAX notification channel (max) registered in the core NotificationManager: free, runs after the push channels and before any paid one, user notifications only.
• Terminal delivery: the channel sets stopEscalation, so a message delivered to the MAX dialog is not duplicated by a paid channel (MAX reports no read receipt).
• Recipient resolution through MaxAuthUser.findForUser, backed by a new denormalized MaxAuthUser.user link; the stale pendingAuthState is now cleared after login.
• Own migration + setup-checklist item that put the max channel into the core notification rules (core stays unaware of this module).
• MAX API client: markdown format, 4000-character limit, request throttling (30 rps domain / 2 messages per second per dialog), typed errors — an unreachable recipient switches notificationsEnabled off, a rejected markdown is retried once as plain text.

1.0.0

• Initial release of the MAX bot authorization provider for the @webresto/core auth layer.