# Вход по SMS через SMSC

← [К модулям](README.md)

Модуль `smsc_auth` отправляет одноразовый код через SMSC. Проверка кода,
создание пользователя и публичная сессия выполняются ядром AVE.cms. Благодаря
этому отключение или замена SMSC не меняет пользователей и их заказы.

## Что получает посетитель

На странице входа появляется форма с телефоном. После отправки сообщения она
заменяется полем для кода. Возможны два сценария:

1. Телефон уже принадлежит активному пользователю — открывается его профиль.
2. Телефона ещё нет — создаётся пользователь сайта в группе регистрации.

Оба сценария используют одну таблицу пользователей. Отдельных «SMS-аккаунтов»
нет. Телефон хранится в международном виде, например `+79001234567`, и не может
одновременно принадлежать двум профилям.

## Подготовка SMSC

1. Создайте аккаунт на [smsc.ru](https://smsc.ru/).
2. В кабинете SMSC выпустите отдельный API-ключ для сайта.
3. При необходимости зарегистрируйте имя отправителя.
4. Пополните баланс и проверьте, разрешена ли отправка на нужные направления.

Логин и пароль кабинета в AVE.cms вводить не нужно. Используйте отдельный
API-ключ, который можно отозвать без смены пароля владельца SMSC.

## Установка и настройка

1. Откройте `Модули -> Управление`.
2. Установите и включите `Вход по SMS (SMSC)`.
3. Откройте `Модули -> Вход по SMS`.
4. Вставьте API-ключ и при необходимости имя отправителя.
5. Оставьте в тексте SMS тег `{code}`.
6. Сохраните настройки.
7. В нижнем блоке отправьте тестовый код на свой номер.
8. Включите публичный вход только после успешного теста.

Общая возможность создавать пользователей и их группа настраиваются в
`Система -> Пользователи сайта -> Регистрация`. Переключатель модуля
`Создавать аккаунты` может дополнительно запретить регистрацию по телефону,
оставив вход существующих пользователей.

## Ограничения кода

| Настройка | Назначение |
| --- | --- |
| Длина кода | От 4 до 8 цифр. Для обычного сайта рекомендуется 6. |
| Код действует | После этого времени код отклоняется. |
| Повторная отправка | Минимальная пауза перед новым SMS в текущей сессии. |
| Попыток ввода | Сколько неверных вводов разрешено одному challenge. |
| SMS в сутки | Суточный предел для одного номера. |

Дополнительно ядро ограничивает частоту запросов по IP и номеру. Новый код
отменяет предыдущий, связан с текущей PHP-сессией и может быть использован
только один раз. В базе хранится bcrypt-хеш кода, а не сам код.

Если создание аккаунтов выключено и номер не найден, публичный ответ всё равно
выглядит как успешный запрос, но SMS не отправляется. Это не позволяет перебирать
зарегистрированные телефоны и не расходует баланс на неизвестные номера.

## Секреты и переменные окружения

Настройки по умолчанию находятся в закрытом хранилище
`storage/secrets/modules/smsc_auth.php`. Их можно переопределить:

```dotenv
SMSC_AUTH_ENABLED=1
SMSC_API_KEY=your-api-key
SMSC_SENDER=AVEcms
```

Не добавляйте файл секретов и рабочий API-ключ в репозиторий, архив модуля,
публичный шаблон или журнал ошибок.

## Публичные шаблоны

Системная форма находится в
`system/App/Frontend/Auth/view/phone.twig`. Для пользовательского шаблона входа
доступен массив `phone_providers`. Если шаблон его не выводит, AVE.cms добавит
рабочую форму после основной формы входа, поэтому старые темы не ломаются.

Публичные Ajax-адреса:

| Метод и адрес | Назначение |
| --- | --- |
| `POST /auth/phone/request` | Нормализует телефон и отправляет код. |
| `POST /auth/phone/verify` | Проверяет challenge и открывает сессию. |

Оба адреса требуют CSRF-токен. Первый также проходит общую защиту публичных
форм и rate limit.

## Удаление модуля

При удалении стираются настройки SMSC и история незавершённых кодов. Пользователи,
подтверждённые телефоны, заказы и профили сохраняются, потому что это общие
данные AVE.cms. Без установленного SMS-провайдера форма входа по телефону просто
не показывается.

## Подключение другого SMS-провайдера

Новый транспорт реализует
`App\Frontend\Auth\Phone\ProviderInterface` и регистрирует экземпляр через:

```php
use App\Frontend\Auth\Phone\ProviderRegistry;

ProviderRegistry::register(new MySmsProvider());
```

Провайдер отвечает только за настройки и отправку `sendCode($phone, $code)`.
Он не должен самостоятельно создавать пользователя, хранить открытый код или
управлять сессией.