feat(identity): verify registration email by otp and sign in on verify (BF-379)

[zaxovaiko]

Summary

Registration now mails a six-digit code instead of a magic link, and verifying that code is what mints the session. Email verification enforcement moves behind registration.requireEmailVerification (default off). BF-379.

Why

Two acceptance criteria contradicted what shipped: "successful registration creates a session and redirects to the homepage", and "unverified players are not restricted while the KYC toggle is off".

They cannot both be satisfied at sign-up. better-auth only returns its indistinguishable duplicate-email response when autoSignIn is off or verification is required, so minting the session at sign-up would have traded away the "registering with an already used email does not reveal whether the account exists" criterion. Moving the session to the verification step satisfies all three: sign-up stays sessionless and indistinguishable, and the player is signed in the moment they enter the code.

The verification gate on sign-in was unconditional, which locked out every unverified account. It is now operator config, defaulting off, so unverified players stay unrestricted until KYC is turned on.

The RG and suspension gate was duplicated across password login and phone login. The new verification path mints a session too, so it needed the same gate; rather than add a third copy, the check moved into one shared implementation in rg-guard.service.ts that all three call. A gate only some login paths enforce is not a gate.

Alternatives considered

• autoSignIn: true at sign-up. Simplest reading of the ticket, but it turns off better-auth's generic duplicate-email response and hands back account enumeration on the registration form.
• Keeping verification mandatory and treating the ticket as wrong. Rejected: the product decision is explicit that unverified players are unrestricted while KYC is off.
• emailOTP({ sendVerificationOnSignUp: true }) to mail the code. Rejected: that hook fires off the sign-up response, which on the duplicate-email path carries a synthetic user with the real owner's address. It would mail a live code to someone who never registered, and verifying that code signs its bearer in. The code is therefore sent explicitly from register(), only in the genuinely-new-user branch.
• Leaving the link flow in place alongside the code. Rejected as dead surface once nothing issues links.

Risks

Breaking changes for downstream operators:

• verifyEmail takes { email, otp } instead of { token } and returns { user, session } (or { twoFactorRedirect: true }) instead of { success }.
• sendEmailVerification takes { email } and is unauthenticated, since the player has no session until the code is verified. It always answers success and only mails an account that exists and is still unverified.
• The verifyEmail email template renders an otp instead of a url/token; custom renderers need updating.
• registration.webUrl is removed and registration.requireEmailVerification added. RegistrationConfigSchema is .strict(), so an operator config still carrying webUrl now fails validation at boot rather than being ignored.

Operational:

• With the gate off by default, an unverified account is fully functional: someone can register an address they do not control, play and cash out, and the real owner can no longer register that address. This follows the product decision that unverified players are unrestricted while KYC is off, and is flagged rather than overridden. Operators wanting the stricter behaviour set registration.requireEmailVerification: true.
• A 2FA-enrolled account is verified but deliberately not signed in by the code: better-auth mints that session through createSession, which its twoFactor plugin does not hook, so the code alone would otherwise bypass the second factor. Such accounts get twoFactorRedirect and sign in through login.
• The verify and resend rate-limit budgets fail closed, so a limiter outage rejects verification attempts rather than opening a brute-force window on a six-digit code.