games_app/backend/dist/services/authService.d.ts
2026-07-02 09:21:05 +02:00

163 lines
6.0 KiB
TypeScript

/**
* Authentication and user identity service.
* Handles registration, login, JWT issuance, profile management, password changes, and TOTP 2FA.
*/
import { SystemSettings } from '../models';
import { type UserGender } from '../models/userGender';
import { JwtPayload, RoleName } from '../types';
/** Builds JWT claims from current DB roles and permissions. */
export declare function buildJwtPayload(user: {
id: string;
email_hash: string;
}): Promise<JwtPayload>;
/** Normalizes legacy JWT payloads that only contain a single `role`. */
export declare function normalizeJwtPayload(decoded: JwtPayload): JwtPayload;
/**
* Validates a password against the system password policy from settings.
* @param password Plain-text password to validate
* @param policy System settings containing password rules
* @throws {Error} When the password fails any configured policy rule
*/
export declare function validatePassword(password: string, policy: SystemSettings): void;
/**
* Registers a new user with profile, country, and optional referral code.
*/
export declare function register(input: {
email: string;
password: string;
fullName: string;
phone?: string;
countryOfResidence: string;
nationality?: string;
gender: string;
referralCode?: string;
registrationIp?: string;
userAgent?: string;
visitorSupportToken?: string | null;
}): Promise<{
userId: string;
referralCode: string;
emailVerificationRequired: boolean;
}>;
/**
* Authenticates a user and issues access and refresh tokens.
* @param email User email for lookup
* @param password Plain-text password
* @param totpCode Optional TOTP code when 2FA is enabled
* @param auditContext Optional IP and user agent for login audit log
* @returns Access token, refresh token, expiry seconds, and basic user info
* @throws {Error} On invalid credentials, disabled/locked account, or failed 2FA
*/
export declare function login(email: string, password: string, totpCode?: string, auditContext?: {
ipAddress?: string;
userAgent?: string;
visitorSupportToken?: string | null;
}): Promise<{
accessToken: string;
refreshToken: string;
expiresIn: number;
user: {
id: string;
emailHash: string;
role: RoleName;
roles: RoleName[];
permissions: string[];
primaryRole: RoleName;
};
}>;
/**
* Issues a new access token from a valid refresh token.
* @param refreshToken Opaque refresh token issued at login
* @returns New access token and remaining lifetime in seconds
* @throws {Error} When refresh token is invalid or user no longer exists
*/
export declare function refreshTokens(refreshToken: string): Promise<{
accessToken: string;
expiresIn: number;
}>;
/**
* Returns decrypted profile fields for the authenticated user.
* @param userId User UUID
* @returns Profile fields (names, date of birth, email, phone)
* @throws {Error} When user is not found
*/
export declare function getProfile(userId: string): Promise<{
id: string;
firstName: string | null;
middleName: string | null;
lastName: string | null;
dateOfBirth: string | null;
email: string | null;
phone: string | null;
countryOfResidence: string | null;
nationality: string | null;
gender: UserGender | null;
role: string;
emailVerified: boolean;
totpEnabled: boolean;
createdAt: string;
}>;
/**
* Updates user profile fields; email and phone are re-hashed and encrypted.
* @param userId User UUID
* @param updates Partial profile updates (undefined fields are skipped)
* @throws {Error} When user not found, email/phone empty, or already used by another account
*/
export declare function updateProfile(userId: string, updates: {
firstName?: string | null;
middleName?: string | null;
lastName?: string | null;
dateOfBirth?: string | null;
email?: string;
phone?: string | null;
countryOfResidence?: string | null;
nationality?: string | null;
gender?: string;
}): Promise<void>;
/**
* Changes the user's password after verifying the current one.
* @param userId User UUID
* @param currentPassword Existing plain-text password
* @param newPassword New plain-text password (validated against policy)
* @throws {Error} When user not found, current password wrong, or new password fails policy
*/
export declare function changePassword(userId: string, currentPassword: string, newPassword: string): Promise<void>;
/**
* Generates a new TOTP secret and QR code for 2FA setup (not yet enabled until confirmed).
* @param userId User UUID
* @returns Base32 secret and data-URL QR code for authenticator apps
* @throws {Error} When user is not found
*/
export declare function setupTotp(userId: string): Promise<{
secret: string;
qrCodeUrl: string;
}>;
/**
* Confirms and enables 2FA after the user verifies a TOTP code from setup.
* @param userId User UUID
* @param code Six-digit TOTP code from authenticator app
* @throws {Error} When 2FA was not set up or code is invalid
*/
export declare function enableTotp(userId: string, code: string): Promise<void>;
/**
* Verifies TOTP for sensitive actions (e.g. transfer). No-op when 2FA is disabled.
* @param userId User UUID
* @param totpCode Optional six-digit TOTP code
* @throws {Error} When user not found, 2FA enabled but code missing/invalid
*/
export declare function verifyTotp(userId: string, totpCode?: string): Promise<void>;
/**
* Verifies and decodes a JWT access token.
* @param accessToken Signed JWT string
* @returns Decoded payload with userId, emailHash, and role
* @throws jwt.JsonWebTokenError When token is invalid or expired
*/
export declare function verifyToken(accessToken: string): Promise<JwtPayload>;
/**
* Returns a guard function that throws if the JWT payload role is not allowed.
* @param allowed Roles permitted for the protected route
* @returns Callback that validates payload.role against allowed list
* @throws {Error} Forbidden when role is not in allowed
*/
export declare function requireRole(allowed: RoleName[]): (payload: JwtPayload) => void;
//# sourceMappingURL=authService.d.ts.map