Files
SHiNE-server/docs/registration-v2/RESEND_EMAIL_VERIFICATION.md
T

9.8 KiB
Raw Blame History

Подтверждение email при бесплатной регистрации SHiNE

Реализация: SHiNE-server/shine-server-archive/src/main/java/server/archive/registration/.

Подключение Resend

  1. В Resend подтвердить shineup.me (DNS DKIM + отправляющие CNAME), статус Verified.
  2. Получить в Resend API key с правом Sending access.
  3. Указать API-ключ как RESEND_API_KEY в окружении Java-процесса (предпочтительно) или через freeRegistration.email.apiKey во внешнем, недоступном из Git application.properties. Никогда не коммитить реальный ключ, не печатать в журнале и не отдавать клиенту.
  4. Настройка freeRegistration.email.from. По умолчанию отправитель: SHiNE <noreply@shineup.me>. При необходимости изменить внешним параметром freeRegistration.email.from, но адрес обязан относиться к подтверждённому домену.
  5. Настройка freeRegistration.email.allowTestCode=false по умолчанию. Только для тестирования true разрешает код 777777 на этапе подтверждения любой активной заявки. Это полностью обходит подтверждение владения email и НЕ ДОЛЖНО использоваться на публичном/production-сервере.
  6. На сервере, где freeRegistration.enabled=true, без API-ключа Resend старт завершится ошибкой (fail-closed), даже если тестовый код включён. При создании заявки письмо всегда отправляется.
  7. В корне репозитория есть allowed-email-domains.txt — закрытый список допустимых почтовых доменов. Файл копируется скриптом deploy/scripts/deploy_server.sh рядом с JAR в рабочую директорию сервера. Не кладите его внутрь JAR и не задавайте путь из UI: проверка выполняется на сервере. При необходимости путь можно изменить через freeRegistration.email.allowedDomainsFile (относительный путь — от рабочей директории Java-процесса). ./gradlew startLocal передаёт абсолютный путь к файлу в корне репозитория, поскольку запускает JAR из SHiNE-server/. После изменения списка или пути требуется перезапуск процесса. Если freeRegistration.enabled=true, а файл отсутствует, пустой или содержит некорректные домены, регистрация не запустится (fail-closed). На выключенную бесплатную регистрацию этот файл не влияет.
  8. После локальных тестов перезапустить только нужный тестовый сервер по инструкциям deploy (production отдельно согласовывать).

Процесс

  • CheckRegistrationEmail проверяет домен по allowed-email-domains.txt и затем занятость email, без отправки. Если домен не разрешён, возвращается emailAvailable=false без запроса к БД. Формат API не менялся: false означает «адрес занят или домен не разрешён». То же ограничение повторно применяется в StartFreeRegistration, включая прямые запросы к API. Список проверяется по точному совпадению после @ (регистр не важен), поддомены и wildcard не допускаются. Список ограничивает только бесплатную регистрацию с подтверждением email, не регистрацию через Solana.
  • StartFreeRegistration создаёт случайный 6-значный код и challenge, отправляет письмо через HTTP API Resend; только после ответа 2xx возвращает challengeId и expiresAtMs.
  • ConfirmFreeRegistration принимает код для конкретного challenge. После верного кода подписывает сертификат и публикует прежним Turbo/Arweave путём. Формат WS/API и сертификата не меняется.
  • Код действует 1 час, хранится в памяти как SHA-256(challengeId + : + code), максимум 5 ошибок на challenge. Повторная отправка ограничена одной попыткой в минуту на email и логин. Общий лимит — 60 отправок в час на процесс. Повторная публикация сертификата после сетевой ошибки допускается до конца TTL.
  • Данные challenge в памяти: после перезапуска сервера ещё не подтверждённый код перестаёт действовать; пользователь начинает новую заявку. Для нескольких Java-инстансов понадобится общее хранилище TTL (Redis/Postgres), иначе challenge, созданный на одном узле, не подтвердится на другом.
  • При HTTP-ошибке Resend заявка удаляется, код не считается отправленным.

Проверка

  1. Для тестового окружения задать RESEND_API_KEY в systemd EnvironmentFile (файл с ограниченными правами), не добавляя ключ в репозиторий. При изменении секрета перезапустить сервис.
  2. Зарегистрировать новый login@free и доступный адрес email.
  3. Проверить письмо, неверный код, истечение срока, пять ошибок, повторную отправку через минуту, успешное подтверждение, Turbo ACK и отсутствие email/кода в системных журналах.
  4. Проверить ошибки/квоту Resend в панели провайдера и корректное поведение UI.

Сервис Resend может принять запрос на отправку, но не гарантирует доставку во входящие пользователя; статусы доставки анализируются в панели Resend, особенно для bounce/spam.

Три настройки сервера

# Реальный секрет предпочтительно задавать через RESEND_API_KEY или внешнюю конфигурацию.
freeRegistration.email.apiKey=
freeRegistration.email.allowTestCode=false
freeRegistration.email.allowReuse=false
freeRegistration.email.from=SHiNE <noreply@shineup.me>
freeRegistration.email.allowedDomainsFile=allowed-email-domains.txt

Параметры читаются из AppConfig: системное свойство → переменная окружения (FREE_REGISTRATION_EMAIL_API_KEY, FREE_REGISTRATION_EMAIL_ALLOW_TEST_CODE, FREE_REGISTRATION_EMAIL_FROM) → внешний application.properties → встроенный файл. RESEND_API_KEY имеет приоритет над freeRegistration.email.apiKey.

Ограничение: чит-код действует только для уже созданного challenge, когда Resend успешно принял запрос на отправку. Он не создаёт пользователя без StartFreeRegistration и не работает после истечения 1 часа или перезапуска Java.

Для применения изменений настроек нужен перезапуск Java-процесса.

Обновление разрешённых почтовых доменов

Редактируйте allowed-email-domains.txt в корне проекта: по одному домену на строку, без символа @; строки с # — комментарии. Например gmail.com, но не *.gmail.com. user@gmail.com и user@GMAIL.COM подходят, user@sub.gmail.com — нет, пока его не добавили отдельной строкой. Новые домены не подхватываются до перезапуска. Список ограничивает злоупотребления, но сам по себе не гарантирует доставку письма и не заменяет rate limiting, проверку кода и защиту от ботов.

Быстрая локальная проверка парсера без внешних зависимостей:

mkdir -p /tmp/shine-allowlist-check
javac -d /tmp/shine-allowlist-check \
  SHiNE-server/shine-server-archive/src/main/java/server/archive/registration/AllowedEmailDomains.java \
  SHiNE-server/shine-server-archive/src/test/java/server/archive/registration/AllowedEmailDomainsCheck.java
java -cp /tmp/shine-allowlist-check server.archive.registration.AllowedEmailDomainsCheck