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

63 lines
6.3 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. После локальных тестов перезапустить только нужный тестовый сервер по инструкциям deploy (production отдельно согласовывать).
## Процесс
- `CheckRegistrationEmail` проверяет известный занятый email, без отправки.
- `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>
```
Параметры читаются из `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-процесса.