@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/AdminAccounts.d.ts

@@ -0,0 +1,329 @@
+import type { GameServerUrls } from "../GameServer.js";
+import { type AdminCaller } from "./AdminApiRouter.js";
+import type { AdminPreferences, AdminRole, AdminUserView, SetupOwnerRequest, SignInRequest, SignInStepView, TotpEnrolmentView } from "./AdminApiTypes.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminUserRecord, ConsoleSessionRecord } from "./AdminRecords.js";
+import type { AdminStore, StoredDocument } from "./AdminStore.js";
+import type { ConsoleSessions, SignInContext } from "./ConsoleSessions.js";
+/** A new account (R32). */
+export interface NewAdminUserInput {
+    username: string;
+    displayName: string;
+    email: string | null;
+    role: AdminRole;
+    /** The first password, or null for an SSO-only account. */
+    password: string | null;
+    oidcSubject: string | null;
+}
+/** A second factor: an authenticator code or a recovery code (R32). */
+export type SecondFactorProof = {
+    code: string;
+} | {
+    recoveryCode: string;
+};
+/** A finished sign-in. */
+export interface SignInResult {
+    /** The new console session. */
+    session: ConsoleSessionRecord;
+    /** Its cookie value (sent once in Set-Cookie). */
+    cookieValue: string;
+    /** New recovery codes after an enrolment; empty otherwise. */
+    recoveryCodes: string[];
+    /** The account. */
+    user: AdminUserRecord;
+}
+/** Called after an account is locked, so it can be audited (T3). */
+export type AccountLockoutListener = (user: AdminUserRecord, clientAddress: string) => void;
+/** The admin accounts of the store. */
+export declare class AdminAccounts {
+    /** The admin store. */
+    private readonly store;
+    /** The clock of expiries and lockouts. */
+    private readonly clock;
+    /** The console sessions. */
+    private readonly sessions;
+    /** Whether the console is on (a setup link is offered only then). */
+    private readonly consoleEnabled;
+    /** The pending first-owner setup, or null. */
+    private setupLink;
+    /** Told when an account is locked. */
+    private lockoutListener;
+    /**
+     * Creates the account service.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param sessions The console sessions.
+     * @param consoleEnabled admin.console.
+     */
+    constructor(store: AdminStore, clock: AdminClock, sessions: ConsoleSessions, consoleEnabled: boolean);
+    /**
+     * Sets who is told when an account is locked (the audit log).
+     * @param listener The listener.
+     */
+    onLockout(listener: AccountLockoutListener): void;
+    /**
+     * 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.
+     */
+    ensureSetupLink(urls: GameServerUrls): Promise<void>;
+    /**
+     * Whether a first-owner setup link is waiting to be used.
+     * @returns True until it is used or expires.
+     */
+    hasPendingSetup(): boolean;
+    /**
+     * Whether any account exists.
+     * @returns True when the users collection is not empty.
+     */
+    hasUsers(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    hasAnotherEnabledOwner(ownerId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    createOwnerFromSetup(request: SetupOwnerRequest): Promise<SignInStepView>;
+    /**
+     * 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.
+     */
+    private isSetupLinkLive;
+    /** Removes every process's setup link once the first owner exists: one owner ends them all. */
+    private forgetSetupLinks;
+    /**
+     * 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.
+     */
+    createUser(input: NewAdminUserInput): Promise<AdminUserRecord>;
+    /**
+     * Reads an account.
+     * @param userId The account id.
+     * @returns The stored account, or null.
+     */
+    getUser(userId: string): Promise<StoredDocument<AdminUserRecord> | null>;
+    /**
+     * Finds an account by username.
+     * @param username The username (any case).
+     * @returns The stored account, or null.
+     */
+    findByUsername(username: string): Promise<StoredDocument<AdminUserRecord> | 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.
+     */
+    beginSignIn(request: SignInRequest, context: SignInContext): Promise<SignInStepView>;
+    /**
+     * 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.
+     */
+    beginEnrolment(pendingToken: string): Promise<TotpEnrolmentView>;
+    /**
+     * 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.
+     */
+    completeEnrolment(pendingToken: string, code: string, context: SignInContext): Promise<SignInResult>;
+    /**
+     * 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.
+     */
+    completeSecondFactor(pendingToken: string, proof: SecondFactorProof, context: SignInContext): Promise<SignInResult>;
+    /**
+     * 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: AdminUserRecord): Promise<SignInStepView>;
+    /**
+     * 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.
+     */
+    signInVerified(userId: string, context: SignInContext): Promise<SignInResult>;
+    /**
+     * 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.
+     */
+    completeSecondFactorWithPasskey(pendingToken: string, userId: string, context: SignInContext): Promise<SignInResult>;
+    /**
+     * 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.
+     */
+    stepUp(caller: AdminCaller, proof: SecondFactorProof): Promise<ConsoleSessionRecord>;
+    /**
+     * 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.
+     */
+    changePassword(userId: string, currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * 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.
+     */
+    setPassword(stored: StoredDocument<AdminUserRecord>, newPassword: string): Promise<void>;
+    /**
+     * Replaces an account's recovery codes.
+     * @param userId The account.
+     * @returns The new codes (shown once).
+     */
+    regenerateRecoveryCodes(userId: string): Promise<string[]>;
+    /**
+     * Saves an account's console preferences.
+     * @param userId The account.
+     * @param preferences The preferences.
+     * @returns The stored account.
+     */
+    updatePreferences(userId: string, preferences: AdminPreferences): Promise<StoredDocument<AdminUserRecord>>;
+    /**
+     * Clears an account's lock and failure count.
+     * @param userId The account.
+     */
+    unlock(userId: string): Promise<void>;
+    /**
+     * Removes an account's authenticator and recovery codes; its next sign-in enrols a new one.
+     * @param userId The account.
+     */
+    resetSecondFactor(userId: string): Promise<void>;
+    /**
+     * The console's view of an account (never its secrets).
+     * @param stored The stored account.
+     * @returns The view.
+     */
+    toUserView(stored: StoredDocument<AdminUserRecord>): AdminUserView;
+    /**
+     * Whether an account is locked now.
+     * @param user The account.
+     * @returns True while lockedUntil is in the future.
+     */
+    isLocked(user: AdminUserRecord): boolean;
+    /**
+     * 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.
+     */
+    private applySecondFactor;
+    /**
+     * 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.
+     */
+    private finishSignIn;
+    /**
+     * 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.
+     */
+    private startPendingSignIn;
+    /**
+     * 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.
+     */
+    private requirePendingSignIn;
+    /**
+     * Reads an account that must exist.
+     * @param userId The account id.
+     * @returns The stored account.
+     * @throws AdminRequestError 404 when it does not exist.
+     */
+    private requireUser;
+    /**
+     * 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.
+     */
+    private requireUsableUser;
+    /**
+     * 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.
+     */
+    private recordFailure;
+    /**
+     * 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.
+     */
+    private lock;
+    /**
+     * 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.
+     */
+    private addFailure;
+    /**
+     * The failures of a counter within the lockout window.
+     * @param failureId The counter.
+     * @returns How many.
+     */
+    private recentFailures;
+    /**
+     * Keeps the failure times within ACCOUNT_LOCKOUT_WINDOW_MS.
+     * @param failures ISO times.
+     * @param now The current time, in milliseconds.
+     * @returns The recent ones.
+     */
+    private withinWindow;
+    /**
+     * Waits on the admin clock.
+     * @param milliseconds How long.
+     * @returns Resolves after the wait.
+     */
+    private delay;
+    /**
+     * @returns The clock's now as an ISO time.
+     */
+    private nowIso;
+}