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

97 lines
9.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Подтверждение 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.
## Три настройки сервера
```properties
# Реальный секрет предпочтительно задавать через 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, проверку кода и защиту от ботов.
Быстрая локальная проверка парсера без внешних зависимостей:
```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
```