153 lines
5.6 KiB
TypeScript
153 lines
5.6 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';
|
|
/**
|
|
* 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;
|
|
};
|
|
}>;
|
|
/**
|
|
* 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
|