/** * 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 } from '../types'; /** Builds JWT claims from current DB roles and permissions. */ export declare function buildJwtPayload(user: { id: string; email_hash: string; token_version?: number; }): Promise; /** 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; }, captchaToken?: string): Promise<{ accessToken: string; refreshToken: string; expiresIn: number; user: { id: string; emailHash: string; role: string; roles: string[]; permissions: string[]; primaryRole: string; }; }>; /** * Issues a new access/refresh token pair from a valid refresh token (rotation). * @param refreshToken Opaque refresh token issued at login * @returns New access token, rotated refresh token, and remaining lifetime in seconds * @throws {Error} When refresh token is invalid or user no longer exists / is disabled */ export declare function refreshTokens(refreshToken: string): Promise<{ accessToken: string; refreshToken: string; expiresIn: number; }>; /** * Revokes the current refresh token (logout). */ export declare function logout(refreshToken: string, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise; /** * Revokes all refresh tokens for the user (logout everywhere). */ export declare function logoutAll(userId: string, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise; /** * 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; /** True when withdrawals are blocked for this account (security hold / surveillance). */ withdrawalsSuspended: 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; /** * 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, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise; /** * 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, opts?: { password?: string; totpCode?: string; auditContext?: { ipAddress?: string; userAgent?: 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, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise<{ recoveryCodes: string[]; }>; /** * Verifies TOTP for sensitive actions (e.g. transfer). No-op when 2FA is disabled * unless platform policy requires withdrawal 2FA (see assertWithdrawalSecondFactor). */ export declare function verifyTotp(userId: string, totpCode?: string): Promise; /** * Enforces platform withdrawal/transfer 2FA policy. * When require_withdrawal_2fa is enabled, user must have 2FA on and provide a valid code. */ export declare function assertWithdrawalSecondFactor(userId: string, totpCode?: string): Promise; /** * Disables 2FA after verifying password and TOTP / recovery code. */ export declare function disableTotp(userId: string, password: string, code: string, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise; /** * Issues new recovery codes (invalidates previous). Requires valid TOTP. */ export declare function regenerateRecoveryCodes(userId: string, totpCode: string, auditContext?: { ipAddress?: string; userAgent?: string; }): Promise<{ recoveryCodes: string[]; }>; /** * 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; /** * 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: string[]): (payload: JwtPayload) => void; //# sourceMappingURL=authService.d.ts.map