# Подтверждение 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 `. При необходимости изменить внешним параметром `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. ## Три настройки сервера ```properties # Реальный секрет предпочтительно задавать через RESEND_API_KEY или внешнюю конфигурацию. freeRegistration.email.apiKey= freeRegistration.email.allowTestCode=false freeRegistration.email.allowReuse=false freeRegistration.email.from=SHiNE 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, проверку кода и защиту от ботов. Быстрая локальная проверка парсера без внешних зависимостей: ```bash 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 ```