213 lines
7.6 KiB
TypeScript
213 lines
7.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';
|
|
/** Builds JWT claims from current DB roles and permissions. */
|
|
export declare function buildJwtPayload(user: {
|
|
id: string;
|
|
email_hash: string;
|
|
token_version?: number;
|
|
}): 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;
|
|
}, captchaToken?: string): Promise<{
|
|
accessToken: string;
|
|
refreshToken: string;
|
|
expiresIn: number;
|
|
user: {
|
|
id: string;
|
|
emailHash: string;
|
|
role: RoleName;
|
|
roles: RoleName[];
|
|
permissions: string[];
|
|
primaryRole: RoleName;
|
|
};
|
|
}>;
|
|
/**
|
|
* 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<void>;
|
|
/**
|
|
* Revokes all refresh tokens for the user (logout everywhere).
|
|
*/
|
|
export declare function logoutAll(userId: string, auditContext?: {
|
|
ipAddress?: string;
|
|
userAgent?: string;
|
|
}): Promise<void>;
|
|
/**
|
|
* 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, auditContext?: {
|
|
ipAddress?: string;
|
|
userAgent?: 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, 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<void>;
|
|
/**
|
|
* 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<void>;
|
|
/**
|
|
* 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<void>;
|
|
/**
|
|
* 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<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
|