@openora/core 0.4.1-canary.16 → 0.4.1-canary.161

package/dist/pam/identity/service/identity.service.js

@@ -1,9 +1,18 @@
+import { randomUUID } from 'node:crypto';
 import { ORPCError } from '@orpc/server';
-import { createAuth, assertRateLimit, findOneOrThrow, makeNotFoundError, } from '@openora/core/server';
+import { createAuth, assertRateLimit, extractClientMeta, getCurrentClientMeta, findOneOrThrow, makeConflictError, makeNotFoundError, createLogger, } from '@openora/core/server';
 import { parseCookies } from 'better-auth/cookies';
-import { eq, sql } from 'drizzle-orm';
+import { and, eq, isNull, lte, ne, sql } from 'drizzle-orm';
+import * as z from 'zod';
 import { user, session, account, verification, twoFactor } from '../schema/index.js';
+import { captureTimezone } from './capture-timezone.service.js';
+import { maskEmail, maskPhone, } from './two-factor-delivery.service.js';
+import { RATE_LIMIT_KEYS, makeRateLimitKey } from '@openora/core/contracts';
 import { assertSupportedLanguage } from '../../shared/language.js';
+import { assertAccountNotBlocked } from './rg-guard.service.js';
+import { DEFAULT_LOCKOUT_DURATION_MS, DEFAULT_MAX_LOGIN_ATTEMPTS, computeLockoutTier, createAccountLockedError, hasFailedLoginWindowExpired, makeLoginSecurityState, } from './lockout-policy.service.js';
+import { getSecurityControls } from './security-controls.service.js';
+import { resolveChallengeMethod, verifyChallengeCode } from './two-factor-challenge.service.js';
 function nodeHeadersToHeaders(nodeHeaders) {
     const headers = new Headers();
     for (const [key, value] of Object.entries(nodeHeaders)) {
@@ -14,14 +23,22 @@ function nodeHeadersToHeaders(nodeHeaders) {
     }
     return headers;
 }
-export function createAccountLockedError(lockoutUntil) {
-    return new ORPCError('UNAUTHORIZED', {
-        message: 'Account is temporarily locked. Please try again later.',
-        data: {
-            code: 'ACCOUNT_LOCKED',
-            lockoutUntil: lockoutUntil.toISOString(),
-        },
-    });
+// Deletes every session row for `userId` created at or before `deadline`, except the
+// caller's freshly minted one (matched by `sparedToken`), and returns the ids of what
+// it deleted. Run a short delay after a password change: better-auth rotates the
+// password hash and deletes sessions in separate, untransacted statements, so a
+// sign-in that verified the OLD password just before the rotation can still insert
+// its session row immediately after `deleteUserSessions()` ran. That row predates
+// `deadline` (captured once the change is known committed), so this catches it while
+// sparing anything created afterwards.
+// Exported for direct testing; the service schedules it via setTimeout.
+export async function sweepRacedSessionsAfterPasswordChange(db, params) {
+    const { userId, sparedToken, deadline } = params;
+    const deleted = await db
+        .delete(session)
+        .where(and(eq(session.userId, userId), ne(session.token, sparedToken), lte(session.createdAt, deadline)))
+        .returning({ id: session.id });
+    return deleted.map((row) => row.id);
 }
 function toIso(value) {
     return value instanceof Date ? value.toISOString() : value;
@@ -31,22 +48,18 @@ function toUser(u) {
         id: u.id,
         email: u.email,
         name: u.name,
+        username: u.username,
         emailVerified: u.emailVerified,
         theme: u.theme ?? 'system',
         language: u.language ?? 'en',
+        twoFactorEnabled: u.twoFactorEnabled ?? false,
         createdAt: toIso(u.createdAt),
         updatedAt: toIso(u.updatedAt),
     };
     return u.image !== undefined ? { ...base, image: u.image } : base;
 }
-function forwardCookies(authResponse, resHeaders) {
-    const cookies = authResponse.headers.getSetCookie?.() ?? [];
-    for (const cookie of cookies) {
-        resHeaders.append('set-cookie', cookie);
-    }
-}
-function clientIp(headers) {
-    return headers.get('x-forwarded-for')?.split(',')[0]?.trim() || headers.get('x-real-ip') || null;
+function makeLoginRateLimitKey(email) {
+    return `login:${email.toLowerCase()}`;
 }
 // Key on the `.two_factor` cookie VALUE, never the raw Cookie header: an attacker can
 // otherwise churn the rate-limit key each retry by appending unrelated cookie pairs.
@@ -62,31 +75,113 @@ function twoFactorPendingCookieValue(headers) {
     }
     return undefined;
 }
+// A web Response exposes Set-Cookie as full attribute strings; a request carries only
+// the name=value pairs.
+function requestCookieHeader(res) {
+    return (res.headers.getSetCookie?.() ?? [])
+        .map((cookie) => {
+        const [pair = ''] = cookie.split(';');
+        return pair.trim();
+    })
+        .filter((pair) => pair.length > 0)
+        .join('; ');
+}
+function hasTrustDeviceCookie(headers) {
+    const cookieHeader = headers.get('cookie');
+    if (!cookieHeader) {
+        return false;
+    }
+    for (const [name] of parseCookies(cookieHeader)) {
+        if (name.endsWith('.trust_device')) {
+            return true;
+        }
+    }
+    return false;
+}
+// better-auth sets `<prefix>.dont_remember` when a user signs in with `rememberMe: false`.
+// Presence is enough here: we only use it to shorten the caller's own rotated session,
+// so a forged cookie can at worst clamp its owner's session earlier - never extend one.
+function hasDontRememberCookie(headers) {
+    const cookieHeader = headers.get('cookie');
+    if (!cookieHeader) {
+        return false;
+    }
+    for (const [name] of parseCookies(cookieHeader)) {
+        if (name.endsWith('.dont_remember') || name === 'dont_remember') {
+            return true;
+        }
+    }
+    return false;
+}
+// Drops the one pair and leaves every other byte alone: the cookies that stay carry
+// signed, percent-encoded values better-auth re-verifies exactly as the browser sent them.
+function withoutTrustDeviceCookie(headers) {
+    const cookieHeader = headers.get('cookie');
+    if (!cookieHeader) {
+        return headers;
+    }
+    const kept = cookieHeader
+        .split(';')
+        .map((pair) => pair.trim())
+        .filter((pair) => {
+        const [name = ''] = pair.split('=');
+        return !name.endsWith('.trust_device');
+    });
+    const next = new Headers(headers);
+    if (kept.length === 0) {
+        next.delete('cookie');
+    }
+    else {
+        next.set('cookie', kept.join('; '));
+    }
+    return next;
+}
 const SUCCESS = { success: true };
 export const UserNotFoundError = makeNotFoundError('User');
+export const UsernameConflictError = makeConflictError('Username', 'Username is already in use');
+const BetterAuthErrorBodySchema = z.object({
+    message: z.string().optional(),
+    code: z.string().optional(),
+});
 // better-auth calls use `asResponse: true`, which returns an error *Response*
 // (4xx/5xx) rather than throwing. Surface those as ORPCErrors so oRPC maps them
 // to the right HTTP status instead of the handler silently returning success.
 // Only reads the body on failure, so a subsequent res.json() on success is safe.
-async function ensureOk(res) {
+// 401 -> UNAUTHORIZED (bad credentials), 403 -> FORBIDDEN (better-auth's
+// TOO_MANY_ATTEMPTS on checkVerificationOTP/resetPasswordEmailOTP), else BAD_REQUEST.
+// `opts.genericMessage` lets a BAD_REQUEST *or* FORBIDDEN caller opt into a fixed
+// message instead of better-auth's raw one - some better-auth 400s (eg
+// checkVerificationOTP's USER_NOT_FOUND-before-INVALID_OTP ordering) leak account
+// existence otherwise. When genericMessage is set, a 403 is masked down to
+// BAD_REQUEST too, so a caller can't tell "too many attempts" apart from "wrong code".
+async function ensureOk(res, opts) {
     if (res.ok) {
         return;
     }
+    const code = res.status === 401 ? 'UNAUTHORIZED' : res.status === 403 ? 'FORBIDDEN' : 'BAD_REQUEST';
+    if ((code === 'BAD_REQUEST' || code === 'FORBIDDEN') && opts?.genericMessage) {
+        throw new ORPCError(code === 'FORBIDDEN' ? 'BAD_REQUEST' : code, {
+            message: opts.genericMessage,
+        });
+    }
     let message = `Request failed (${res.status})`;
-    try {
-        const parsed = JSON.parse(await res.text());
-        if (parsed.message) {
-            message = parsed.message;
+    let betterAuthCode;
+    const body = BetterAuthErrorBodySchema.safeParse(await res.json().catch(() => null));
+    if (body.success) {
+        if (body.data.message) {
+            message = body.data.message;
+        }
+        if (body.data.code) {
+            betterAuthCode = body.data.code;
         }
     }
-    catch {
-        // non-JSON body - keep the default message
-    }
-    throw new ORPCError(res.status === 401 ? 'UNAUTHORIZED' : 'BAD_REQUEST', { message });
+    throw new ORPCError(code, {
+        message,
+        ...(betterAuthCode ? { data: { code: betterAuthCode } } : {}),
+    });
 }
-const DEFAULT_MAX_LOGIN_ATTEMPTS = 5;
-const DEFAULT_LOCKOUT_DURATION_MS = 15 * 60 * 1000;
 const MINUTE_MS = 60 * 1000;
+export const SESSION_DURATION_IN_SECONDS = 30 * 24 * 60 * 60; // 30 days
 // Coarse abuse throttles keyed by the caller identifier the context provides (email/
 // token/session), NOT IP. The lockout above is a per-account credential-failure
 // counter; these bound raw request volume on each brute-force surface. An overlay
@@ -96,29 +191,76 @@ const MINUTE_MS = 60 * 1000;
 // throttles (register/resend/etc.) keep the default fail-open.
 const LOGIN_RATE_LIMIT = { limit: 10, windowMs: 5 * MINUTE_MS, onUnavailable: 'deny' };
 const REGISTER_RATE_LIMIT = { limit: 5, windowMs: 15 * MINUTE_MS };
+// Keyed on the caller, not the handle: the abuse shape here is enumerating many
+// usernames from one client, not probing one username repeatedly.
+const USERNAME_AVAILABILITY_RATE_LIMIT = { limit: 30, windowMs: MINUTE_MS };
 const PASSWORD_RESET_REQUEST_RATE_LIMIT = { limit: 3, windowMs: 15 * MINUTE_MS };
 const PASSWORD_RESET_RATE_LIMIT = {
     limit: 5,
     windowMs: 15 * MINUTE_MS,
     onUnavailable: 'deny',
 };
+const PASSWORD_RESET_VERIFY_RATE_LIMIT = {
+    limit: 5,
+    windowMs: 5 * MINUTE_MS,
+    onUnavailable: 'deny',
+};
 const VERIFY_2FA_RATE_LIMIT = { limit: 5, windowMs: 5 * MINUTE_MS, onUnavailable: 'deny' };
-const EMAIL_VERIFICATION_RATE_LIMIT = { limit: 3, windowMs: 15 * MINUTE_MS };
-const VERIFY_EMAIL_RATE_LIMIT = { limit: 5, windowMs: 15 * MINUTE_MS };
+// Fails closed with the verify budget below: better-auth issues a fresh code (and a fresh
+// 3-attempt counter) per resend, so an unbounded resend loop is an unbounded guess budget.
+const EMAIL_VERIFICATION_RATE_LIMIT = {
+    limit: 3,
+    windowMs: 15 * MINUTE_MS,
+    onUnavailable: 'deny',
+};
+// Fails closed like the other secret-guessing budgets: the emailed code is six digits,
+// so an unthrottled window is a brute-force window, not a degraded-UX window.
+const VERIFY_EMAIL_RATE_LIMIT = {
+    limit: 5,
+    windowMs: 15 * MINUTE_MS,
+    onUnavailable: 'deny',
+};
 const CHANGE_PASSWORD_RATE_LIMIT = { limit: 5, windowMs: 15 * MINUTE_MS };
+// How long after a password change to re-sweep the user's sessions for a row that a
+// concurrent old-password sign-in raced in just after better-auth's revoke ran. This
+// is the residual exposure window; keep it short.
+const RACED_SESSION_SWEEP_DELAY_MS = 2_000;
+// better-auth's `createSession` gives a `dontRememberMe` session this fixed TTL
+// (`getDate(3600 * 24, 'sec')`). `revokeOtherSessions` mints the caller's replacement
+// session without that flag, so we re-apply the clamp when the request carries the
+// `dont_remember` cookie. Matches `SESSION_TTL_MS` in phone-login.service.
+const DONT_REMEMBER_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 const TWO_FACTOR_PASSWORD_RATE_LIMIT = { limit: 5, windowMs: 5 * MINUTE_MS };
-// Mirrors better-auth session.expiresIn (server/auth/auth.ts); used only as a fallback
-// when the sign-in response omits an explicit session expiry.
-const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+// Fails closed: every call spends real money on an `sms` enrolment and fills a mailbox
+// on an `email` one, and better-auth issues a fresh code per send, so an unbounded
+// resend loop is both a toll-fraud channel and an unbounded guess budget.
+const SEND_2FA_OTP_RATE_LIMIT = {
+    limit: 3,
+    windowMs: 5 * MINUTE_MS,
+    onUnavailable: 'deny',
+};
+const ANTI_PHISHING_CODE_RATE_LIMIT = {
+    limit: 5,
+    windowMs: 5 * MINUTE_MS,
+    onUnavailable: 'deny',
+};
+const FAKE_LOGIN_SHADOW_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+function loginShadowKey(email) {
+    return `login-shadow:${email}`;
+}
+const loginShadowLogger = createLogger('login-shadow');
+const identityLogger = createLogger('identity');
+function hasErrorCode(error, code) {
+    if (typeof error !== 'object' || error === null || !('data' in error)) {
+        return false;
+    }
+    const data = error.data;
+    return typeof data === 'object' && data !== null && 'code' in data && data.code === code;
+}
 function computeLockoutState({ attempts, maxAttempts, durationMs, nowMs, }) {
     const isLocking = attempts >= maxAttempts;
     return { isLocking, lockoutUntil: isLocking ? new Date(nowMs + durationMs) : null };
 }
-// A finite rgBlockedUntil in the past = a lapsed cooling-off; a null one = indefinite
-// (self-exclusion / permanent). Blocked only while set and not elapsed.
-function isRgBlocked(u) {
-    return u.rgBlocked && (u.rgBlockedUntil === null || u.rgBlockedUntil > new Date());
-}
 /**
  * Thin wrapper over the shared better-auth instance (register/login/2FA/
  * password/email flows) that layers on platform-specific policy better-auth
@@ -132,44 +274,303 @@ export class IdentityService {
     auth;
     drizzle;
     events;
-    email;
+    identityReader;
+    mailDispatch;
     options;
     limiter;
     platformConfig;
-    constructor({ drizzle, events, email, options, limiter, platformConfig }) {
+    playerProvisioning;
+    geoCheck;
+    cache;
+    // Addresses whose reset code is being sent because a sign-up hit an existing account.
+    // Held only for the duration of that send: `requestPasswordResetEmailOTP` drives
+    // `sendVerificationOTP` -> `render` inside the same await, so the flag is read before
+    // the `finally` clears it. Not cache-backed - it never has to outlive the call or
+    // cross a process.
+    existingAccountSignUps = new Set();
+    trustedDevices;
+    twoFactorLockout;
+    twoFactorDelivery;
+    sessions;
+    constructor({ drizzle, events, identityReader, mailDispatch, options, limiter, platformConfig, geoCheck, playerProvisioning, cache, trustedDevices, twoFactorLockout, twoFactorDelivery, sessions, }) {
         this.drizzle = drizzle;
         this.events = events;
-        this.email = email;
+        this.identityReader = identityReader;
+        this.mailDispatch = mailDispatch;
         this.options = options;
         this.limiter = limiter;
         this.platformConfig = platformConfig;
+        this.geoCheck = geoCheck;
+        this.playerProvisioning = playerProvisioning;
+        this.cache = cache;
+        this.trustedDevices = trustedDevices;
+        this.twoFactorLockout = twoFactorLockout;
+        this.twoFactorDelivery = twoFactorDelivery;
+        this.sessions = sessions;
         this.auth = createAuth({
             db: drizzle.db,
             schema: { user, session, account, verification, twoFactor },
-            ...(email ? { sendEmail: (args) => email.send(args) } : {}),
+            ...(mailDispatch
+                ? {
+                    dispatchOtpMail: async ({ to, template }) => {
+                        const idempotencyKey = `otp:${template.key}:${randomUUID()}`;
+                        const recipient = await this.findUserByEmail(to);
+                        if (recipient) {
+                            await mailDispatch.toUser({ userId: recipient.id, template, idempotencyKey });
+                            return;
+                        }
+                        await mailDispatch.toAddress({ email: to, template, idempotencyKey });
+                    },
+                }
+                : {}),
+            // Binds the plugin's OTP hook to the transport fan-out. Without it better-auth
+            // still mints codes for the `email`/`sms` methods and drops them on the floor.
+            twoFactor: { sendOtp: (args) => twoFactorDelivery.deliver(args) },
+            requireEmailVerification: this.platformConfig?.registration?.requireEmailVerification ?? false,
+            isExistingAccountSignUp: (lookupEmail) => this.existingAccountSignUps.has(lookupEmail.toLowerCase()),
+            isAdminPasswordReset: (lookupEmail) => this.isAdminPasswordReset(lookupEmail),
+            onExistingUserSignUp: async (existing) => {
+                const key = existing.email.toLowerCase();
+                this.existingAccountSignUps.add(key);
+                try {
+                    const response = await this.api.requestPasswordResetEmailOTP({
+                        body: { email: existing.email },
+                        headers: new Headers(),
+                        asResponse: true,
+                    });
+                    await ensureOk(response);
+                }
+                finally {
+                    this.existingAccountSignUps.delete(key);
+                }
+            },
+            onPasswordReset: async (resetUser) => {
+                await this.drizzle.db
+                    .update(user)
+                    .set({ passwordMeetsPolicy: true })
+                    .where(eq(user.id, resetUser.id));
+                this.events.emit('identity.password.reset', {
+                    userId: resetUser.id,
+                    playerId: await this.identityReader.getPlayerIdByUserIdSafe(resetUser.id),
+                    ...getCurrentClientMeta(),
+                });
+                await this.clearLockout(resetUser.id);
+            },
         });
     }
+    async findUserByEmail(email) {
+        const [row] = await this.drizzle.db
+            .select({ id: user.id })
+            .from(user)
+            .where(eq(user.email, email.toLowerCase()))
+            .limit(1);
+        return row;
+    }
     get api() {
         // Library boundary: the admin/organization plugin endpoints aren't on better-auth's
         // base `api` type. Sanctioned cast, see conventions.
         return this.auth.api;
     }
+    forwardCookies(authResponse, resHeaders) {
+        const cookies = authResponse.headers.getSetCookie?.() ?? [];
+        for (const cookie of cookies) {
+            resHeaders.append('set-cookie', cookie);
+        }
+    }
     async currentUserId(headers) {
-        const session = await this.auth.api.getSession({ headers });
-        return session?.user?.id ?? null;
+        return (await this.currentSession(headers))?.userId ?? null;
+    }
+    // Both the caller's userId and the id of the session row they are authenticating
+    // with, for handlers that must tell the caller's own device apart from their others
+    // (eg sparing the acting session from a revoke-all).
+    async currentSession(headers) {
+        const resolved = await this.auth.api.getSession({ headers });
+        const userId = resolved?.user?.id;
+        return userId ? { userId, sessionId: resolved?.session?.id } : null;
+    }
+    async securityControlsFor(userId) {
+        // 0 when trusted devices are not wired at all (some deployments), matching what
+        // `trust()` itself does with a non-positive `trustedDeviceDays`: a client reading 0
+        // knows the offer is not real anywhere it might otherwise render one.
+        const controls = await getSecurityControls(this.drizzle, userId, this.trustedDevices?.getTrustedDeviceDays() ?? 0);
+        if (!controls) {
+            throw new UserNotFoundError(userId);
+        }
+        return controls;
+    }
+    // Same gate as password login and phone login, from the one shared implementation.
+    assertAccountNotBlocked(account, meta) {
+        return assertAccountNotBlocked({ drizzle: this.drizzle, events: this.events }, account, meta, {
+            revokeSessions: true,
+            errorData: { rgBlocked: { code: 'RG_BLOCKED' }, suspended: { code: 'ACCOUNT_SUSPENDED' } },
+        });
     }
-    async register(input, reqHeaders, resHeaders) {
-        await assertRateLimit(this.limiter, `register:${input.email.toLowerCase()}`, REGISTER_RATE_LIMIT);
+    /**
+     * Emitted on every registration attempt that produced no account. The audit trail is
+     * the one place that records what actually happened - the HTTP response deliberately
+     * does not, because a truthful answer on a known address is an enumeration oracle.
+     */
+    emitRegistrationFailed(reason, input, { ip, userAgent }) {
+        this.events.emit('identity.user.registration.failed', {
+            email: input.email,
+            username: input.username,
+            reason,
+            ip,
+            userAgent,
+        });
+    }
+    async register(input, reqHeaders) {
+        // Read before the config guard: a rejected attempt is audited too, and an audit row
+        // with no origin is barely a record.
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        const meta = { ip, userAgent };
+        const registration = this.platformConfig?.registration;
+        const provisioning = this.playerProvisioning;
+        if (!registration || !provisioning) {
+            this.emitRegistrationFailed('registration_disabled', input, meta);
+            throw new ORPCError('FORBIDDEN', { message: 'Registration is unavailable' });
+        }
+        // `assertRateLimit` throws and is shared by a dozen call sites, so the emit wraps it
+        // here rather than moving into it.
+        try {
+            await assertRateLimit(this.limiter, `register:${input.email.toLowerCase()}`, REGISTER_RATE_LIMIT);
+            await assertRateLimit(this.limiter, `register-ip:${ip ?? 'unknown'}`, REGISTER_RATE_LIMIT);
+        }
+        catch (err) {
+            this.emitRegistrationFailed('rate_limited', input, meta);
+            throw err;
+        }
+        if (this.geoCheck && !(await this.geoCheck.checkRegistration(ip)).allowed) {
+            this.emitRegistrationFailed('geo_blocked', input, meta);
+            throw new ORPCError('FORBIDDEN', { message: 'Registration is unavailable' });
+        }
         const headers = nodeHeadersToHeaders(reqHeaders);
-        const authResponse = await this.auth.api.signUpEmail({
-            body: { email: input.email, password: input.password, name: input.name },
+        const authResponse = await this.api.signUpEmail({
+            body: {
+                email: input.email,
+                password: input.password,
+                name: input.username,
+                username: input.username,
+            },
             headers,
             asResponse: true,
         });
-        forwardCookies(authResponse, resHeaders);
+        if (!authResponse.ok) {
+            // The `lower(username)` unique index is the only arbiter - a pre-flight check
+            // could not close the race anyway, so the taken handle is read off the failure.
+            if (await this.findUserIdByUsername(input.username)) {
+                this.emitRegistrationFailed('username_taken', input, meta);
+                throw new UsernameConflictError();
+            }
+            // `ensureOk` always throws on a non-ok response, so emitting first needs no catch.
+            this.emitRegistrationFailed('error', input, meta);
+            await ensureOk(authResponse, { genericMessage: 'Registration is unavailable' });
+        }
         const body = (await authResponse.json());
-        this.events.emit('identity.user.registered', { userId: body.user.id });
-        return { user: toUser(body.user) };
+        // A known address gets an indistinguishable success response (and a reset mail)
+        // rather than a new account, so only a genuinely new user is provisioned.
+        if ((await this.findUserIdByEmail(input.email)) !== body.user.id) {
+            // The known-address branch: no account was created, so the attempt failed even
+            // though the caller is told it succeeded. Only the audit trail says so.
+            this.emitRegistrationFailed('email_already_registered', input, meta);
+            return { status: 'check-email' };
+        }
+        await this.drizzle.db
+            .update(user)
+            .set({ passwordMeetsPolicy: true })
+            .where(eq(user.id, body.user.id));
+        let consent;
+        try {
+            consent = await this.recordRegistrationConsent(provisioning, body.user.id, registration.termsVersion, { ip, userAgent });
+        }
+        catch (err) {
+            this.emitRegistrationFailed('error', input, meta);
+            throw err;
+        }
+        const { playerId, consentStored } = consent;
+        // After the consent write, which is what materialises the player row the zone lands on.
+        // No session yet, but the browser is here now and a first login may be days away.
+        await captureTimezone(this.playerProvisioning, body.user.id, input.timezone);
+        this.events.emit('identity.user.registered', {
+            userId: body.user.id,
+            playerId: playerId ?? (await this.identityReader.getPlayerIdByUserIdSafe(body.user.id)),
+            // Only claimed when the consent row was actually written - a discarded capture
+            // must not leave an audit trail implying evidence that does not exist.
+            ...(consentStored
+                ? {
+                    termsVersion: registration.termsVersion,
+                    acceptedTerms: input.acceptedTerms,
+                    acceptedAge: input.acceptedAge,
+                }
+                : {}),
+            ip,
+            userAgent,
+        });
+        // Sent here rather than by better-auth's sendOnSignUp hook: that hook also fires on
+        // the synthetic duplicate-email response, mailing a live code to an address whose
+        // owner never asked for it - and `verifyEmail` signs that code's bearer in.
+        // A mail failure is logged, never surfaced: the account exists either way and the
+        // player can ask for a new code, so failing the call here would only mislead them.
+        const otpResponse = await this.api.sendVerificationOTP({
+            body: { email: input.email, type: 'email-verification' },
+            headers,
+            asResponse: true,
+        });
+        if (!otpResponse.ok) {
+            identityLogger.error({ userId: body.user.id, status: otpResponse.status }, 'verification code could not be sent - player must request a new one');
+        }
+        return { status: 'check-email' };
+    }
+    async findUserIdByUsername(username) {
+        const [row] = await this.drizzle.db
+            .select({ id: user.id })
+            .from(user)
+            .where(eq(sql `lower(${user.username})`, username.toLowerCase()))
+            .limit(1);
+        return row?.id ?? null;
+    }
+    async findUserIdByEmail(email) {
+        const [row] = await this.drizzle.db
+            .select({ id: user.id })
+            .from(user)
+            .where(eq(user.email, email.toLowerCase()))
+            .limit(1);
+        return row?.id ?? null;
+    }
+    /**
+     * Better Auth commits the user inside its own transaction before returning, so a
+     * failure here would otherwise leave an account with no consent record. The user is
+     * deleted instead (sessions and accounts cascade), making registration all-or-nothing.
+     */
+    async recordRegistrationConsent(provisioning, userId, termsVersion, { ip, userAgent }) {
+        const now = new Date();
+        let outcome;
+        try {
+            outcome = await provisioning.createForRegistration({
+                userId,
+                termsVersion,
+                termsAcceptedAt: now,
+                ageAcceptedAt: now,
+                registrationIp: ip,
+                registrationUserAgent: userAgent,
+            });
+        }
+        catch (err) {
+            identityLogger.error({ err, userId }, 'registration consent write failed - rolling back user');
+            await this.drizzle.db.delete(user).where(eq(user.id, userId));
+            throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Registration is unavailable' });
+        }
+        if (!outcome.created) {
+            // A player row already existed, so this consent capture was discarded. Never
+            // silent: the acceptance evidence is a compliance record.
+            identityLogger.error({ userId, termsVersion }, 'registration consent not stored - player row already existed');
+        }
+        return { playerId: outcome.playerId ?? null, consentStored: outcome.created };
+    }
+    async usernameAvailable(username, reqHeaders) {
+        const { ip } = extractClientMeta(reqHeaders);
+        await assertRateLimit(this.limiter, `check-username:${ip ?? 'unknown'}`, USERNAME_AVAILABILITY_RATE_LIMIT);
+        return { available: !(await this.findUserIdByUsername(username)) };
     }
     /**
      * Credentials are verified FIRST; the RG login block is checked only AFTER
@@ -184,12 +585,11 @@ export class IdentityService {
      * read a stale count and slip past the lockout threshold.
      */
     async login(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
-        const ip = clientIp(headers);
-        const userAgent = headers.get('user-agent') || null;
         // better-auth lowercases emails on write, so the lockout lookup must match on the same form.
         const email = input.email.toLowerCase();
-        await assertRateLimit(this.limiter, `login:${email}`, LOGIN_RATE_LIMIT);
+        await assertRateLimit(this.limiter, makeLoginRateLimitKey(email), LOGIN_RATE_LIMIT);
         const configLockoutEnabled = this.options?.lockout?.enabled ?? true;
         // Read once for the lockout budget, the admin-bypass check, and the RG login gate
         // (indexed email lookup). Read unconditionally - the RG gate runs even when lockout
@@ -199,9 +599,13 @@ export class IdentityService {
             id: user.id,
             failedLoginAttempts: user.failedLoginAttempts,
             lockoutUntil: user.lockoutUntil,
+            lockoutCount: user.lockoutCount,
+            lastLockoutAt: user.lastLockoutAt,
+            lastFailedLoginAt: user.lastFailedLoginAt,
             role: user.role,
             rgBlocked: user.rgBlocked,
             rgBlockedUntil: user.rgBlockedUntil,
+            requireTwoFactorOnLogin: user.requireTwoFactorOnLogin,
         })
             .from(user)
             .where(eq(user.email, email))
@@ -210,8 +614,9 @@ export class IdentityService {
         const isAdmin = existingUser?.role === 'admin';
         const bypassForAdmins = this.options?.lockout?.bypassForAdmins ?? false;
         const lockoutEnabled = configLockoutEnabled && !(isAdmin && bypassForAdmins);
+        const nowMs = Date.now();
         if (lockoutEnabled && existingUser?.lockoutUntil) {
-            if (new Date(existingUser.lockoutUntil) > new Date()) {
+            if (new Date(existingUser.lockoutUntil) > new Date(nowMs)) {
                 throw createAccountLockedError(new Date(existingUser.lockoutUntil));
             }
             // Lock window elapsed: clear it so the next failure starts from a fresh budget
@@ -219,78 +624,193 @@ export class IdentityService {
             await this.clearLockout(existingUser.id);
             existingUser = { ...existingUser, failedLoginAttempts: 0, lockoutUntil: null };
         }
+        if (lockoutEnabled &&
+            existingUser &&
+            hasFailedLoginWindowExpired(existingUser.lastFailedLoginAt, existingUser.lastLockoutAt, nowMs)) {
+            await this.resetLockoutTier(existingUser.id);
+            existingUser = {
+                ...existingUser,
+                failedLoginAttempts: 0,
+                lockoutUntil: null,
+                lockoutCount: 0,
+                lastLockoutAt: null,
+                lastFailedLoginAt: null,
+            };
+        }
+        let fakeLoginShadow;
+        if (lockoutEnabled && !existingUser) {
+            fakeLoginShadow = await this.loginShadowGet(loginShadowKey(email));
+            if (fakeLoginShadow?.lastFailedLoginAt) {
+                const lastFailedLoginAt = new Date(fakeLoginShadow.lastFailedLoginAt);
+                if (hasFailedLoginWindowExpired(lastFailedLoginAt, null, nowMs)) {
+                    fakeLoginShadow = {
+                        failedAttempts: 0,
+                        lockoutUntil: null,
+                        lockoutCount: 0,
+                        lastLockoutAt: null,
+                        lastFailedLoginAt: null,
+                    };
+                }
+            }
+            if (fakeLoginShadow?.lockoutUntil) {
+                if (new Date(fakeLoginShadow.lockoutUntil) > new Date()) {
+                    throw createAccountLockedError(new Date(fakeLoginShadow.lockoutUntil));
+                }
+                fakeLoginShadow = { ...fakeLoginShadow, failedAttempts: 0, lockoutUntil: null };
+            }
+        }
+        // better-auth honours its trust-device cookie on its own and offers no way to revoke
+        // one. The revocable half of a trusted device is the row this module keeps, so a login
+        // presenting the cookie without a live row has to fall back to the full challenge.
+        let signInHeaders = headers;
+        if (existingUser && this.trustedDevices && hasTrustDeviceCookie(headers)) {
+            // "Require 2FA every login" outranks the cookie outright, so no lookup is needed -
+            // how well this browser is trusted stops mattering while the preference holds.
+            const trusted = !existingUser.requireTwoFactorOnLogin &&
+                (await this.trustedDevices.isTrusted(existingUser.id, userAgent));
+            if (!trusted) {
+                signInHeaders = withoutTrustDeviceCookie(headers);
+            }
+        }
         try {
             const authResponse = await this.auth.api.signInEmail({
                 body: { email, password: input.password, rememberMe: input.rememberMe },
-                headers,
+                headers: signInHeaders,
                 asResponse: true,
             });
             await ensureOk(authResponse);
-            // RG login block, applied only AFTER credentials verify so a pre-auth probe can't
-            // distinguish a restricted account from a wrong password. Kill the session
-            // better-auth just issued and never forward its cookie. Cooling-off auto-expires
-            // here once rgBlockedUntil elapses (no unblock job).
-            if (existingUser && isRgBlocked(existingUser)) {
-                await this.drizzle.db
-                    .update(session)
-                    .set({ expiresAt: new Date() })
-                    .where(eq(session.userId, existingUser.id));
-                this.events.emit('rg.exclusion.login_blocked', { userId: existingUser.id, ip, userAgent });
-                throw new ORPCError('FORBIDDEN', {
-                    message: 'Account access is currently restricted (responsible gambling).',
-                });
-            }
-            forwardCookies(authResponse, resHeaders);
+            // RG and backoffice blocks, applied only AFTER credentials verify so a pre-auth
+            // probe can't distinguish a restricted account from a wrong password. Resolves
+            // playerId once, so the eventual login success event can carry it too.
+            const playerId = existingUser
+                ? await this.assertAccountNotBlocked(existingUser, { ip, userAgent })
+                : null;
+            this.forwardCookies(authResponse, resHeaders);
             const body = (await authResponse.json());
             if (body.twoFactorRedirect || !body.user || !body.token) {
-                return { twoFactorRedirect: true };
+                // The challenge screen has to know whether to ask for an authenticator code or
+                // to push one, and there is no session yet to read the account's method from.
+                // Naming it here reveals nothing the challenge would not show anyway. Same for
+                // the trust window: an operator's configured length is not account-specific.
+                return {
+                    twoFactorRedirect: true,
+                    trustedDeviceDays: this.trustedDevices?.getTrustedDeviceDays() ?? 0,
+                    ...(existingUser
+                        ? { twoFactorMethod: await this.resolveTwoFactorMethod(existingUser.id) }
+                        : {}),
+                };
             }
             if (lockoutEnabled && existingUser) {
                 await this.clearLockout(existingUser.id);
             }
-            this.events.emit('identity.user.login', { userId: body.user.id, ip, userAgent });
+            await this.drizzle.db
+                .update(session)
+                .set({ ipAddress: ip, userAgent })
+                .where(eq(session.token, body.token));
+            this.events.emit('identity.user.login', {
+                userId: body.user.id,
+                playerId,
+                ip,
+                userAgent,
+            });
+            this.events.emit('identity.authentication.succeeded', {
+                userId: body.user.id,
+                playerId,
+                method: 'password',
+                ip,
+                userAgent,
+            });
+            await captureTimezone(this.playerProvisioning, body.user.id, input.timezone);
+            const sessionDurationSeconds = this.auth.options.session?.expiresIn ?? SESSION_DURATION_IN_SECONDS;
             const expiresAt = body.session?.expiresAt
                 ? toIso(body.session.expiresAt)
-                : new Date(Date.now() + SESSION_TTL_MS).toISOString();
+                : new Date(Date.now() + sessionDurationSeconds * 1000).toISOString();
             return {
                 user: toUser(body.user),
                 session: { token: body.token, expiresAt },
+                security: makeLoginSecurityState({
+                    failedLoginAttempts: 0,
+                    maxAttempts: this.options?.lockout?.maxAttempts ?? DEFAULT_MAX_LOGIN_ATTEMPTS,
+                    lockoutUntil: null,
+                }),
             };
         }
         catch (error) {
             // An RG block is not a credential failure - surface it as-is, without touching the
-            // lockout budget or emitting login.failed (the RG event was already emitted).
-            if (error instanceof ORPCError && error.code === 'FORBIDDEN') {
+            // lockout budget or emitting login.failed (the RG event was already emitted). Match on
+            // the RG_BLOCKED marker, not the bare FORBIDDEN code - ensureOk also maps a banned-user
+            // 403 (better-auth's admin plugin) to FORBIDDEN, and that path must still fall through
+            // to the generic branch below to emit login.failed.
+            if (error instanceof ORPCError &&
+                error.code === 'FORBIDDEN' &&
+                (hasErrorCode(error, 'RG_BLOCKED') || hasErrorCode(error, 'ACCOUNT_SUSPENDED'))) {
                 throw error;
             }
             // Only a genuine credential rejection counts toward lockout - a transient DB/network
             // error must never lock the account out.
-            const isCredentialFailure = error instanceof ORPCError && error.code === 'UNAUTHORIZED';
+            const isAccountLocked = error instanceof ORPCError &&
+                error.code === 'UNAUTHORIZED' &&
+                hasErrorCode(error, 'ACCOUNT_LOCKED');
+            const isCredentialFailure = error instanceof ORPCError && error.code === 'UNAUTHORIZED' && !isAccountLocked;
+            let attemptsRemaining;
             if (lockoutEnabled && existingUser && isCredentialFailure) {
                 const maxAttempts = this.options?.lockout?.maxAttempts ?? DEFAULT_MAX_LOGIN_ATTEMPTS;
-                const durationMs = this.options?.lockout?.durationMs ?? DEFAULT_LOCKOUT_DURATION_MS;
+                const fallbackDurationMs = this.options?.lockout?.durationMs ?? DEFAULT_LOCKOUT_DURATION_MS;
                 // Atomic increment: concurrent failures can't each read a stale count and slip past
                 // the threshold (the read-modify-write this replaces was bypassable under load).
                 const [row] = await this.drizzle.db
                     .update(user)
-                    .set({ failedLoginAttempts: sql `${user.failedLoginAttempts} + 1` })
+                    .set({
+                    failedLoginAttempts: sql `${user.failedLoginAttempts} + 1`,
+                    lastFailedLoginAt: new Date(),
+                })
                     .where(eq(user.id, existingUser.id))
                     .returning({ failedLoginAttempts: user.failedLoginAttempts });
                 const newAttempts = row?.failedLoginAttempts ?? existingUser.failedLoginAttempts + 1;
-                const { isLocking, lockoutUntil } = computeLockoutState({
+                attemptsRemaining = Math.max(maxAttempts - newAttempts, 0);
+                const { isLocking } = computeLockoutState({
                     attempts: newAttempts,
                     maxAttempts,
-                    durationMs,
+                    durationMs: fallbackDurationMs,
                     nowMs: Date.now(),
                 });
-                if (isLocking && lockoutUntil) {
-                    await this.drizzle.db
+                if (isLocking) {
+                    const nowMs = Date.now();
+                    // Escalate the lockout duration for repeat offenders inside the 24h window.
+                    const { tier, durationMs } = computeLockoutTier({
+                        lockoutCount: existingUser.lockoutCount ?? 0,
+                        lastFailedLoginAt: existingUser.lastFailedLoginAt ?? null,
+                        fallbackLastLockoutAt: existingUser.lastLockoutAt ?? null,
+                        nowMs,
+                        fallbackDurationMs,
+                    });
+                    const lockoutUntil = new Date(nowMs + durationMs);
+                    const [lockoutRow] = await this.drizzle.db
                         .update(user)
-                        .set({ lockoutUntil })
-                        .where(eq(user.id, existingUser.id));
+                        .set({ lockoutUntil, lockoutCount: tier, lastLockoutAt: new Date(nowMs) })
+                        // Only the first request that reaches the threshold creates the lockout.
+                        // Other concurrent failures must observe and return the winner's lockout
+                        // instead of overwriting its tier or emitting a duplicate event.
+                        .where(and(eq(user.id, existingUser.id), isNull(user.lockoutUntil)))
+                        .returning({ lockoutUntil: user.lockoutUntil });
+                    if (!lockoutRow) {
+                        const [current] = await this.drizzle.db
+                            .select({ lockoutUntil: user.lockoutUntil })
+                            .from(user)
+                            .where(eq(user.id, existingUser.id))
+                            .limit(1);
+                        if (current?.lockoutUntil) {
+                            throw createAccountLockedError(current.lockoutUntil);
+                        }
+                        throw new ORPCError('INTERNAL_SERVER_ERROR', {
+                            message: 'Unable to establish account lockout.',
+                        });
+                    }
+                    await this.limiter?.reset(makeLoginRateLimitKey(email));
                     this.events.emit('identity.user.lockout.triggered', {
                         userId: existingUser.id,
                         email,
+                        tier,
                         lockoutUntil: lockoutUntil.toISOString(),
                         ip,
                         userAgent,
@@ -298,8 +818,69 @@ export class IdentityService {
                     throw createAccountLockedError(lockoutUntil);
                 }
             }
+            else if (lockoutEnabled && !existingUser && isCredentialFailure) {
+                const maxAttempts = this.options?.lockout?.maxAttempts ?? DEFAULT_MAX_LOGIN_ATTEMPTS;
+                const fallbackDurationMs = this.options?.lockout?.durationMs ?? DEFAULT_LOCKOUT_DURATION_MS;
+                const newAttempts = (fakeLoginShadow?.failedAttempts ?? 0) + 1;
+                attemptsRemaining = Math.max(maxAttempts - newAttempts, 0);
+                const { isLocking } = computeLockoutState({
+                    attempts: newAttempts,
+                    maxAttempts,
+                    durationMs: fallbackDurationMs,
+                    nowMs: Date.now(),
+                });
+                if (isLocking) {
+                    const nowMs = Date.now();
+                    const { tier, durationMs } = computeLockoutTier({
+                        lockoutCount: fakeLoginShadow?.lockoutCount ?? 0,
+                        lastFailedLoginAt: fakeLoginShadow?.lastFailedLoginAt
+                            ? new Date(fakeLoginShadow.lastFailedLoginAt)
+                            : null,
+                        fallbackLastLockoutAt: fakeLoginShadow?.lastLockoutAt
+                            ? new Date(fakeLoginShadow.lastLockoutAt)
+                            : null,
+                        nowMs,
+                        fallbackDurationMs,
+                    });
+                    const lockoutUntil = new Date(nowMs + durationMs);
+                    await this.loginShadowSet(loginShadowKey(email), {
+                        failedAttempts: newAttempts,
+                        lockoutUntil: lockoutUntil.toISOString(),
+                        lockoutCount: tier,
+                        lastLockoutAt: new Date(nowMs).toISOString(),
+                        lastFailedLoginAt: new Date(nowMs).toISOString(),
+                    });
+                    await this.limiter?.reset(makeLoginRateLimitKey(email));
+                    throw createAccountLockedError(lockoutUntil);
+                }
+                await this.loginShadowSet(loginShadowKey(email), {
+                    failedAttempts: newAttempts,
+                    lockoutUntil: null,
+                    lockoutCount: fakeLoginShadow?.lockoutCount ?? 0,
+                    lastLockoutAt: fakeLoginShadow?.lastLockoutAt ?? null,
+                    lastFailedLoginAt: new Date().toISOString(),
+                });
+            }
             const reason = isCredentialFailure ? 'invalid_credentials' : 'error';
-            this.events.emit('identity.user.login.failed', { email, reason, ip, userAgent });
+            this.events.emit('identity.user.login.failed', {
+                email,
+                reason,
+                ip,
+                userAgent,
+                ...(attemptsRemaining !== undefined ? { attemptsRemaining } : {}),
+            });
+            if (isCredentialFailure && error instanceof ORPCError && attemptsRemaining !== undefined) {
+                const maxAttempts = this.options?.lockout?.maxAttempts ?? DEFAULT_MAX_LOGIN_ATTEMPTS;
+                const security = makeLoginSecurityState({
+                    failedLoginAttempts: attemptsRemaining === undefined ? 0 : maxAttempts - attemptsRemaining,
+                    maxAttempts,
+                    lockoutUntil: null,
+                });
+                throw new ORPCError('UNAUTHORIZED', {
+                    message: error.message,
+                    data: { ...error.data, ...security },
+                });
+            }
             throw error;
         }
     }
@@ -309,7 +890,95 @@ export class IdentityService {
             .set({ failedLoginAttempts: 0, lockoutUntil: null })
             .where(eq(user.id, userId));
     }
-    async unlockUser(userId, actorId) {
+    resetLockoutTier(userId) {
+        return this.drizzle.db
+            .update(user)
+            .set({
+            failedLoginAttempts: 0,
+            lockoutUntil: null,
+            lockoutCount: 0,
+            lastLockoutAt: null,
+            lastFailedLoginAt: null,
+        })
+            .where(eq(user.id, userId));
+    }
+    async loginShadowGet(key) {
+        if (!this.cache) {
+            return undefined;
+        }
+        try {
+            return await this.cache.get(key);
+        }
+        catch (err) {
+            loginShadowLogger.warn({ key, err }, 'login shadow cache read failed');
+            return undefined;
+        }
+    }
+    async loginShadowSet(key, value) {
+        if (!this.cache) {
+            return;
+        }
+        try {
+            await this.cache.set(key, value, { ttlMs: FAKE_LOGIN_SHADOW_TTL_MS });
+        }
+        catch (err) {
+            loginShadowLogger.warn({ key, err }, 'login shadow cache write failed');
+        }
+    }
+    adminPasswordResetMarkerKey(email) {
+        return `admin-password-reset:${email.toLowerCase()}`;
+    }
+    async isAdminPasswordReset(email) {
+        if (!this.cache) {
+            return false;
+        }
+        const key = this.adminPasswordResetMarkerKey(email);
+        try {
+            const isAdmin = (await this.cache.get(key)) === true;
+            if (isAdmin) {
+                await this.cache.delete(key);
+            }
+            return isAdmin;
+        }
+        catch (err) {
+            identityLogger.warn({ err }, 'admin password reset marker cache read failed');
+            return false;
+        }
+    }
+    async adminRequestPasswordReset(userId, actorId, meta) {
+        const existingUser = findOneOrThrow(await this.drizzle.db
+            .select({ id: user.id, email: user.email })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1), new UserNotFoundError(userId));
+        const email = existingUser.email.toLowerCase();
+        try {
+            await this.cache?.set(this.adminPasswordResetMarkerKey(email), true, { ttlMs: 120_000 });
+        }
+        catch (err) {
+            identityLogger.warn({ email, err }, 'admin password reset marker cache write failed');
+        }
+        // Mirrors requestPasswordReset - the send failure is swallowed the same way.
+        try {
+            await this.api.requestPasswordResetEmailOTP({
+                body: { email },
+                headers: new Headers(),
+                asResponse: true,
+            });
+        }
+        catch {
+            // intentionally ignored
+        }
+        this.events.emit('identity.password.admin_reset_requested', {
+            userId,
+            email,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return SUCCESS;
+    }
+    async unlockUser(userId, actorId, meta) {
         const existingUser = findOneOrThrow(await this.drizzle.db
             .select({
             id: user.id,
@@ -321,6 +990,7 @@ export class IdentityService {
             .where(eq(user.id, userId))
             .limit(1), new UserNotFoundError(userId));
         await this.clearLockout(userId);
+        await this.limiter?.reset(makeLoginRateLimitKey(existingUser.email));
         this.events.emit('identity.user.unlocked', {
             userId,
             email: existingUser.email,
@@ -329,18 +999,26 @@ export class IdentityService {
             previousLockoutUntil: existingUser.lockoutUntil
                 ? existingUser.lockoutUntil.toISOString()
                 : null,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
         });
         return SUCCESS;
     }
     async logout(reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
         // Resolve the user BEFORE signOut so the audit log can attribute the logout.
         const session = await this.auth.api.getSession({ headers });
         const userId = session?.user?.id;
         const authResponse = await this.auth.api.signOut({ headers, asResponse: true });
-        forwardCookies(authResponse, resHeaders);
+        this.forwardCookies(authResponse, resHeaders);
         if (userId) {
-            this.events.emit('identity.user.logout', { userId });
+            this.events.emit('identity.user.logout', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                ip,
+                userAgent,
+            });
         }
         return SUCCESS;
     }
@@ -352,61 +1030,460 @@ export class IdentityService {
         }
         return toUser(session.user);
     }
+    /**
+     * Starts enrolment. All three methods share the one secret better-auth mints here;
+     * `method` only decides how the code that activates it arrives, and is written
+     * before the send so the delivery hook knows where to route. better-auth flips
+     * `twoFactorEnabled` only once the first code clears, so abandoning a first
+     * enrolment leaves the account unprotected exactly as it was.
+     *
+     * A transport failure on the first send throws (see `sendOtpForCurrentMethod`)
+     * after `two_factor_method` is already written, but that write is inert on its
+     * own: `twoFactorStatus` reports it only once `enabled` is true, and the CONFLICT
+     * guard below only fires once it is. The caller recovers by retrying either
+     * `sendTwoFactorOtp` (resend) or this route again - both read the method that was
+     * already persisted, so neither loses the player's choice.
+     */
     async enableTwoFactor(input, reqHeaders, resHeaders) {
         const headers = nodeHeadersToHeaders(reqHeaders);
         const userId = await this.currentUserId(headers);
         await assertRateLimit(this.limiter, `enable2fa:${userId ?? 'anonymous'}`, TWO_FACTOR_PASSWORD_RATE_LIMIT);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
+        }
+        await this.assertMethodAvailable(userId, input.method);
+        // There is no switch-in-place: a player changes method by disabling and enrolling
+        // again. better-auth's enable leg deletes and recreates the `twoFactor` row with a
+        // fresh secret and fresh backup codes, and marks it verified straight away when one
+        // was already verified - so re-running it on a live account destroys the working
+        // authenticator the moment the call lands, and abandoning the step strands the
+        // player on a secret they never scanned with `two_factor_enabled` still true.
+        if (await this.isTwoFactorEnabled(userId)) {
+            throw new ORPCError('CONFLICT', {
+                message: 'Two-factor authentication is already enabled. Disable it first to change method.',
+            });
+        }
         const res = await this.api.enableTwoFactor({
             body: { password: input.password },
             headers,
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         const body = (await res.json());
-        return { totpUri: body.totpURI, backupCodes: body.backupCodes };
+        await this.setTwoFactorMethod(userId, input.method);
+        if (input.method === 'app') {
+            return { totpUri: body.totpURI, backupCodes: body.backupCodes };
+        }
+        // The first code has to reach the player before they can activate the method, so
+        // the send belongs to enrolment rather than a separate call the client must know
+        // to make. "Resend code" then replays it through sendTwoFactorOtp.
+        const masked = await this.sendOtpForCurrentMethod(userId, headers, resHeaders);
+        return { backupCodes: body.backupCodes, maskedDestination: masked };
+    }
+    /**
+     * Re-sends the one-time code for an account on the `email` or `sms` method - the
+     * "Resend code" action during enrolment, and the send leg of a login challenge.
+     * Resolves its subject from a live session first and the pending-challenge cookie
+     * second, because at login there is no session yet.
+     */
+    async sendTwoFactorOtp(reqHeaders, resHeaders) {
+        const headers = nodeHeadersToHeaders(reqHeaders);
+        const pendingCookie = twoFactorPendingCookieValue(headers);
+        const userId = (await this.currentUserId(headers)) ??
+            (await this.twoFactorLockout?.resolvePendingUserId(pendingCookie));
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
+        }
+        await assertRateLimit(this.limiter, `send2faOtp:${userId}`, SEND_2FA_OTP_RATE_LIMIT);
+        // An account inside a lockout window cannot spend a code, so minting one only
+        // hands out fresh guesses - and, on `sms`, bills the operator for them.
+        await this.twoFactorLockout?.assertNotLocked(userId);
+        return { maskedDestination: await this.sendOtpForCurrentMethod(userId, headers, resHeaders) };
+    }
+    /** Whether a second factor is active, which method it uses, and where a code can go. */
+    async twoFactorStatus(reqHeaders) {
+        const headers = nodeHeadersToHeaders(reqHeaders);
+        const userId = await this.currentUserId(headers);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
+        }
+        const [row] = await this.drizzle.db
+            .select({
+            email: user.email,
+            phoneNumber: user.phoneNumber,
+            phoneVerified: user.phoneVerified,
+            twoFactorEnabled: user.twoFactorEnabled,
+            twoFactorMethod: user.twoFactorMethod,
+        })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        if (!row) {
+            throw new UserNotFoundError(userId);
+        }
+        const enabled = row.twoFactorEnabled ?? false;
+        return {
+            enabled,
+            // The column outlives an abandoned enrolment, so an account that never cleared
+            // its first code must still read as having no active method.
+            method: enabled ? (row.twoFactorMethod ?? null) : null,
+            maskedEmail: maskEmail(row.email),
+            maskedPhone: row.phoneVerified && row.phoneNumber ? maskPhone(row.phoneNumber) : null,
+        };
+    }
+    /**
+     * Rejects a method the account cannot actually receive a code on. Enrolling into
+     * `sms` without a verified phone would mint a secret the player can never clear,
+     * locking them out of their own account at the next login.
+     */
+    async assertMethodAvailable(userId, method) {
+        if (method === 'app') {
+            return;
+        }
+        const [row] = await this.drizzle.db
+            .select({
+            emailVerified: user.emailVerified,
+            phoneNumber: user.phoneNumber,
+            phoneVerified: user.phoneVerified,
+        })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        // A code can only guard the account if the address it goes to is one the account
+        // has proven it holds. `registration.requireEmailVerification` is off by default,
+        // so an unverified or mistyped address would otherwise enrol and lock the player
+        // out at the next login - the same failure the phone check already prevents.
+        if (method === 'email' && !row?.emailVerified) {
+            throw new ORPCError('BAD_REQUEST', {
+                message: 'Verify your email address before using email for two-factor authentication',
+            });
+        }
+        if (method === 'sms' && (!row?.phoneNumber || !row.phoneVerified)) {
+            throw new ORPCError('BAD_REQUEST', {
+                message: 'Add and verify a phone number before using SMS for two-factor authentication',
+            });
+        }
+    }
+    /**
+     * The account's delivery method, defaulting to `app`: an enrolment that predates the
+     * column reads as null, and every one of those was an authenticator.
+     */
+    async resolveTwoFactorMethod(userId) {
+        const [row] = await this.drizzle.db
+            .select({ twoFactorMethod: user.twoFactorMethod })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        return row?.twoFactorMethod ?? 'app';
+    }
+    async isTwoFactorEnabled(userId) {
+        const [row] = await this.drizzle.db
+            .select({ twoFactorEnabled: user.twoFactorEnabled })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        return row?.twoFactorEnabled ?? false;
+    }
+    async setTwoFactorMethod(userId, method) {
+        await this.drizzle.db.update(user).set({ twoFactorMethod: method }).where(eq(user.id, userId));
+    }
+    verifyChallengeCode(method, body, headers) {
+        return verifyChallengeCode(this.api, method, body, headers);
+    }
+    async sendOtpForCurrentMethod(userId, headers, resHeaders) {
+        const destination = await this.twoFactorDelivery.describeDestination(userId);
+        if (!destination) {
+            throw new ORPCError('BAD_REQUEST', {
+                message: 'This account does not receive two-factor codes by email or SMS',
+            });
+        }
+        const res = await this.api.sendTwoFactorOTP({ body: {}, headers, asResponse: true });
+        await ensureOk(res);
+        // A 200 here means the code was minted, not that it left the building: the send
+        // hook is wrapped in `.catch(logger.error)` upstream. Telling the player a code is
+        // on its way when the transport just failed strands them on a screen waiting for
+        // something that is never coming.
+        const failure = this.twoFactorDelivery.takeFailure(userId);
+        if (failure) {
+            throw new ORPCError('SERVICE_UNAVAILABLE', {
+                message: 'Could not send your verification code. Please try again.',
+                cause: failure,
+            });
+        }
+        this.forwardCookies(res, resHeaders);
+        return destination.masked;
+    }
+    /**
+     * Whether the account insists on a second factor every login. Read off the row rather
+     * than passed in: mid-challenge there is no session yet, so the only handle on the
+     * account is the id the pending cookie resolved to.
+     */
+    async requiresTwoFactorEveryLogin(userId) {
+        if (!userId) {
+            return false;
+        }
+        const [row] = await this.drizzle.db
+            .select({ requireTwoFactorOnLogin: user.requireTwoFactorOnLogin })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        return row?.requireTwoFactorOnLogin ?? false;
     }
     async verifyTwoFactor(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
-        const twoFactorKey = (await this.currentUserId(headers)) ?? twoFactorPendingCookieValue(headers) ?? 'anonymous';
+        const pendingCookie = twoFactorPendingCookieValue(headers);
+        const sessionUserId = await this.currentUserId(headers);
+        const twoFactorKey = sessionUserId ?? pendingCookie ?? 'anonymous';
         await assertRateLimit(this.limiter, `verify2fa:${twoFactorKey}`, VERIFY_2FA_RATE_LIMIT);
-        const res = await this.api.verifyTOTP({
-            body: { code: input.code },
-            headers,
-            asResponse: true,
-        });
+        const challengedUserId = sessionUserId ?? (await this.twoFactorLockout?.resolvePendingUserId(pendingCookie));
+        if (challengedUserId) {
+            await this.twoFactorLockout?.assertNotLocked(challengedUserId);
+        }
+        // A backup code is a single-use recovery credential, not a second factor to bind a
+        // browser to: it clears the challenge but never buys the trust window. A pushed
+        // `otp` is a real factor and does, the same as a live authenticator code.
+        const trustDevice = input.trustDevice &&
+            input.method !== 'backup_code' &&
+            this.trustedDevices !== undefined &&
+            !(await this.requiresTwoFactorEveryLogin(challengedUserId));
+        const body = { code: input.code, trustDevice };
+        const res = await this.verifyChallengeCode(input.method, body, headers);
+        if (!res.ok && challengedUserId) {
+            await this.twoFactorLockout?.recordFailure(challengedUserId, { ip, userAgent });
+        }
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
-        const userId = await this.currentUserId(headers);
+        if (challengedUserId) {
+            await this.twoFactorLockout?.reset(challengedUserId);
+        }
+        this.forwardCookies(res, resHeaders);
+        // better-auth rotates the session on a successful challenge, so the request cookie is
+        // already dead here - the actor is the identity resolved before the call.
+        const userId = challengedUserId ?? (await this.currentUserId(headers));
+        // Ground truth for the caller: `trustDevice` already reflects backup-code and
+        // require-2fa-every-login refusals, but only actually buys the cookie below, and
+        // only when `userId` resolved. The client asked to trust this device and deserves to
+        // know whether that request was honoured rather than silently dropped.
+        let trustGranted = false;
         if (userId) {
-            this.events.emit('identity.2fa.enabled', { userId });
+            const playerId = await this.identityReader.getPlayerIdByUserIdSafe(userId);
+            // A challenge answered from a live session is the enrolment step: better-auth only
+            // flips twoFactorEnabled once the first code clears. Every later verification is a
+            // sign-in, which carries the pending cookie instead and must not re-announce setup.
+            if (sessionUserId) {
+                this.events.emit('identity.2fa.enabled', {
+                    userId,
+                    playerId,
+                    method: input.method,
+                    ip,
+                    userAgent,
+                });
+            }
+            this.events.emit('identity.2fa.verified', {
+                userId,
+                playerId,
+                method: input.method,
+                trustedDevice: trustDevice,
+                ip,
+                userAgent,
+            });
+            if (!sessionUserId) {
+                this.events.emit('identity.authentication.succeeded', {
+                    userId,
+                    playerId,
+                    method: input.method,
+                    ip,
+                    userAgent,
+                });
+            }
+            if (trustDevice) {
+                await this.trustedDevices?.trust(userId, { ip, userAgent });
+                trustGranted = true;
+            }
+            await captureTimezone(this.playerProvisioning, userId, input.timezone);
+        }
+        return { ...SUCCESS, trustGranted };
+    }
+    /**
+     * Grants this browser its trust window without a sign-out. better-auth issues the
+     * trust cookie only on the sign-in leg of a challenge, so the grant has to replay
+     * that leg: the account proves its password and a fresh second factor, and the
+     * cookies better-auth returns are the ones the browser keeps.
+     */
+    async trustCurrentDevice(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        const headers = nodeHeadersToHeaders(reqHeaders);
+        const userId = await this.currentUserId(headers);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
         }
+        await assertRateLimit(this.limiter, `trustDevice:${userId}`, TWO_FACTOR_PASSWORD_RATE_LIMIT);
+        // Granting trust the login path is contractually going to ignore would leave the
+        // player with a device listed as trusted that still gets challenged every time.
+        if (await this.requiresTwoFactorEveryLogin(userId)) {
+            throw new ORPCError('UNPROCESSABLE_CONTENT', {
+                message: 'Turn off two-factor on every login before trusting this device.',
+            });
+        }
+        const [account] = await this.drizzle.db
+            .select({ email: user.email })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        if (!account) {
+            throw new UserNotFoundError(userId);
+        }
+        const signIn = await this.auth.api.signInEmail({
+            body: { email: account.email, password: input.password },
+            headers: withoutTrustDeviceCookie(headers),
+            asResponse: true,
+        });
+        await ensureOk(signIn);
+        const signInBody = (await signIn.json());
+        if (signInBody.twoFactorRedirect !== true) {
+            throw new ORPCError('BAD_REQUEST', {
+                message: 'Two-factor authentication is not enabled for this account',
+            });
+        }
+        // Only the cookies the challenge just issued: leaving the live session cookie in
+        // place makes better-auth treat the call as a settings change and skip the trust.
+        const challengeHeaders = new Headers(headers);
+        challengeHeaders.set('cookie', requestCookieHeader(signIn));
+        await this.twoFactorLockout?.assertNotLocked(userId);
+        // Authenticator accounts only. This route replays a fresh sign-in leg, and
+        // better-auth keys a pushed code by the pending-challenge cookie that leg mints -
+        // so an `email`/`sms` account has no code that can answer this challenge, and
+        // letting the call through would only spend its lockout budget on a credential it
+        // is impossible to present. Refusing says so instead of failing as a wrong code.
+        const challengeMethod = await resolveChallengeMethod(this.drizzle, userId);
+        if (challengeMethod !== 'totp') {
+            throw new ORPCError('CONFLICT', {
+                message: 'Trusting this device requires an authenticator app.',
+            });
+        }
+        const verified = await this.verifyChallengeCode(challengeMethod, { code: input.code, trustDevice: true }, challengeHeaders);
+        if (!verified.ok) {
+            await this.twoFactorLockout?.recordFailure(userId, { ip, userAgent });
+        }
+        await ensureOk(verified);
+        await this.twoFactorLockout?.reset(userId);
+        this.forwardCookies(verified, resHeaders);
+        await this.trustedDevices?.trust(userId, { ip, userAgent });
+        const playerId = await this.identityReader.getPlayerIdByUserIdSafe(userId);
+        this.events.emit('identity.2fa.verified', {
+            userId,
+            playerId,
+            method: challengeMethod,
+            trustedDevice: true,
+            ip,
+            userAgent,
+        });
+        // The challenge leg above ran without a session cookie, so better-auth minted a new
+        // session and this response carries it. That is a new authenticated session like any
+        // other, and the security alert has to see it.
+        this.events.emit('identity.authentication.succeeded', {
+            userId,
+            playerId,
+            method: 'totp',
+            ip,
+            userAgent,
+        });
         return SUCCESS;
     }
+    /**
+     * A step-up gate for the self-service routes that change standing 2FA state: the
+     * caller has to clear a live authenticator code, not just the account password.
+     * Routed through TwoFactorLockoutService so a hijacked session plus a reused
+     * password cannot grind the second factor here the way the password-only paths let it.
+     */
+    async assertFreshSecondFactor(userId, headers, meta, code) {
+        await this.twoFactorLockout?.assertNotLocked(userId);
+        const res = await this.verifyChallengeCode(await resolveChallengeMethod(this.drizzle, userId), { code, trustDevice: false }, headers);
+        if (!res.ok) {
+            await this.twoFactorLockout?.recordFailure(userId, meta);
+        }
+        await ensureOk(res, { genericMessage: 'Invalid authenticator code' });
+        await this.twoFactorLockout?.reset(userId);
+    }
+    async regenerateBackupCodes(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        const headers = nodeHeadersToHeaders(reqHeaders);
+        const userId = await this.currentUserId(headers);
+        await assertRateLimit(this.limiter, `backupCodes:${userId ?? 'anonymous'}`, TWO_FACTOR_PASSWORD_RATE_LIMIT);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
+        }
+        await this.assertFreshSecondFactor(userId, headers, { ip, userAgent }, input.code);
+        const res = await this.api.generateBackupCodes({
+            body: { password: input.password },
+            headers,
+            asResponse: true,
+        });
+        await ensureOk(res);
+        this.forwardCookies(res, resHeaders);
+        const body = (await res.json());
+        // The old set is void the moment a new one is minted, so any device still trusted
+        // off the old recovery flow re-verifies on its next login.
+        await this.trustedDevices?.revokeAllForUser(userId, userId);
+        this.events.emit('identity.2fa.backup_codes_regenerated', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            ip,
+            userAgent,
+        });
+        return { backupCodes: body.backupCodes };
+    }
     async disableTwoFactor(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
         const userId = await this.currentUserId(headers);
         await assertRateLimit(this.limiter, `disable2fa:${userId ?? 'anonymous'}`, TWO_FACTOR_PASSWORD_RATE_LIMIT);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
+        }
+        await this.assertFreshSecondFactor(userId, headers, { ip, userAgent }, input.code);
+        // Read before the teardown clears it, so the audit trail records which method the
+        // account was actually protected by rather than a blank.
+        const disabledMethod = await resolveChallengeMethod(this.drizzle, userId);
         const res = await this.api.disableTwoFactor({
             body: { password: input.password },
             headers,
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
-        if (userId) {
-            this.events.emit('identity.2fa.disabled', { userId });
-        }
+        this.forwardCookies(res, resHeaders);
+        await this.setTwoFactorMethod(userId, null);
+        // Dropping the second factor takes every standing bypass with it, the same teardown
+        // a Super Admin reset performs - a browser must not keep the access 2FA was guarding.
+        await this.trustedDevices?.revokeAllForUser(userId, userId);
+        await this.sessions?.revokeAllSessions(userId, userId, { ip, userAgent });
+        // Must clear alongside the method: leaving it set strands the account with
+        // `twoFactorEnabled: false, requireTwoFactorOnLogin: true` - a state `trustCurrentDevice`
+        // reads as "still enforced" while `setRequireTwoFactorOnLogin` itself refuses to turn it
+        // off without `twoFactorEnabled`, so nothing in the product could ever escape it again.
+        await this.drizzle.db
+            .update(user)
+            .set({ requireTwoFactorOnLogin: false })
+            .where(eq(user.id, userId));
+        this.events.emit('identity.2fa.disabled', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            method: disabledMethod,
+            ip,
+            userAgent,
+        });
         return SUCCESS;
     }
     async requestPasswordReset(input) {
-        await assertRateLimit(this.limiter, `pwreset-req:${input.email.toLowerCase()}`, PASSWORD_RESET_REQUEST_RATE_LIMIT);
-        // Always returns success - never reveal whether the email exists. The reset
-        // email (if any) is delivered through the sendEmail hook -> notifications.
-        // Any underlying error is swallowed for the same anti-enumeration reason.
+        const email = input.email.toLowerCase();
+        await assertRateLimit(this.limiter, makeRateLimitKey(RATE_LIMIT_KEYS.PASSWORD_RESET_REQUEST, email), PASSWORD_RESET_REQUEST_RATE_LIMIT);
+        // Always returns success - never reveal whether the email exists. The reset OTP
+        // (if any) is enqueued through better-auth's emailOTP hook -> MAIL_DISPATCH. Any
+        // underlying error is swallowed for the same anti-enumeration reason.
         try {
-            await this.api.requestPasswordReset({
-                body: { email: input.email, redirectTo: '/reset-password' },
+            await this.api.requestPasswordResetEmailOTP({
+                body: { email },
                 headers: new Headers(),
                 asResponse: true,
             });
@@ -416,77 +1493,504 @@ export class IdentityService {
         }
         return SUCCESS;
     }
+    async verifyPasswordResetOtp(input) {
+        const email = input.email.toLowerCase();
+        await assertRateLimit(this.limiter, makeRateLimitKey(RATE_LIMIT_KEYS.PASSWORD_RESET_VERIFY, email), PASSWORD_RESET_VERIFY_RATE_LIMIT);
+        const res = await this.api.checkVerificationOTP({
+            body: { email, type: 'forget-password', otp: input.otp },
+            headers: new Headers(),
+            asResponse: true,
+        });
+        await ensureOk(res, { genericMessage: 'Invalid or expired verification code' });
+        return SUCCESS;
+    }
     async resetPassword(input) {
-        // Key on the token - the only identifier the input carries - to bound retries
-        // against a single reset token.
-        await assertRateLimit(this.limiter, `pwreset:${input.token}`, PASSWORD_RESET_RATE_LIMIT);
-        const res = await this.api.resetPassword({
-            body: { newPassword: input.newPassword, token: input.token },
+        const email = input.email.toLowerCase();
+        await assertRateLimit(this.limiter, makeRateLimitKey(RATE_LIMIT_KEYS.PASSWORD_RESET, email), PASSWORD_RESET_RATE_LIMIT);
+        const res = await this.api.resetPasswordEmailOTP({
+            body: { email, otp: input.otp, password: input.newPassword },
             headers: new Headers(),
             asResponse: true,
         });
-        await ensureOk(res);
-        const body = (await res.json().catch(() => ({})));
-        if (body.user?.id) {
-            this.events.emit('identity.password.reset', { userId: body.user.id });
-            // Password reset clears any lockout - the user has proven identity via email/phone.
-            await this.clearLockout(body.user.id);
-        }
+        await ensureOk(res, { genericMessage: 'Invalid or expired verification code' });
+        // better-auth's resetPasswordEmailOTP internally invokes the onPasswordReset hook
+        // (wired in the constructor above), which emits `identity.password.reset` and
+        // clears the lockout - do not duplicate that here (was double-emitting/double-
+        // clearing on every real reset).
         return SUCCESS;
     }
-    async changePassword(input, reqHeaders, resHeaders) {
+    async changePassword(input, reqHeaders, resHeaders, caller) {
         const headers = nodeHeadersToHeaders(reqHeaders);
-        const userId = await this.currentUserId(headers);
-        await assertRateLimit(this.limiter, `change-password:${userId ?? 'anonymous'}`, CHANGE_PASSWORD_RATE_LIMIT);
+        const { userId, sessionId } = caller;
+        await assertRateLimit(this.limiter, `change-password:${userId}`, CHANGE_PASSWORD_RATE_LIMIT);
         const res = await this.api.changePassword({
-            body: { currentPassword: input.currentPassword, newPassword: input.newPassword },
+            // revokeOtherSessions: better-auth deletes every session for this user and
+            // mints a fresh one for the caller; forwardCookies below ships that cookie.
+            body: {
+                currentPassword: input.currentPassword,
+                newPassword: input.newPassword,
+                revokeOtherSessions: true,
+            },
             headers,
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
+        // Captured once the rotation is known committed - the deferred sweep below deletes
+        // any session row created at or before this instant (i.e. one a concurrent
+        // old-password sign-in raced in), sparing anything created afterwards.
+        const sweepDeadline = new Date();
+        // The token of the session better-auth just minted for the caller. `ensureOk` only
+        // reads the body on failure, so this read is safe here.
+        // Library boundary: `Response.json()` resolves to `any`, and better-auth publishes no
+        // response type for this route, so its shape is asserted once here.
+        const rotatedToken = (await res.json().catch(() => ({}))).token ?? null;
+        // better-auth's response only carries the token, not the row id - look the row up
+        // once here and reuse its id both to clamp the dontRememberMe TTL below and to
+        // spare this (legitimate) session from the sweep's own revoke push further down.
+        const rotated = rotatedToken
+            ? (await this.drizzle.db
+                .select({ id: session.id })
+                .from(session)
+                .where(eq(session.token, rotatedToken))
+                .limit(1))[0]
+            : undefined;
+        // `revokeOtherSessions` makes better-auth mint the replacement session via
+        // `createSession(userId)` with no `dontRememberMe` argument, so a caller who signed
+        // in with `rememberMe: false` silently gets a full-TTL row. better-auth's own
+        // `setSessionCookie` still honours the `dont_remember` cookie for the cookie maxAge,
+        // but not the DB row - clamp it back to the non-remembered TTL to match.
+        if (rotated && hasDontRememberCookie(headers)) {
+            await this.drizzle.db
+                .update(session)
+                .set({ expiresAt: new Date(Date.now() + DONT_REMEMBER_SESSION_TTL_MS) })
+                .where(eq(session.id, rotated.id));
+        }
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        // Independent of each other and of `rotated` - one round trip instead of two on a
+        // user-facing endpoint. (The TTL clamp above does depend on `rotated`, so it stays
+        // sequential.)
+        const [, playerId] = await Promise.all([
+            this.drizzle.db.update(user).set({ passwordMeetsPolicy: true }).where(eq(user.id, userId)),
+            this.identityReader.getPlayerIdByUserIdSafe(userId),
+        ]);
+        // Dedicated, non-sensitive record that the login credential itself changed -
+        // the audit mapper keys the action off the topic, so a plain
+        // `identity.sessions.revoked_all` alone would read as "revoked all sessions",
+        // not "changed password". Every state-changing credential action needs its own
+        // accurately named audit record.
+        this.events.emit('identity.password.changed', {
+            userId,
+            playerId,
+            ip: ip ?? null,
+            userAgent: userAgent ?? null,
+        });
+        // Same event the admin "revoke all sessions" path emits, so the streamSession
+        // SSE handler pushes { type: 'revoked' } to this user's OTHER tabs.
+        // exceptSessionId is the caller's PRE-rotation session id - it's the id the
+        // caller's already-open streamSession connection captured at stream-open, and the
+        // only value its SSE compare can ever match, so this is what spares the
+        // initiating tab.
+        this.events.emit('identity.sessions.revoked_all', {
+            userId,
+            playerId,
+            actorId: userId,
+            ip: ip ?? null,
+            userAgent: userAgent ?? null,
+            exceptSessionId: sessionId,
+        });
+        // better-auth rotates the password hash and deletes sessions in separate,
+        // untransacted statements; a sign-in that verified the OLD password just before
+        // the rotation can still insert its session row right after. Re-sweep shortly
+        // after to delete it, sparing the caller's fresh session by token. Skipped when
+        // the rotated token is unknown - without it the sweep cannot tell the caller's
+        // own new session apart. Residual exposure: RACED_SESSION_SWEEP_DELAY_MS.
+        if (rotatedToken) {
+            const timer = setTimeout(() => {
+                void sweepRacedSessionsAfterPasswordChange(this.drizzle.db, {
+                    userId,
+                    sparedToken: rotatedToken,
+                    deadline: sweepDeadline,
+                })
+                    .then((deletedIds) => {
+                    // A session the sweep just force-deleted got no push and no audit record
+                    // otherwise: it raced in after the primary revoked_all above already
+                    // fired, so this is the only notice it gets of either.
+                    if (deletedIds.length === 0) {
+                        return;
+                    }
+                    this.events.emit('identity.sessions.revoked_all', {
+                        userId,
+                        playerId,
+                        actorId: userId,
+                        ip: ip ?? null,
+                        userAgent: userAgent ?? null,
+                        // The caller's PRE-rotation session id, same as the primary emit above -
+                        // it's what the initiating tab's already-open streamSession connection
+                        // captured at stream-open, and the only value its SSE compare can match.
+                        // `rotated.id` (the NEW row) can never match that, so using it here would
+                        // force-revoke the legitimate acting tab the moment the sweep actually
+                        // deletes a raced session.
+                        exceptSessionId: sessionId,
+                    });
+                })
+                    .catch((err) => {
+                    identityLogger.warn({ err, userId }, 'post-password-change session sweep failed');
+                });
+            }, RACED_SESSION_SWEEP_DELAY_MS);
+            timer.unref?.();
+        }
         return SUCCESS;
     }
-    async sendEmailVerification(reqHeaders) {
-        const headers = nodeHeadersToHeaders(reqHeaders);
-        const session = await this.auth.api.getSession({ headers });
-        const email = session?.user?.email;
-        if (email) {
-            await assertRateLimit(this.limiter, `email-verify:${email.toLowerCase()}`, EMAIL_VERIFICATION_RATE_LIMIT);
-            await this.api.sendVerificationEmail({ body: { email }, headers, asResponse: true });
+    async getSecurityControls(reqHeaders) {
+        const userId = await this.currentUserId(nodeHeadersToHeaders(reqHeaders));
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in.' });
+        }
+        return this.securityControlsFor(userId);
+    }
+    /**
+     * Resolves the caller of a security-preference setter and refuses anyone who is not a
+     * player. These setters reject before any shared guard runs, so a denial still owes the
+     * audit log the same signal AdminGuard emits (docs/standards/audit.md) - `resource`
+     * names which preference was attempted.
+     */
+    async assertPlayerPreferenceCaller(reqHeaders, resource) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        const userId = await this.currentUserId(nodeHeadersToHeaders(reqHeaders));
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in.' });
+        }
+        const [caller] = await this.drizzle.db
+            .select({ role: user.role })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        if (caller?.role !== 'player') {
+            this.events.emit('identity.user.unauthorized_access', {
+                userId,
+                playerId: null,
+                resource,
+                action: 'set',
+                ...(caller?.role ? { role: caller.role } : {}),
+                ip,
+                userAgent,
+            });
+            throw new ORPCError('FORBIDDEN', {
+                message: 'Only players can set this preference.',
+            });
+        }
+        return { userId, ip, userAgent };
+    }
+    async setLoginWithdrawalAlerts(input, reqHeaders) {
+        const { userId, ip, userAgent } = await this.assertPlayerPreferenceCaller(reqHeaders, 'identity.security.login_withdrawal_alerts');
+        const before = await this.securityControlsFor(userId);
+        if (input.enabled && !before.emailVerified) {
+            throw new ORPCError('UNPROCESSABLE_CONTENT', {
+                message: 'Verify your email before enabling security alerts.',
+            });
+        }
+        if (before.loginWithdrawalAlertsEnabled === input.enabled) {
+            return before;
+        }
+        await this.drizzle.db
+            .update(user)
+            .set({ loginWithdrawalAlertsEnabled: input.enabled })
+            .where(eq(user.id, userId));
+        this.events.emit('identity.security.login_withdrawal_alerts.updated', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            previousEnabled: before.loginWithdrawalAlertsEnabled,
+            enabled: input.enabled,
+            ip,
+            userAgent,
+        });
+        return { ...before, loginWithdrawalAlertsEnabled: input.enabled };
+    }
+    async setAutoLogoutDuration(input, reqHeaders) {
+        const { userId, ip, userAgent } = await this.assertPlayerPreferenceCaller(reqHeaders, 'identity.security.auto_logout');
+        const before = await this.securityControlsFor(userId);
+        if (before.autoLogoutDuration === input.duration) {
+            return before;
+        }
+        await this.drizzle.db
+            .update(user)
+            .set({ autoLogoutDuration: input.duration })
+            .where(eq(user.id, userId));
+        this.events.emit('identity.security.auto_logout.updated', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            previousDuration: before.autoLogoutDuration,
+            duration: input.duration,
+            ip,
+            userAgent,
+        });
+        return { ...before, autoLogoutDuration: input.duration };
+    }
+    /**
+     * Turning this on also tears down the devices already trusted: stripping the trust
+     * cookie at login is enough to force the challenge, but leaving live rows behind would
+     * show a player devices that no longer buy anything, and hand them straight back the
+     * moment the toggle goes off again.
+     */
+    async setRequireTwoFactorOnLogin(input, reqHeaders) {
+        const { userId, ip, userAgent } = await this.assertPlayerPreferenceCaller(reqHeaders, 'identity.security.require_two_factor');
+        const before = await this.securityControlsFor(userId);
+        if (input.enabled && !before.twoFactorEnabled) {
+            throw new ORPCError('UNPROCESSABLE_CONTENT', {
+                message: 'Enable two-factor authentication before requiring it on every login.',
+            });
+        }
+        if (before.requireTwoFactorOnLogin === input.enabled) {
+            return before;
+        }
+        await this.drizzle.db
+            .update(user)
+            .set({ requireTwoFactorOnLogin: input.enabled })
+            .where(eq(user.id, userId));
+        if (input.enabled) {
+            await this.trustedDevices?.revokeAllForUser(userId, userId);
+        }
+        this.events.emit('identity.security.require_two_factor.updated', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            previousEnabled: before.requireTwoFactorOnLogin,
+            enabled: input.enabled,
+            ip,
+            userAgent,
+        });
+        return { ...before, requireTwoFactorOnLogin: input.enabled };
+    }
+    /**
+     * Sets (or overwrites) the player's anti-phishing code: a free-text, case-sensitive
+     * recognition phrase stamped into every outgoing platform email so the player can tell a
+     * genuine email from a phishing attempt. Unlike the withdrawal PIN this authorizes nothing,
+     * so - like `setLoginWithdrawalAlerts` - it takes no reauth and there is no remove route;
+     * calling it again with a new value just changes the code.
+     */
+    async setAntiPhishingCode(input, reqHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
+        const userId = await this.currentUserId(nodeHeadersToHeaders(reqHeaders));
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in.' });
+        }
+        const [caller] = await this.drizzle.db
+            .select({ role: user.role, email: user.email, language: user.language })
+            .from(user)
+            .where(eq(user.id, userId))
+            .limit(1);
+        if (caller?.role !== 'player') {
+            // A service-level denial still owes the audit log the same signal AdminGuard emits,
+            // since this check rejects before any shared guard runs (docs/standards/audit.md).
+            this.events.emit('identity.user.unauthorized_access', {
+                userId,
+                playerId: null,
+                resource: 'identity.security.anti_phishing_code',
+                action: 'set',
+                ...(caller?.role ? { role: caller.role } : {}),
+                ip,
+                userAgent,
+            });
+            throw new ORPCError('FORBIDDEN', {
+                message: 'Only players can set this preference.',
+            });
+        }
+        const before = await this.securityControlsFor(userId);
+        if (before.antiPhishingCode === input.code) {
+            return before;
+        }
+        await assertRateLimit(this.limiter, makeRateLimitKey(RATE_LIMIT_KEYS.ANTI_PHISHING_CODE_MUTATION, userId), ANTI_PHISHING_CODE_RATE_LIMIT);
+        await this.drizzle.db
+            .update(user)
+            .set({ antiPhishingCode: input.code })
+            .where(eq(user.id, userId));
+        this.events.emit('identity.security.anti_phishing_code.set', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            wasAlreadySet: before.antiPhishingCode !== null,
+            ip,
+            userAgent,
+        });
+        // Deliberately address-only: resolving a user recipient later would stamp the email with
+        // the replacement code. This notice instead carries the prior code, which lets the owner
+        // recognise it even if a stolen session changed the current value.
+        // The row is already committed, so a failed enqueue must not fail the mutation: the
+        // caller would see an error for a change that landed, and retrying the same value exits
+        // at the no-op branch above without ever re-sending the notice.
+        try {
+            await this.mailDispatch?.toAddress({
+                email: caller.email,
+                locale: caller.language,
+                template: {
+                    key: 'securityAntiPhishingCodeChanged',
+                    data: { previousAntiPhishingCode: before.antiPhishingCode },
+                },
+                idempotencyKey: `anti-phishing-code-changed:${userId}:${randomUUID()}`,
+            });
+        }
+        catch (err) {
+            identityLogger.error({ err, userId }, 'anti-phishing code change notice enqueue failed');
+        }
+        return { ...before, antiPhishingCode: input.code };
+    }
+    /**
+     * Resends the registration code. Unauthenticated by design - the player has no session
+     * until the code is verified - so it answers SUCCESS for every address and only mails a
+     * code to an account that exists and is still unverified. Verified accounts are skipped
+     * deliberately: `verifyEmail` signs the code's bearer in, so resending to a verified
+     * address would turn this into passwordless sign-in for anyone who can read that inbox.
+     */
+    async sendEmailVerification(input, reqHeaders) {
+        const { ip } = extractClientMeta(reqHeaders);
+        const email = input.email.toLowerCase();
+        await assertRateLimit(this.limiter, `email-verify:${email}`, EMAIL_VERIFICATION_RATE_LIMIT);
+        if (ip) {
+            await assertRateLimit(this.limiter, `email-verify-ip:${ip}`, EMAIL_VERIFICATION_RATE_LIMIT);
+        }
+        const [row] = await this.drizzle.db
+            .select({ emailVerified: user.emailVerified })
+            .from(user)
+            .where(eq(user.email, email))
+            .limit(1);
+        if (row && !row.emailVerified) {
+            await this.api.sendVerificationOTP({
+                body: { email, type: 'email-verification' },
+                headers: nodeHeadersToHeaders(reqHeaders),
+                asResponse: true,
+            });
         }
         return SUCCESS;
     }
-    async verifyEmail(input, reqHeaders) {
+    /**
+     * Consumes the 6-digit code mailed by `register()` and signs the player in -
+     * better-auth's `autoSignInAfterVerification` mints the session here rather than at
+     * sign-up, which is what lets sign-up stay sessionless and therefore keep its
+     * duplicate-email response indistinguishable. Same post-credential gates as `login`:
+     * a code is proof of address ownership, not a bypass for an RG or backoffice block.
+     */
+    async verifyEmail(input, reqHeaders, resHeaders) {
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
-        const userId = await this.currentUserId(headers);
-        await assertRateLimit(this.limiter, `verify-email:${userId ?? 'anonymous'}`, VERIFY_EMAIL_RATE_LIMIT);
-        const res = await this.api.verifyEmail({
-            query: { token: input.token },
+        const email = input.email.toLowerCase();
+        // Keyed on the address under attack (six digits are guessable) and on the caller, so
+        // one client can neither grind a single account nor sweep many.
+        await assertRateLimit(this.limiter, `verify-email:${email}`, VERIFY_EMAIL_RATE_LIMIT);
+        // Only when the caller's IP is actually known: an `unknown` bucket would be shared by
+        // every anonymous caller, letting one client stall everyone else's sign-up.
+        if (ip) {
+            await assertRateLimit(this.limiter, `verify-email-ip:${ip}`, VERIFY_EMAIL_RATE_LIMIT);
+        }
+        const res = await this.api.verifyEmailOTP({
+            body: { email, otp: input.otp },
             headers,
             asResponse: true,
         });
-        await ensureOk(res);
-        if (userId) {
-            this.events.emit('identity.email.verified', { userId });
+        await ensureOk(res, { genericMessage: 'Invalid or expired verification code' });
+        const body = (await res.json());
+        // better-auth has already committed `emailVerified` by now, so the audit record is
+        // emitted before any gate below can throw - a state change that leaves no trail is a
+        // compliance gap, see docs/standards/audit.md.
+        const playerId = await this.identityReader.getPlayerIdByUserIdSafe(body.user.id);
+        this.events.emit('identity.email.verified', { userId: body.user.id, playerId, ip, userAgent });
+        const [account] = await this.drizzle.db
+            .select({
+            id: user.id,
+            rgBlocked: user.rgBlocked,
+            rgBlockedUntil: user.rgBlockedUntil,
+            twoFactorEnabled: user.twoFactorEnabled,
+        })
+            .from(user)
+            .where(eq(user.id, body.user.id))
+            .limit(1);
+        if (account) {
+            await this.assertAccountNotBlocked(account, { ip, userAgent });
         }
-        return SUCCESS;
+        // Before the 2FA branch below: that path ends the session it just minted, but the zone
+        // the browser reported is good either way.
+        await captureTimezone(this.playerProvisioning, body.user.id, input.timezone);
+        // better-auth mints this session with `createSession`, which its twoFactor plugin only
+        // hooks on the sign-in routes - so an enrolled account would get a full session from
+        // the emailed code alone, bypassing its second factor. Verification still stands; the
+        // session does not, and the player signs in through `login` to face the challenge.
+        if (account?.twoFactorEnabled) {
+            // Scoped to the token this call just minted: the player's other devices did nothing
+            // wrong, and an unrelated sign-out here would be indistinguishable from a session
+            // hijack. The RG/backoffice branch above is the one that revokes everything.
+            if (body.token) {
+                await this.drizzle.db
+                    .update(session)
+                    .set({ expiresAt: new Date() })
+                    .where(eq(session.token, body.token));
+            }
+            return { twoFactorRedirect: true };
+        }
+        if (!body.token) {
+            throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Verification did not sign you in' });
+        }
+        this.forwardCookies(res, resHeaders);
+        await this.drizzle.db
+            .update(session)
+            .set({ ipAddress: ip, userAgent })
+            .where(eq(session.token, body.token));
+        this.events.emit('identity.user.login', { userId: body.user.id, playerId, ip, userAgent });
+        this.events.emit('identity.authentication.succeeded', {
+            userId: body.user.id,
+            playerId,
+            method: 'email_verification',
+            ip,
+            userAgent,
+        });
+        const sessionDurationSeconds = this.auth.options.session?.expiresIn ?? SESSION_DURATION_IN_SECONDS;
+        return {
+            user: toUser(body.user),
+            session: {
+                token: body.token,
+                expiresAt: new Date(Date.now() + sessionDurationSeconds * 1000).toISOString(),
+            },
+        };
     }
     async changeEmail(input, reqHeaders, resHeaders) {
         const headers = nodeHeadersToHeaders(reqHeaders);
+        const userId = await this.currentUserId(headers);
+        const newEmail = input.newEmail.toLowerCase();
         const res = await this.api.changeEmail({
             body: { newEmail: input.newEmail },
             headers,
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
+        if (userId) {
+            // better-auth's `/change-email` returns the same `{ status: true }` shape for the
+            // anti-enumeration no-op (target already owned by someone else) and for a deferred
+            // confirmation-email flow, where the address only actually changes once the
+            // confirmation link is clicked - neither of which touched this row yet. Requiring
+            // `user.email` to already equal the requested address scopes the disable to the
+            // one branch (`updateEmailWithoutVerification`) that updates it synchronously.
+            const [disabled] = await this.drizzle.db
+                .update(user)
+                .set({ loginWithdrawalAlertsEnabled: false })
+                .where(and(eq(user.id, userId), eq(user.loginWithdrawalAlertsEnabled, true), eq(user.email, newEmail)))
+                .returning({ id: user.id });
+            if (disabled) {
+                const { ip, userAgent } = extractClientMeta(reqHeaders);
+                this.events.emit('identity.security.login_withdrawal_alerts.updated', {
+                    userId,
+                    playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                    previousEnabled: true,
+                    enabled: false,
+                    ip,
+                    userAgent,
+                });
+            }
+        }
         return SUCCESS;
     }
     async updateProfile(input, reqHeaders, resHeaders) {
         if (input.language !== undefined) {
             assertSupportedLanguage(input.language, this.platformConfig);
         }
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         const headers = nodeHeadersToHeaders(reqHeaders);
         // better-auth's field parser and drizzle's mapUpdateSet both drop `undefined`
         // values before the SQL SET clause, so omitted fields are safely no-ops here.
@@ -497,12 +2001,17 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         // updateUser returns { status } only - re-read from session to get the full user.
         const session = await this.auth.api.getSession({ headers });
         const current = session?.user;
         if (current) {
-            this.events.emit('identity.profile.updated', { userId: current.id });
+            this.events.emit('identity.profile.updated', {
+                userId: current.id,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(current.id),
+                ip,
+                userAgent,
+            });
         }
         if (!current) {
             throw new Error('Profile update succeeded but session could not be re-read');