@openora/core 0.4.1-canary.13 → 0.4.1-canary.130

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

@@ -1,9 +1,16 @@
+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, 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 { 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';
 function nodeHeadersToHeaders(nodeHeaders) {
     const headers = new Headers();
     for (const [key, value] of Object.entries(nodeHeaders)) {
@@ -14,15 +21,6 @@ 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(),
-        },
-    });
-}
 function toIso(value) {
     return value instanceof Date ? value.toISOString() : value;
 }
@@ -31,22 +29,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 +56,98 @@ 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;
+}
+// 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 +157,54 @@ 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 };
 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;
+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 +218,288 @@ 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;
+    sessions;
+    constructor({ drizzle, events, identityReader, mailDispatch, options, limiter, platformConfig, geoCheck, playerProvisioning, cache, trustedDevices, twoFactorLockout, 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.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 });
+                    },
+                }
+                : {}),
+            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;
     }
-    async register(input, reqHeaders, resHeaders) {
-        await assertRateLimit(this.limiter, `register:${input.email.toLowerCase()}`, REGISTER_RATE_LIMIT);
+    async securityControlsFor(userId) {
+        const controls = await getSecurityControls(this.drizzle, userId);
+        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' } },
+        });
+    }
+    /**
+     * 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 +514,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,6 +528,9 @@ 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,
@@ -210,8 +542,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,28 +552,65 @@ 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)) {
+            const trusted = 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 };
@@ -248,49 +618,114 @@ export class IdentityService {
             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 +733,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 +805,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 +905,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 +914,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;
     }
@@ -362,51 +955,236 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         const body = (await res.json());
         return { totpUri: body.totpURI, backupCodes: body.backupCodes };
     }
     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 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.
+        const trustDevice = input.trustDevice && input.method === 'totp' && this.trustedDevices !== undefined;
+        const body = { code: input.code, trustDevice };
+        const res = input.method === 'backup_code'
+            ? await this.api.verifyBackupCode({ body, headers, asResponse: true })
+            : await this.api.verifyTOTP({ body, headers, asResponse: true });
+        if (!res.ok && challengedUserId) {
+            await this.twoFactorLockout?.recordFailure(challengedUserId, { ip, userAgent });
+        }
+        await ensureOk(res);
+        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));
+        if (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 });
+            }
+            await captureTimezone(this.playerProvisioning, userId, input.timezone);
+        }
+        return SUCCESS;
+    }
+    /**
+     * 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);
+        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);
+        // Only a live authenticator earns the trust window - a backup code is a recovery
+        // credential and the schema never lets one reach this route.
+        const verified = await this.api.verifyTOTP({
+            body: { code: input.code, trustDevice: true },
+            headers: challengeHeaders,
+            asResponse: true,
+        });
+        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: 'totp',
+            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.api.verifyTOTP({
-            body: { code: input.code },
+            body: { code, trustDevice: false },
             headers,
             asResponse: true,
         });
-        await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        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);
-        if (userId) {
-            this.events.emit('identity.2fa.enabled', { userId });
+        await assertRateLimit(this.limiter, `backupCodes:${userId ?? 'anonymous'}`, TWO_FACTOR_PASSWORD_RATE_LIMIT);
+        if (!userId) {
+            throw new ORPCError('UNAUTHORIZED', { message: 'Not signed in' });
         }
-        return SUCCESS;
+        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);
         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);
+        // 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 });
+        this.events.emit('identity.2fa.disabled', {
+            userId,
+            playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+            method: 'totp',
+            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,22 +1194,30 @@ 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) {
@@ -444,49 +1230,230 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
+        if (userId) {
+            await this.drizzle.db
+                .update(user)
+                .set({ passwordMeetsPolicy: true })
+                .where(eq(user.id, userId));
+        }
         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);
+    }
+    async setLoginWithdrawalAlerts(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 })
+            .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.login_withdrawal_alerts',
+                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 (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 };
+    }
+    /**
+     * 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 +1464,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');