@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AdminAccounts.js

@@ -0,0 +1,607 @@
+// Admin accounts (game-server-admin-console D8, D30, DR §7.1, §7.2): the first-owner setup link, account creation,
+// the two-factor sign-in with lockout, authenticator enrolment, recovery codes and step-up checks.
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { ACCOUNT_LOCKOUT_FAILURES, ACCOUNT_LOCKOUT_WINDOW_MS, ADDRESS_SIGN_IN_FAILURES, CONSOLE_BASE_PATH, PENDING_SIGN_IN_LIFETIME_MS, SETUP_LINK_LIFETIME_MS, SIGN_IN_DELAY_MAX_MS, SIGN_IN_DELAY_STEP_MS } from "./AdminConstants.js";
+import { randomToken, sha256Hex, textsMatch } from "./AdminCrypto.js";
+import { hashPassword, passwordProblem, timingEqualizerPasswordHash, verifyPassword } from "./AdminPasswords.js";
+import { buildOtpauthUri, consumeRecoveryCode, generateRecoveryCodes, generateTotpSecret, verifyTotp } from "./OneTimeCodes.js";
+/** HTTP statuses of account refusals. */
+const HTTP_BAD_REQUEST = 400;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_NOT_FOUND = 404;
+const HTTP_CONFLICT = 409;
+const HTTP_LOCKED = 423;
+const HTTP_TOO_MANY_REQUESTS = 429;
+/** Usernames: lower case letters, digits, dot, underscore and dash, 3 to 32 characters. */
+const USERNAME_PATTERN = /^[a-z0-9._-]{3,32}$/;
+/** Random bytes of a user id. */
+const USER_ID_BYTES = 16;
+/** Random bytes of a setup token and a pending sign-in token. */
+const TOKEN_BYTES = 32;
+/** Preferences of a new account. */
+const DEFAULT_PREFERENCES = { theme: "system", timeZone: "local" };
+/** The answer of every failed password check (the same for an unknown user). */
+const WRONG_CREDENTIALS_MESSAGE = "wrong username or password";
+/** The answer of a locked account (R33). */
+const LOCKED_MESSAGE = "this account is locked; try again later";
+/** The answer of a used, expired or wrong setup token (R33). */
+const INVALID_SETUP_MESSAGE = "this setup link is not valid";
+/** The answer of a wrong, reused or missing second factor. */
+const WRONG_CODE_MESSAGE = "wrong or already used code";
+/** The answer of an unknown or expired pending sign-in. */
+const SIGN_IN_EXPIRED_MESSAGE = "this sign-in has expired; sign in again";
+/** The admin accounts of the store. */
+export class AdminAccounts {
+    /** The admin store. */
+    store;
+    /** The clock of expiries and lockouts. */
+    clock;
+    /** The console sessions. */
+    sessions;
+    /** Whether the console is on (a setup link is offered only then). */
+    consoleEnabled;
+    /** The pending first-owner setup, or null. */
+    setupLink = null;
+    /** Told when an account is locked. */
+    lockoutListener = null;
+    /**
+     * Creates the account service.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param sessions The console sessions.
+     * @param consoleEnabled admin.console.
+     */
+    constructor(store, clock, sessions, consoleEnabled) {
+        this.store = store;
+        this.clock = clock;
+        this.sessions = sessions;
+        this.consoleEnabled = consoleEnabled;
+    }
+    /**
+     * Sets who is told when an account is locked (the audit log).
+     * @param listener The listener.
+     */
+    onLockout(listener) {
+        this.lockoutListener = listener;
+    }
+    /**
+     * Offers a one-time first-owner setup link when no account exists (D30, DR §7.1): the link is logged once at warn
+     * level and only its hash is kept. On Redis the hash is stored as well as held here, because behind a load balancer
+     * the request that uses the link can reach any process, and on Colyseus Cloud there is no shell to create an owner
+     * from. A file store has one process, so a first start writes nothing to the data folder.
+     * @param urls Where the server is reached.
+     */
+    async ensureSetupLink(urls) {
+        if (!this.consoleEnabled || await this.hasUsers())
+            return;
+        const setupToken = randomToken(TOKEN_BYTES);
+        this.setupLink = { tokenHash: sha256Hex(setupToken), expiresAtMilliseconds: this.clock.now() + SETUP_LINK_LIFETIME_MS };
+        if (this.store.kind === "redis")
+            await this.store.putDocument("setupLinks", this.setupLink.tokenHash, this.setupLink, null);
+        getLogger().warn("admin setup link", { url: urls.http + CONSOLE_BASE_PATH + "#/setup?token=" + setupToken });
+    }
+    /**
+     * Whether a first-owner setup link is waiting to be used.
+     * @returns True until it is used or expires.
+     */
+    hasPendingSetup() {
+        return this.setupLink != null && this.clock.now() < this.setupLink.expiresAtMilliseconds;
+    }
+    /**
+     * Whether any account exists.
+     * @returns True when the users collection is not empty.
+     */
+    async hasUsers() {
+        return (await this.store.listDocuments("users")).length > 0;
+    }
+    /**
+     * Whether an enabled owner other than this account exists (DR §5: the last enabled owner is never removed, demoted
+     * or disabled — by the users routes or by a single sign-on role mapping).
+     * @param ownerId The owner that would lose the role.
+     * @returns True when another enabled owner remains.
+     */
+    async hasAnotherEnabledOwner(ownerId) {
+        const users = await this.store.listDocuments("users");
+        return users.some((stored) => stored.value.role === "owner" && !stored.value.disabled && stored.id !== ownerId);
+    }
+    /**
+     * Creates the first owner from the setup link (single use, DR §7.1).
+     * @param request The setup token and the owner's details.
+     * @returns The enrolment step of the owner's first sign-in.
+     * @throws AdminRequestError 404 for a used, expired or wrong token; 400 for an invalid username or password.
+     */
+    async createOwnerFromSetup(request) {
+        const tokenHash = sha256Hex(request.setupToken);
+        if (!await this.isSetupLinkLive(tokenHash) || await this.hasUsers())
+            throw new AdminRequestError(HTTP_NOT_FOUND, INVALID_SETUP_MESSAGE);
+        const owner = await this.createUser({ username: request.username, displayName: request.displayName, email: null, role: "owner", password: request.password, oidcSubject: null });
+        this.setupLink = null;
+        await this.forgetSetupLinks();
+        return this.startPendingSignIn(owner, "enrolSecondFactor");
+    }
+    /**
+     * Whether a token hash names a live setup link of this process or, in the store, of any other. The store is looked
+     * up by the hash, so a wrong token finds nothing.
+     * @param tokenHash The hash of the token offered.
+     * @returns True for a live link.
+     */
+    async isSetupLinkLive(tokenHash) {
+        if (this.setupLink != null && this.hasPendingSetup() && textsMatch(tokenHash, this.setupLink.tokenHash))
+            return true;
+        if (this.store.kind !== "redis")
+            return false;
+        const stored = await this.store.getDocument("setupLinks", tokenHash);
+        return stored != null && this.clock.now() < stored.value.expiresAtMilliseconds;
+    }
+    /** Removes every process's setup link once the first owner exists: one owner ends them all. */
+    async forgetSetupLinks() {
+        if (this.store.kind !== "redis")
+            return;
+        const links = await this.store.listDocuments("setupLinks");
+        await Promise.all(links.map((link) => this.store.deleteDocument("setupLinks", link.id)));
+    }
+    /**
+     * Creates an account (setup, the CLI and the users routes).
+     * @param input The account.
+     * @returns The stored account.
+     * @throws AdminRequestError 400 for an invalid username or password, 409 when the username is taken.
+     */
+    async createUser(input) {
+        const username = input.username.trim().toLowerCase();
+        if (!USERNAME_PATTERN.test(username))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "the username must be 3 to 32 lower-case letters, digits, dots, dashes or underscores");
+        if (await this.findByUsername(username) != null)
+            throw new AdminRequestError(HTTP_CONFLICT, "this username is taken");
+        if (input.password != null) {
+            const problem = passwordProblem(input.password, username);
+            if (problem != null)
+                throw new AdminRequestError(HTTP_BAD_REQUEST, problem);
+        }
+        const now = this.nowIso();
+        const user = {
+            userId: randomToken(USER_ID_BYTES),
+            username: username,
+            displayName: input.displayName.trim() !== "" ? input.displayName.trim() : username,
+            email: input.email,
+            role: input.role,
+            passwordHash: (input.password != null) ? await hashPassword(input.password) : null,
+            totpSecret: null,
+            lastUsedTotpStep: 0,
+            recoveryCodeHashes: [],
+            disabled: false,
+            lockedUntil: null,
+            oidcSubject: input.oidcSubject,
+            preferences: Object.assign({}, DEFAULT_PREFERENCES),
+            createdAt: now,
+            passwordChangedAt: now,
+            lastSignInAt: null
+        };
+        await this.store.putDocument("users", user.userId, user, 0);
+        return user;
+    }
+    /**
+     * Reads an account.
+     * @param userId The account id.
+     * @returns The stored account, or null.
+     */
+    getUser(userId) {
+        return this.store.getDocument("users", userId);
+    }
+    /**
+     * Finds an account by username.
+     * @param username The username (any case).
+     * @returns The stored account, or null.
+     */
+    async findByUsername(username) {
+        const wanted = username.trim().toLowerCase();
+        const users = await this.store.listDocuments("users");
+        return users.find((stored) => stored.value.username === wanted) ?? null;
+    }
+    /**
+     * The first sign-in step (DR §7.2 step 1): the address limit, the account state and the password.
+     * @param request The username and password.
+     * @param context Where the sign-in comes from.
+     * @returns The next step (second factor or enrolment).
+     * @throws AdminRequestError 429 for a noisy address, 423 for a locked account, 401 for wrong credentials.
+     */
+    async beginSignIn(request, context) {
+        const addressFailures = await this.recentFailures(addressFailureId(context.clientAddress));
+        if (addressFailures >= ADDRESS_SIGN_IN_FAILURES)
+            throw new AdminRequestError(HTTP_TOO_MANY_REQUESTS, "too many failed sign-ins from this address; try again later");
+        const stored = await this.findByUsername(request.username);
+        if (stored != null && this.isLocked(stored.value))
+            throw new AdminRequestError(HTTP_LOCKED, LOCKED_MESSAGE);
+        const user = stored?.value ?? null;
+        const accountHash = (user != null && !user.disabled) ? user.passwordHash : null;
+        // An unknown, disabled or password-less account still pays one scrypt, so timing never reveals a username.
+        const hashMatches = await verifyPassword(request.password, accountHash ?? await timingEqualizerPasswordHash());
+        const passwordMatches = accountHash != null && hashMatches;
+        if (user == null || !passwordMatches) {
+            await this.recordFailure(user, context.clientAddress);
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, WRONG_CREDENTIALS_MESSAGE);
+        }
+        return this.startPendingSignIn(user, (user.totpSecret != null) ? "secondFactor" : "enrolSecondFactor");
+    }
+    /**
+     * Offers an authenticator secret to a sign-in that must enrol one (the only answer that shows a secret).
+     * @param pendingToken The pending sign-in.
+     * @returns The secret and its otpauth URI.
+     * @throws AdminRequestError 401 for an unknown or expired sign-in.
+     */
+    async beginEnrolment(pendingToken) {
+        const pending = await this.requirePendingSignIn(pendingToken, "enrolSecondFactor");
+        const user = await this.requireUser(pending.value.userId);
+        const secret = generateTotpSecret();
+        await this.store.putDocument("pendingSignIns", pending.id, Object.assign({}, pending.value, { pendingTotpSecret: secret }), pending.revision);
+        return { secret: secret, otpauthUri: buildOtpauthUri(user.value.username, secret) };
+    }
+    /**
+     * Confirms an enrolment with a code from the new secret and signs in (DR §7.2 step 3).
+     * @param pendingToken The pending sign-in.
+     * @param code The authenticator code.
+     * @param context Where the sign-in comes from.
+     * @returns The session and the account's new recovery codes.
+     * @throws AdminRequestError 401 for an unknown sign-in or a wrong code.
+     */
+    async completeEnrolment(pendingToken, code, context) {
+        const pending = await this.requirePendingSignIn(pendingToken, "enrolSecondFactor");
+        const secret = pending.value.pendingTotpSecret;
+        const stored = await this.requireUser(pending.value.userId);
+        const check = (secret != null) ? verifyTotp(secret, code, 0, this.clock.now()) : { ok: false, step: 0 };
+        if (secret == null || !check.ok) {
+            await this.recordFailure(stored.value, context.clientAddress);
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, WRONG_CODE_MESSAGE);
+        }
+        const recovery = generateRecoveryCodes();
+        const enrolled = Object.assign({}, stored.value, { totpSecret: secret, lastUsedTotpStep: check.step, recoveryCodeHashes: recovery.hashes });
+        return this.finishSignIn(pending.id, stored, enrolled, context, recovery.codes);
+    }
+    /**
+     * Checks the second factor of a sign-in and signs in (DR §7.2 step 3).
+     * @param pendingToken The pending sign-in.
+     * @param proof An authenticator code or a recovery code.
+     * @param context Where the sign-in comes from.
+     * @returns The session.
+     * @throws AdminRequestError 401 for an unknown sign-in or a wrong, reused code.
+     */
+    async completeSecondFactor(pendingToken, proof, context) {
+        const pending = await this.requirePendingSignIn(pendingToken, "secondFactor");
+        const stored = await this.requireUser(pending.value.userId);
+        const verified = this.applySecondFactor(stored.value, proof);
+        if (verified == null) {
+            await this.recordFailure(stored.value, context.clientAddress);
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, WRONG_CODE_MESSAGE);
+        }
+        return this.finishSignIn(pending.id, stored, verified, context, []);
+    }
+    /**
+     * Starts the second-factor step of a single sign-on whose provider gave no multi-factor proof (D26): the account's
+     * authenticator code is asked, or enrolled when it has none.
+     * @param user The account the provider signed in.
+     * @returns The step answer with its pending token.
+     */
+    startSingleSignOnSecondFactor(user) {
+        return this.startPendingSignIn(user, (user.totpSecret != null) ? "secondFactor" : "enrolSecondFactor", true);
+    }
+    /**
+     * Signs in an account whose sign-in already proved both factors: a single sign-on with a multi-factor proof (D26) or
+     * a user-verified passkey (D31).
+     * @param userId The account.
+     * @param context Where the sign-in comes from.
+     * @returns The session.
+     * @throws AdminRequestError 404 for an unknown account, 423 for a locked one, 401 for a disabled one.
+     */
+    async signInVerified(userId, context) {
+        const stored = await this.requireUsableUser(userId);
+        return this.finishSignIn(null, stored, stored.value, context, []);
+    }
+    /**
+     * Completes a password sign-in with a passkey as its second factor (D31).
+     * @param pendingToken The pending sign-in of the password step.
+     * @param userId The account the passkey belongs to.
+     * @param context Where the sign-in comes from.
+     * @returns The session.
+     * @throws AdminRequestError 401 for an unknown or expired sign-in or a passkey of another account.
+     */
+    async completeSecondFactorWithPasskey(pendingToken, userId, context) {
+        const pending = await this.requirePendingSignIn(pendingToken, null);
+        if (pending.value.userId !== userId)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, SIGN_IN_EXPIRED_MESSAGE);
+        const stored = await this.requireUsableUser(userId);
+        return this.finishSignIn(pending.id, stored, stored.value, context, []);
+    }
+    /**
+     * Re-checks the second factor of a signed-in admin, so dangerous actions are allowed for STEP_UP_WINDOW_MS.
+     * @param caller The signed-in caller.
+     * @param proof An authenticator code or a recovery code.
+     * @returns The session with its new secondFactorAt.
+     * @throws AdminRequestError 401 for a wrong code or a caller without a session.
+     */
+    async stepUp(caller, proof) {
+        if (caller.session == null || caller.user == null)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+        const stored = await this.requireUser(caller.user.userId);
+        const verified = this.applySecondFactor(stored.value, proof);
+        if (verified == null)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, WRONG_CODE_MESSAGE);
+        await this.store.putDocument("users", stored.id, verified, stored.revision);
+        const session = await this.sessions.markSecondFactor(caller.session.sessionId);
+        if (session == null)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+        return session;
+    }
+    /**
+     * Changes a signed-in admin's password.
+     * @param userId The account.
+     * @param currentPassword The current password.
+     * @param newPassword The new password.
+     * @throws AdminRequestError 401 for a wrong current password, 400 for a weak new one.
+     */
+    async changePassword(userId, currentPassword, newPassword) {
+        const stored = await this.requireUser(userId);
+        const currentMatches = stored.value.passwordHash != null && await verifyPassword(currentPassword, stored.value.passwordHash);
+        if (!currentMatches)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, "the current password is wrong");
+        await this.setPassword(stored, newPassword);
+    }
+    /**
+     * Sets a new password without the old one (CLI recovery, admin reset).
+     * @param stored The account.
+     * @param newPassword The new password.
+     * @throws AdminRequestError 400 for a weak password.
+     */
+    async setPassword(stored, newPassword) {
+        const problem = passwordProblem(newPassword, stored.value.username);
+        if (problem != null)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, problem);
+        const updated = Object.assign({}, stored.value, { passwordHash: await hashPassword(newPassword), passwordChangedAt: this.nowIso() });
+        await this.store.putDocument("users", stored.id, updated, stored.revision);
+    }
+    /**
+     * Replaces an account's recovery codes.
+     * @param userId The account.
+     * @returns The new codes (shown once).
+     */
+    async regenerateRecoveryCodes(userId) {
+        const stored = await this.requireUser(userId);
+        const recovery = generateRecoveryCodes();
+        await this.store.putDocument("users", stored.id, Object.assign({}, stored.value, { recoveryCodeHashes: recovery.hashes }), stored.revision);
+        return recovery.codes;
+    }
+    /**
+     * Saves an account's console preferences.
+     * @param userId The account.
+     * @param preferences The preferences.
+     * @returns The stored account.
+     */
+    async updatePreferences(userId, preferences) {
+        const stored = await this.requireUser(userId);
+        return this.store.putDocument("users", stored.id, Object.assign({}, stored.value, { preferences: preferences }), stored.revision);
+    }
+    /**
+     * Clears an account's lock and failure count.
+     * @param userId The account.
+     */
+    async unlock(userId) {
+        const stored = await this.requireUser(userId);
+        await this.store.putDocument("users", stored.id, Object.assign({}, stored.value, { lockedUntil: null }), stored.revision);
+        await this.store.deleteDocument("signInFailures", accountFailureId(userId));
+    }
+    /**
+     * Removes an account's authenticator and recovery codes; its next sign-in enrols a new one.
+     * @param userId The account.
+     */
+    async resetSecondFactor(userId) {
+        const stored = await this.requireUser(userId);
+        await this.store.putDocument("users", stored.id, Object.assign({}, stored.value, { totpSecret: null, lastUsedTotpStep: 0, recoveryCodeHashes: [] }), stored.revision);
+    }
+    /**
+     * The console's view of an account (never its secrets).
+     * @param stored The stored account.
+     * @returns The view.
+     */
+    toUserView(stored) {
+        const user = stored.value;
+        return {
+            userId: user.userId,
+            username: user.username,
+            displayName: user.displayName,
+            email: user.email,
+            role: user.role,
+            disabled: user.disabled,
+            locked: this.isLocked(user),
+            hasSecondFactor: user.totpSecret != null,
+            createdAt: user.createdAt,
+            lastSignInAt: user.lastSignInAt,
+            preferences: user.preferences,
+            revision: stored.revision
+        };
+    }
+    /**
+     * Whether an account is locked now.
+     * @param user The account.
+     * @returns True while lockedUntil is in the future.
+     */
+    isLocked(user) {
+        return user.lockedUntil != null && Date.parse(user.lockedUntil) > this.clock.now();
+    }
+    /**
+     * Checks a second factor against an account.
+     * @param user The account.
+     * @param proof A code (its step must be newer than lastUsedTotpStep) or a recovery code (used up).
+     * @returns The account with the code recorded as used, or null when the proof is wrong.
+     */
+    applySecondFactor(user, proof) {
+        if ("recoveryCode" in proof) {
+            const remaining = consumeRecoveryCode(proof.recoveryCode, user.recoveryCodeHashes);
+            return (remaining != null) ? Object.assign({}, user, { recoveryCodeHashes: remaining }) : null;
+        }
+        if (user.totpSecret == null)
+            return null;
+        const check = verifyTotp(user.totpSecret, proof.code, user.lastUsedTotpStep, this.clock.now());
+        return check.ok ? Object.assign({}, user, { lastUsedTotpStep: check.step }) : null;
+    }
+    /**
+     * Ends a sign-in: stores the account, creates the session, deletes the pending record and clears the failures.
+     * @param pendingId The pending sign-in document id, or null for a sign-in without one.
+     * @param stored The account as read.
+     * @param updated The account with the used code recorded.
+     * @param context Where the sign-in comes from.
+     * @param recoveryCodes New recovery codes to show, or none.
+     * @returns The session.
+     */
+    async finishSignIn(pendingId, stored, updated, context, recoveryCodes) {
+        const signedIn = Object.assign({}, updated, { lastSignInAt: this.nowIso() });
+        // The revision check makes a code that two requests send at once work only once.
+        await this.store.putDocument("users", stored.id, signedIn, stored.revision);
+        const created = await this.sessions.create(signedIn, context);
+        if (pendingId != null)
+            await this.store.deleteDocument("pendingSignIns", pendingId);
+        await this.store.deleteDocument("signInFailures", accountFailureId(signedIn.userId));
+        return { session: created.record, cookieValue: created.cookieValue, recoveryCodes: recoveryCodes, user: signedIn };
+    }
+    /**
+     * Stores a sign-in waiting for its second factor.
+     * @param user The account.
+     * @param stage What it waits for.
+     * @param viaSingleSignOn True when the first factor was a single sign-on.
+     * @returns The step answer with the pending token.
+     */
+    async startPendingSignIn(user, stage, viaSingleSignOn = false) {
+        const pendingToken = randomToken(TOKEN_BYTES);
+        const record = { userId: user.userId, stage: stage, pendingTotpSecret: null, expiresAt: new Date(this.clock.now() + PENDING_SIGN_IN_LIFETIME_MS).toISOString(), viaSingleSignOn: viaSingleSignOn };
+        await this.store.putDocument("pendingSignIns", sha256Hex(pendingToken), record, 0);
+        return { stage: stage, pendingToken: pendingToken };
+    }
+    /**
+     * Reads a live pending sign-in of a stage.
+     * @param pendingToken The token.
+     * @param stage The stage the call needs, or null for either stage.
+     * @returns The stored pending sign-in.
+     * @throws AdminRequestError 401 when it is unknown, expired or at another stage.
+     */
+    async requirePendingSignIn(pendingToken, stage) {
+        const stored = await this.store.getDocument("pendingSignIns", sha256Hex(pendingToken));
+        const isAtStage = stored != null && (stage == null || stored.value.stage === stage);
+        const isLive = stored != null && isAtStage && Date.parse(stored.value.expiresAt) > this.clock.now();
+        if (stored == null || !isLive)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, SIGN_IN_EXPIRED_MESSAGE);
+        return stored;
+    }
+    /**
+     * Reads an account that must exist.
+     * @param userId The account id.
+     * @returns The stored account.
+     * @throws AdminRequestError 404 when it does not exist.
+     */
+    async requireUser(userId) {
+        const stored = await this.getUser(userId);
+        if (stored == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such admin user");
+        return stored;
+    }
+    /**
+     * Reads an account that may sign in now.
+     * @param userId The account id.
+     * @returns The stored account.
+     * @throws AdminRequestError 404 when it does not exist, 401 when it is disabled, 423 while it is locked.
+     */
+    async requireUsableUser(userId) {
+        const stored = await this.requireUser(userId);
+        if (stored.value.disabled)
+            throw new AdminRequestError(HTTP_UNAUTHORIZED, "this account is disabled");
+        if (this.isLocked(stored.value))
+            throw new AdminRequestError(HTTP_LOCKED, LOCKED_MESSAGE);
+        return stored;
+    }
+    /**
+     * Counts a failed sign-in for the address and the account, locks the account at ACCOUNT_LOCKOUT_FAILURES, then waits
+     * the growing failure delay (DR §7.2).
+     * @param user The account, or null for an unknown username.
+     * @param clientAddress The client address.
+     */
+    async recordFailure(user, clientAddress) {
+        const addressFailures = await this.addFailure(addressFailureId(clientAddress));
+        let accountFailures = 0;
+        if (user != null) {
+            accountFailures = await this.addFailure(accountFailureId(user.userId));
+            if (accountFailures >= ACCOUNT_LOCKOUT_FAILURES)
+                await this.lock(user, clientAddress);
+        }
+        const recentFailures = Math.max(addressFailures, accountFailures);
+        await this.delay(Math.min(SIGN_IN_DELAY_STEP_MS * recentFailures, SIGN_IN_DELAY_MAX_MS));
+    }
+    /**
+     * Locks an account for ACCOUNT_LOCKOUT_WINDOW_MS and tells the lockout listener.
+     * @param user The account.
+     * @param clientAddress The address of the last failure.
+     */
+    async lock(user, clientAddress) {
+        const stored = await this.getUser(user.userId);
+        if (stored == null)
+            return;
+        const lockedUntil = new Date(this.clock.now() + ACCOUNT_LOCKOUT_WINDOW_MS).toISOString();
+        await this.store.putDocument("users", stored.id, Object.assign({}, stored.value, { lockedUntil: lockedUntil }), null);
+        await this.store.deleteDocument("signInFailures", accountFailureId(user.userId));
+        this.lockoutListener?.(stored.value, clientAddress);
+    }
+    /**
+     * Adds one failure to a counter, dropping failures older than the lockout window.
+     * @param failureId "account:<userId>" or "address:<address>".
+     * @returns The failures within the window, this one included.
+     */
+    async addFailure(failureId) {
+        const now = this.clock.now();
+        const stored = await this.store.getDocument("signInFailures", failureId);
+        const failures = this.withinWindow(stored?.value.failures ?? [], now).concat(new Date(now).toISOString());
+        await this.store.putDocument("signInFailures", failureId, { failures: failures }, null);
+        return failures.length;
+    }
+    /**
+     * The failures of a counter within the lockout window.
+     * @param failureId The counter.
+     * @returns How many.
+     */
+    async recentFailures(failureId) {
+        const stored = await this.store.getDocument("signInFailures", failureId);
+        return this.withinWindow(stored?.value.failures ?? [], this.clock.now()).length;
+    }
+    /**
+     * Keeps the failure times within ACCOUNT_LOCKOUT_WINDOW_MS.
+     * @param failures ISO times.
+     * @param now The current time, in milliseconds.
+     * @returns The recent ones.
+     */
+    withinWindow(failures, now) {
+        return failures.filter((failedAt) => now - Date.parse(failedAt) < ACCOUNT_LOCKOUT_WINDOW_MS);
+    }
+    /**
+     * Waits on the admin clock.
+     * @param milliseconds How long.
+     * @returns Resolves after the wait.
+     */
+    delay(milliseconds) {
+        return new Promise((resolve) => this.clock.setTimeout(resolve, milliseconds));
+    }
+    /**
+     * @returns The clock's now as an ISO time.
+     */
+    nowIso() {
+        return new Date(this.clock.now()).toISOString();
+    }
+}
+/**
+ * @param userId An account id.
+ * @returns Its failure counter id.
+ */
+function accountFailureId(userId) {
+    return "account:" + userId;
+}
+/**
+ * @param clientAddress A client address.
+ * @returns Its failure counter id.
+ */
+function addressFailureId(clientAddress) {
+    return "address:" + clientAddress;
+}