@openora/core 0.4.0 → 0.4.1-canary.100

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

@@ -1,27 +1,23 @@
 import { ORPCError } from '@orpc/server';
-import { createAuth, assertRateLimit, } 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 { user, session, account, verification, twoFactor } from '../schema/index.js';
+import { player } from '@openora/core/pam/schema/profile';
+import { RATE_LIMIT_KEYS, makeRateLimitKey } from '@openora/core/contracts';
 import { assertSupportedLanguage } from '../../shared/language.js';
+import { isRgBlocked } from './rg-guard.service.js';
+import { DEFAULT_LOCKOUT_DURATION_MS, DEFAULT_MAX_LOGIN_ATTEMPTS, computeLockoutTier, createAccountLockedError, hasFailedLoginWindowExpired, makeLoginSecurityState, } from './lockout-policy.service.js';
 function nodeHeadersToHeaders(nodeHeaders) {
     const headers = new Headers();
     for (const [key, value] of Object.entries(nodeHeaders)) {
-        if (value === undefined)
+        if (value === undefined) {
             continue;
+        }
         headers.set(key, Array.isArray(value) ? value.join(', ') : value);
     }
     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;
 }
@@ -30,6 +26,7 @@ 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',
@@ -38,49 +35,61 @@ function toUser(u) {
     };
     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.
 function twoFactorPendingCookieValue(headers) {
     const cookieHeader = headers.get('cookie');
-    if (!cookieHeader)
+    if (!cookieHeader) {
         return undefined;
+    }
     for (const [name, value] of parseCookies(cookieHeader)) {
-        if (name.endsWith('.two_factor'))
+        if (name.endsWith('.two_factor')) {
             return value;
+        }
     }
     return undefined;
 }
 const SUCCESS = { success: true };
+export const UserNotFoundError = makeNotFoundError('User');
+export const UsernameConflictError = makeConflictError('Username', 'Username is already in use');
 // 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) {
-    if (res.ok)
+// 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)
+        if (parsed.message) {
             message = parsed.message;
+        }
     }
     catch {
         // non-JSON body - keep the default message
     }
-    throw new ORPCError(res.status === 401 ? 'UNAUTHORIZED' : 'BAD_REQUEST', { message });
+    throw new ORPCError(code, { message });
 }
-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
@@ -90,79 +99,244 @@ 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 };
 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
+ * doesn't provide: per-account lockout after N failed logins, RG
+ * (responsible-gambling) login blocking, and rate limiting keyed by
+ * caller-identifier (email/token/session), never IP. better-auth calls use
+ * `asResponse: true` and return an error Response rather than throwing, so
+ * every call is routed through `ensureOk` to surface failures as `ORPCError`s.
+ */
 export class IdentityService {
     auth;
     drizzle;
     events;
+    identityReader;
     email;
+    templateRenderer;
     options;
     limiter;
     platformConfig;
-    constructor({ drizzle, events, email, options, limiter, platformConfig }) {
+    playerProvisioning;
+    geoCheck;
+    cache;
+    constructor({ drizzle, events, identityReader, email, templateRenderer, options, limiter, platformConfig, geoCheck, playerProvisioning, cache, }) {
         this.drizzle = drizzle;
         this.events = events;
+        this.identityReader = identityReader;
         this.email = email;
+        this.templateRenderer = templateRenderer;
         this.options = options;
         this.limiter = limiter;
         this.platformConfig = platformConfig;
+        this.geoCheck = geoCheck;
+        this.playerProvisioning = playerProvisioning;
+        this.cache = cache;
         this.auth = createAuth({
             db: drizzle.db,
             schema: { user, session, account, verification, twoFactor },
             ...(email ? { sendEmail: (args) => email.send(args) } : {}),
+            templateRenderer: this.templateRenderer,
+            getUserLanguage: (lookupEmail) => this.resolveUserLanguage(lookupEmail),
+            registrationWebUrl: this.platformConfig?.registration?.webUrl,
+            onExistingUserSignUp: async (existing) => {
+                const response = await this.api.requestPasswordResetEmailOTP({
+                    body: { email: existing.email },
+                    headers: new Headers(),
+                    asResponse: true,
+                });
+                await ensureOk(response);
+            },
+            onPasswordReset: async (resetUser) => {
+                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, language: user.language })
+            .from(user)
+            .where(eq(user.email, email.toLowerCase()))
+            .limit(1);
+        return row;
+    }
+    // Used by the emailOTP plugin's sendVerificationOTP hook to pick a locale for the
+    // reset-password email - better-auth only gives us the target email, not a session.
+    async resolveUserLanguage(email) {
+        const row = await this.findUserByEmail(email);
+        return row?.language ?? null;
+    }
     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) {
+    async register(input, reqHeaders) {
+        const registration = this.platformConfig?.registration;
+        const provisioning = this.playerProvisioning;
+        if (!registration || !provisioning) {
+            throw new ORPCError('FORBIDDEN', { message: 'Registration is unavailable' });
+        }
+        const { ip, userAgent } = extractClientMeta(reqHeaders);
         await assertRateLimit(this.limiter, `register:${input.email.toLowerCase()}`, REGISTER_RATE_LIMIT);
+        await assertRateLimit(this.limiter, `register-ip:${ip ?? 'unknown'}`, REGISTER_RATE_LIMIT);
+        if (this.geoCheck && !(await this.geoCheck.checkRegistration(ip)).allowed) {
+            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)) {
+                throw new UsernameConflictError();
+            }
+            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) {
+            const { playerId } = await this.recordRegistrationConsent(provisioning, body.user.id, registration.termsVersion, { ip, userAgent });
+            this.events.emit('identity.user.registered', {
+                userId: body.user.id,
+                playerId: playerId ?? (await this.identityReader.getPlayerIdByUserIdSafe(body.user.id)),
+                ip,
+                userAgent,
+            });
+        }
+        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 };
+    }
+    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
+     * a pass, so a pre-auth probe can't distinguish a restricted account from a
+     * wrong password. An RG-blocked account still authenticates then has its
+     * fresh session immediately expired and the cookie withheld - it never
+     * counts toward the lockout budget. A 2FA-enrolled account returns
+     * `{ twoFactorRedirect: true }` instead of a session; the client completes
+     * via `verifyTwoFactor`. Failed-attempt counting only advances on a genuine
+     * credential rejection (never on a transient/backend error), via an atomic
+     * `UPDATE ... SET attempts = attempts + 1` so concurrent failures can't each
+     * 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
@@ -172,6 +346,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,
@@ -183,8 +360,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
@@ -192,6 +370,41 @@ 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 };
+            }
+        }
         try {
             const authResponse = await this.auth.api.signInEmail({
                 body: { email, password: input.password, rememberMe: input.rememberMe },
@@ -199,6 +412,17 @@ export class IdentityService {
                 asResponse: true,
             });
             await ensureOk(authResponse);
+            // Resolved once (only when a user was found), before either gate below, so both
+            // the RG-block and the Backoffice-block events - and the eventual login success
+            // event - can all carry playerId.
+            let playerRow;
+            if (existingUser) {
+                [playerRow] = await this.drizzle.db
+                    .select({ id: player.id, status: player.status })
+                    .from(player)
+                    .where(eq(player.userId, existingUser.id))
+                    .limit(1);
+            }
             // 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
@@ -208,12 +432,41 @@ export class IdentityService {
                     .update(session)
                     .set({ expiresAt: new Date() })
                     .where(eq(session.userId, existingUser.id));
-                this.events.emit('rg.exclusion.login_blocked', { userId: existingUser.id, ip, userAgent });
+                this.events.emit('rg.exclusion.login_blocked', {
+                    userId: existingUser.id,
+                    playerId: playerRow?.id ?? null,
+                    ip,
+                    userAgent,
+                });
                 throw new ORPCError('FORBIDDEN', {
                     message: 'Account access is currently restricted (responsible gambling).',
+                    data: { code: 'RG_BLOCKED' },
                 });
             }
-            forwardCookies(authResponse, resHeaders);
+            // Backoffice-initiated account block (status suspended/closed). Same shape as the
+            // RG gate above: applied only AFTER credentials verify, kills the just-issued
+            // session and withholds its cookie. Distinct mechanism from RG (self_excluded is
+            // out of scope here) - a suspended/closed player can never log back in.
+            if (existingUser &&
+                playerRow &&
+                (playerRow.status === 'suspended' || playerRow.status === 'closed')) {
+                await this.drizzle.db
+                    .update(session)
+                    .set({ expiresAt: new Date() })
+                    .where(eq(session.userId, existingUser.id));
+                this.events.emit('player.login_blocked', {
+                    userId: existingUser.id,
+                    playerId: playerRow.id,
+                    status: playerRow.status,
+                    ip,
+                    userAgent,
+                });
+                throw new ORPCError('FORBIDDEN', {
+                    message: 'This account has been suspended and can no longer be used.',
+                    data: { code: 'ACCOUNT_SUSPENDED' },
+                });
+            }
+            this.forwardCookies(authResponse, resHeaders);
             const body = (await authResponse.json());
             if (body.twoFactorRedirect || !body.user || !body.token) {
                 return { twoFactorRedirect: true };
@@ -221,48 +474,106 @@ 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: playerRow?.id ?? null,
+                ip,
+                userAgent,
+            });
+            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,
@@ -270,8 +581,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;
         }
     }
@@ -281,8 +653,83 @@ export class IdentityService {
             .set({ failedLoginAttempts: 0, lockoutUntil: null })
             .where(eq(user.id, userId));
     }
-    async unlockUser(userId, actorId) {
-        const [existingUser] = await this.drizzle.db
+    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');
+        }
+    }
+    // Read by a downstream custom EmailTemplateRenderer (same CACHE binding) to tell an
+    // admin-triggered reset apart from a self-service one within the synchronous
+    // sendVerificationOTP -> templateRenderer.render call chain below.
+    adminPasswordResetMarkerKey(email) {
+        return `admin-password-reset:${email.toLowerCase()}`;
+    }
+    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 OTP email (if any) is delivered through the
+        // sendEmail hook -> notifications; any underlying error 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,
             email: user.email,
@@ -291,11 +738,9 @@ export class IdentityService {
         })
             .from(user)
             .where(eq(user.id, userId))
-            .limit(1);
-        if (!existingUser) {
-            throw new ORPCError('NOT_FOUND', { message: 'User not found' });
-        }
+            .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,
@@ -304,25 +749,35 @@ 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);
-        if (userId)
-            this.events.emit('identity.user.logout', { userId });
+        this.forwardCookies(authResponse, resHeaders);
+        if (userId) {
+            this.events.emit('identity.user.logout', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                ip,
+                userAgent,
+            });
+        }
         return SUCCESS;
     }
     async me(reqHeaders) {
         const headers = nodeHeadersToHeaders(reqHeaders);
         const session = await this.auth.api.getSession({ headers });
-        if (!session?.user)
+        if (!session?.user) {
             return null;
+        }
         return toUser(session.user);
     }
     async enableTwoFactor(input, reqHeaders, resHeaders) {
@@ -335,11 +790,12 @@ 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';
         await assertRateLimit(this.limiter, `verify2fa:${twoFactorKey}`, VERIFY_2FA_RATE_LIMIT);
@@ -349,13 +805,20 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         const userId = await this.currentUserId(headers);
-        if (userId)
-            this.events.emit('identity.2fa.enabled', { userId });
+        if (userId) {
+            this.events.emit('identity.2fa.enabled', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                ip,
+                userAgent,
+            });
+        }
         return SUCCESS;
     }
     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);
@@ -365,19 +828,26 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
-        if (userId)
-            this.events.emit('identity.2fa.disabled', { userId });
+        this.forwardCookies(res, resHeaders);
+        if (userId) {
+            this.events.emit('identity.2fa.disabled', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                ip,
+                userAgent,
+            });
+        }
         return SUCCESS;
     }
     async requestPasswordReset(input) {
-        await assertRateLimit(this.limiter, `pwreset-req:${input.email.toLowerCase()}`, PASSWORD_RESET_REQUEST_RATE_LIMIT);
+        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
         // email (if any) is delivered through the sendEmail hook -> notifications.
         // 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,
             });
@@ -387,22 +857,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) {
@@ -415,7 +893,7 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         return SUCCESS;
     }
     async sendEmailVerification(reqHeaders) {
@@ -429,19 +907,49 @@ export class IdentityService {
         return SUCCESS;
     }
     async verifyEmail(input, reqHeaders) {
+        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 sessionUserId = await this.currentUserId(headers);
+        // Verification links are followed without a session, so an `anonymous` bucket
+        // would be shared by every caller - one client could stall everyone's sign-up.
+        await assertRateLimit(this.limiter, `verify-email:${sessionUserId ?? ip ?? 'unknown'}`, VERIFY_EMAIL_RATE_LIMIT);
         const res = await this.api.verifyEmail({
             query: { token: input.token },
             headers,
             asResponse: true,
         });
         await ensureOk(res);
-        if (userId)
-            this.events.emit('identity.email.verified', { userId });
+        const userId = sessionUserId ?? (await this.userIdFromVerificationToken(input.token));
+        if (userId) {
+            this.events.emit('identity.email.verified', {
+                userId,
+                playerId: await this.identityReader.getPlayerIdByUserIdSafe(userId),
+                ip,
+                userAgent,
+            });
+        }
         return SUCCESS;
     }
+    /**
+     * Better Auth answers an unauthenticated verification with `user: null`, so the
+     * subject is recovered from the token it just accepted - otherwise the audit event
+     * would never fire for the ordinary click-the-link flow.
+     */
+    async userIdFromVerificationToken(token) {
+        const payload = token.split('.')[1];
+        if (!payload) {
+            return null;
+        }
+        let email;
+        try {
+            email = JSON.parse(Buffer.from(payload, 'base64url').toString())
+                .email;
+        }
+        catch {
+            return null;
+        }
+        return typeof email === 'string' ? this.findUserIdByEmail(email) : null;
+    }
     async changeEmail(input, reqHeaders, resHeaders) {
         const headers = nodeHeadersToHeaders(reqHeaders);
         const res = await this.api.changeEmail({
@@ -450,12 +958,14 @@ export class IdentityService {
             asResponse: true,
         });
         await ensureOk(res);
-        forwardCookies(res, resHeaders);
+        this.forwardCookies(res, resHeaders);
         return SUCCESS;
     }
     async updateProfile(input, reqHeaders, resHeaders) {
-        if (input.language !== undefined)
+        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.
@@ -466,12 +976,18 @@ 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 });
+        if (current) {
+            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');
         }