Huawei SMS

Huawei SMS — небольшой веб-интерфейс и движок SMS-команд для модемов Huawei с HiLink API.

Система регулярно опрашивает модем, переносит входящие и исходящие SMS в локальную базу SQLite и после успешной обработки удаляет их из памяти модема. Благодаря этому память Huawei не забивается, а вся история сообщений остаётся на сервере.

Главная особенность проекта — SMS-команды с доверенных телефонных номеров. К команде можно подключить собственный Bash- или Python-скрипт и выполнить нужную проверку или действие обычным SMS. Сам PHP-код Huawei SMS для этого менять не требуется.

Например:

SMS: Статус
    ↓
Huawei SMS проверяет номер отправителя и команду
    ↓
scripts.local/status.sh
    ↓
текст из стандартного вывода скрипта
    ↓
ответное SMS

Текущая версия: 1.0.2.

Что умеет Huawei SMS

• принимает SMS из памяти Huawei и сохраняет их в SQLite;
• сохраняет исходящие SMS, в том числе отправленные не через веб-интерфейс Huawei SMS;
• после обработки удаляет сообщения из памяти модема;
• показывает входящие и исходящие сообщения в веб-интерфейсе;
• позволяет отправлять SMS из браузера;
• выполняет SMS-команды только с доверенных номеров;
• подключает пользовательские Bash- и Python-обработчики без изменения ядра;
• передаёт результат работы обработчика обратно по SMS;
• не собирает команду оболочки из текста SMS и передаёт аргументы обработчику раздельно;
• ограничивает количество, длину и допустимые значения аргументов команды;
• ограничивает время выполнения и размер вывода пользовательского обработчика;
• ведёт журнал выполнения SMS-команд;
• не повторяет автоматически внешнюю команду после неопределённого аварийного завершения;
• повторяет отправку уже готового ответа без повторного запуска обработчика;
• следит за доступностью модема и умеет сообщать об отказе и восстановлении;
• может выполнять плановую перезагрузку Huawei через API;
• отправляет уведомления через Telegram, MAX и Matrix;
• поддерживает прокси с авторизацией для Telegram и MAX;
• при необходимости может попробовать прямое соединение, если именно прокси недоступен;
• защищает веб-интерфейс паролем;
• поддерживает TOTP как второй фактор входа;
• поддерживает одноразовые ссылки быстрого входа из выбранных каналов уведомлений: пароль остаётся обязательным, а ссылка заменяет только ввод кода TOTP;
• автоматически создаёт и обновляет рабочую базу SQLite.

Штатные SMS-команды

В комплект входят только универсальные команды:

Пинг <IPv4 или имя>
Порт <IPv4 или имя> <порт>
Модем

Пинг и Порт используют scripts/network-check.py.

Модем использует scripts/modem-health.sh и показывает доступность Huawei, состояние соединения, оператора, тип сети, параметры сигнала и число непрочитанных SMS, если соответствующие поля доступны в прошивке модема.

Все команды, завязанные на конкретную инфраструктуру, должны находиться вне ядра — в commands.local.php и scripts.local/.

Пользовательские команды

Для своей SMS-команды нужны два элемента:

commands.local.php     описание команды и её ограничений
scripts.local/         Bash- или Python-обработчик

commands.local.php дополняет штатные команды. Копировать туда Пинг, Порт и Модем не нужно.

Подробное руководство по созданию собственных обработчиков находится в docs/PLUGINS-RU.md. Это основной документ, если Huawei SMS нужен именно как движок удалённых действий по SMS.

Готовый безопасный пример:

examples/plugins/status.sh
examples/plugins/commands-entry.php.example

Как обрабатывается память модема

Каждый запуск cron/poll.php является одноразовым.

Он последовательно:

1. читает сообщения Huawei небольшими порциями;
2. определяет, является ли входящее сообщение SMS-командой;
3. сохраняет сообщение в SQLite;
4. при необходимости выполняет команду и готовит ответ;
5. удаляет обработанное сообщение из памяти Huawei;
6. снова читает первую страницу сообщений;
7. продолжает, пока память соответствующей папки модема не будет обработана полностью или пока Huawei не перестанет удалять сообщения.

После входящих таким же образом обрабатываются исходящие сообщения.

Сообщения, которые администратор сам поместил в локальный список блокировки, являются исключением: они удаляются как нежелательные и записываются в отдельный журнал блокировки, но не сохраняются в обычной истории SMS.

Требования

Для обычной установки нужны:

• Linux;
• PHP 8.2 или новее;
• PHP-FPM;
• расширения PHP curl, mbstring, PDO SQLite и SimpleXML;
• nginx или другой веб-сервер, способный публиковать только каталог public/;
• Python 3;
• Bash;
• утилиты curl и ping для штатных скриптов;
• flock рекомендуется для согласования доступа штатной диагностики к API модема;
• доступ сервера к Huawei HiLink API.

Отдельный сервер MySQL, MariaDB или PostgreSQL не нужен.

Установка

Веб-установщика у Huawei SMS нет. Настройку выполняет администратор сервера.

Кратко:

1. распакуйте проект, например в /srv/huawei-sms;
2. создайте config.local.php из примера;
3. задайте адрес модема, пароль веб-интерфейса и остальные нужные параметры;
4. разрешите рабочему пользователю PHP запись в data/ и logs/;
5. настройте nginx с корнем /srv/huawei-sms/public;
6. запустите предварительную проверку от того же пользователя, от которого работает PHP-FPM и опрос модема;
7. настройте запуск cron/poll.php раз в минуту через таймер systemd или cron.

Полная пошаговая инструкция: INSTALL-RU.md.

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

Рабочие настройки хранятся в:

config.local.php

Локальные SMS-команды:

commands.local.php

Локальный список блокировки:

blocklist.local.php

Пользовательские скрипты:

scripts.local/

Секреты можно хранить отдельными файлами в:

secrets/

Эти данные не входят в репозиторий и не должны попадать в публичный архив.

Описание параметров: docs/CONFIGURATION-RU.md.

Уведомления

Huawei SMS поддерживает три независимых канала:

• Telegram;
• MAX;
• Matrix.

Общий переключатель notifications.enabled разрешает или запрещает механизм уведомлений целиком. Затем каждый канал включается отдельно.

Уведомления могут использоваться для:

• новых входящих SMS;
• успешных и неудачных входов;
• блокировки входа;
• ошибок проверки CSRF;
• перехода модема в состояние «недоступен»;
• восстановления модема;
• начала и результата плановой перезагрузки Huawei.

Для Telegram и MAX можно настроить HTTP-, HTTPS- или SOCKS-прокси, если используемая сборка cURL поддерживает выбранный тип.

fallback_direct=true разрешает прямую попытку только после сетевой ошибки или ошибки самого прокси. Ответ удалённого API с ошибкой, например HTTP 401 или 429, не является поводом обходить прокси.

Веб-интерфейс и авторизация

Логин и хеш пароля задаются вручную в config.local.php.

Хеш пароля:

cd /srv/huawei-sms
read -rsp 'Пароль: ' P; echo
HUAWEI_SMS_PASSWORD="$P" php bin/password-hash.php
unset P

Если PHP поддерживает Argon2id, используется он. Иначе применяется bcrypt.

Для TOTP есть отдельная команда:

php bin/totp-secret.php

Она выводит секрет Base32 и URI otpauth://, который можно добавить в совместимое приложение-аутентификатор.

При нескольких неудачных попытках вход с одного IP временно блокируется. Во время блокировки сервер возвращает HTTP 429 и не выдаёт форму авторизации.

Ошибки пароля, TOTP и quick-login показываются пользователю одинаково. Точный тип события сохраняется во внутреннем журнале.

После успешной проверки логина и пароля дополнительно действует глобальный limiter неверных TOTP, поэтому смена IP не позволяет бесконечно перебирать второй фактор.

Быстрый вход из уведомлений

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

В самом сообщении отображается обычный адрес кабинета:

https://sms.example.org/

При переходе пользователь вводит обычный логин и пароль, но код TOTP для этой попытки не требуется. Пароль остаётся обязательным.

Каждая ссылка создаётся заново и по умолчанию действует 30 минут.

• после успешного входа ссылка сразу удаляется из базы;
• неиспользованная ссылка после истечения срока удаляется периодическим cron/poll.php;
• в SQLite хранится только SHA-256 ключа, а не сам ключ;
• для каждого канала создаётся отдельная ссылка.

Быстрый вход можно независимо включить для Telegram, MAX и Matrix. Если для канала он выключен, используется обычная ссылка и вход выполняется с паролем и TOTP.

Уведомления о событиях веб-авторизации используют обычный адрес кабинета и не создают quick-login token.

В Telegram и MAX предпросмотр страницы для таких уведомлений отключается.

SQLite

Рабочая база по умолчанию:

data/sms.sqlite

Готовая база в репозиторий не входит.

При первом обращении Huawei SMS сам создаёт актуальную схему. Для новой установки не нужно импортировать schema.sql или вручную запускать миграции.

Текущий маркер схемы:

PRAGMA user_version = 6

bin/migrate.php нужен для ручной проверки и обновления существующей установки, а не для первоначального создания базы.

Подробнее: docs/DATABASE-RU.md.

Документация

• INSTALL-RU.md — установка и первый запуск;
• docs/PLUGINS-RU.md — подробное создание собственных SMS-команд;
• docs/COMMANDS-RU.md — работа штатного механизма команд;
• docs/CONFIGURATION-RU.md — параметры config.local.php;
• docs/ARCHITECTURE-RU.md — устройство проекта;
• docs/DATABASE-RU.md — SQLite, хранение и восстановление;
• docs/UPDATE-RU.md — обновление установленной системы;
• SECURITY.md — безопасная эксплуатация;
• LICENSING-RU.md — пояснение лицензии;
• THIRD_PARTY-RU.md — внешние программы и библиотеки;
• CHANGELOG.md — изменения версии.

Лицензия

Huawei SMS распространяется по PolyForm Noncommercial License 1.0.0.

Бесплатное некоммерческое использование, изменение и распространение разрешаются в пределах условий лицензии. Коммерческое использование, продажа программы, перепродажа изменённой версии и включение Huawei SMS в платный продукт или услугу без отдельного разрешения не допускаются.

Программное обеспечение предоставляется без гарантий. Подробности: LICENSE и LICENSING-RU.md.

Автор

Разработка: Виталий Егоров
E-mail: egorowitaliy@gmail.com