@nauth-toolkit/core 0.1.39 → 0.1.40

package/dist/services/auth-service-internal-helpers.d.ts

@@ -0,0 +1,229 @@
+import { Repository } from 'typeorm';
+import { IUser } from '../interfaces/entities.interface';
+import { BaseUser, BaseLoginAttempt, BaseChallengeSession } from '../entities';
+import { PasswordService } from './password.service';
+import { SessionService } from './session.service';
+import { EmailVerificationService } from './email-verification.service';
+import { PhoneVerificationService } from './phone-verification.service';
+import { ClientInfoService } from './client-info.service';
+import { ChallengeService } from './challenge.service';
+import { AuthChallengeHelperService } from './auth-challenge-helper.service';
+import { AccountLockoutStorageService } from '../storage/account-lockout-storage.service';
+import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
+import { TrustedDeviceService } from './trusted-device.service';
+import { MFAService } from './mfa.service';
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+import { ChallengeResponseData, CollectPhoneResponse, VerifyPhoneResponse, VerifyMFACodeResponse, VerifyMFAPasskeyResponse, MFASetupResponse } from '../dto/challenge-response.dto';
+import { AuthResponseDTO } from '../dto/auth-response.dto';
+import { UpdateUserAttributesRequestDTO } from '../dto/update-user-attributes-request.dto';
+import { NAuthConfig } from '../interfaces/config.interface';
+import { NAuthLogger } from '../utils/nauth-logger';
+/**
+ * Internal helper service for AuthService
+ *
+ * Contains private utility methods for challenge handling, validation,
+ * password management, and login tracking. This class is NOT exported from
+ * the package and should only be used internally by AuthService.
+ *
+ * INTERNAL USE ONLY - DO NOT IMPORT DIRECTLY
+ *
+ * @internal
+ */
+export declare class AuthServiceInternalHelpers {
+    private readonly userRepository;
+    private readonly loginAttemptRepository;
+    private readonly emailVerificationService;
+    private readonly phoneVerificationService;
+    private readonly challengeService;
+    private readonly challengeHelper;
+    private readonly clientInfoService;
+    private readonly sessionService;
+    private readonly accountLockoutStorage;
+    private readonly config;
+    private readonly logger;
+    constructor(userRepository: Repository<BaseUser>, loginAttemptRepository: Repository<BaseLoginAttempt>, emailVerificationService: EmailVerificationService, phoneVerificationService: PhoneVerificationService | undefined, challengeService: ChallengeService, challengeHelper: AuthChallengeHelperService, clientInfoService: ClientInfoService, sessionService: SessionService, accountLockoutStorage: AccountLockoutStorageService, config: NAuthConfig, logger: NAuthLogger);
+    /**
+     * Handle VERIFY_EMAIL challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param code - Email verification code
+     * @returns Authentication response with tokens or next challenge
+     */
+    handleVerifyEmail(challengeSession: BaseChallengeSession & {
+        user?: BaseUser;
+    }, code: string): Promise<AuthResponseDTO>;
+    /**
+     * Handle VERIFY_PHONE challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - Phone verification data (phone number or code)
+     * @returns Authentication response with tokens or next challenge
+     */
+    handleVerifyPhone(challengeSession: BaseChallengeSession & {
+        user?: BaseUser;
+    }, data: VerifyPhoneResponse | CollectPhoneResponse): Promise<AuthResponseDTO>;
+    /**
+     * Handle MFA_REQUIRED challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - MFA verification data
+     * @param mfaService - MFA service (passed from AuthService)
+     * @param trustedDeviceService - Trusted device service (optional, passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    handleMFAVerification(challengeSession: BaseChallengeSession & {
+        user?: BaseUser;
+    }, data: VerifyMFACodeResponse | VerifyMFAPasskeyResponse, mfaService: MFAService | undefined, trustedDeviceService: TrustedDeviceService | undefined, auditService: AuthAuditService | undefined): Promise<AuthResponseDTO>;
+    /**
+     * Handle FORCE_CHANGE_PASSWORD challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param newPassword - New password
+     * @param passwordService - Password service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    handleForceChangePassword(challengeSession: BaseChallengeSession & {
+        user?: BaseUser;
+    }, newPassword: string, passwordService: PasswordService, auditService: AuthAuditService | undefined): Promise<AuthResponseDTO>;
+    /**
+     * Handle MFA_SETUP_REQUIRED challenge
+     *
+     * @param challengeSession - Challenge session with user
+     * @param data - MFA setup data
+     * @param mfaService - MFA service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Authentication response with tokens or next challenge
+     */
+    handleMFASetup(challengeSession: BaseChallengeSession & {
+        user?: BaseUser;
+    }, data: MFASetupResponse, mfaService: MFAService | undefined, _auditService: AuthAuditService | undefined): Promise<AuthResponseDTO>;
+    /**
+     * Validate that response type matches expected challenge type
+     *
+     * @param expected - Expected challenge type
+     * @param provided - Provided challenge type
+     * @throws {NAuthException} If types don't match
+     */
+    validateChallengeTypeMatch(expected: string, provided: string): void;
+    /**
+     * Validate parameters for challenge type
+     *
+     * Service-level validation ensures Express/other frameworks get same validation as NestJS.
+     * This is critical for non-DTO-based applications.
+     *
+     * @param type - Challenge type
+     * @param data - Challenge response data
+     * @throws {NAuthException} If validation fails
+     */
+    validateChallengeParams(type: string, data: ChallengeResponseData): void;
+    /**
+     * Checks if the login identifier matches the specified allowed type.
+     *
+     * Determines if the given identifier is a valid email, username, phone, or allowed hybrid,
+     * according to the configured identifier type restriction.
+     *
+     * @param identifier - The login identifier to check (email, username, or phone)
+     * @param allowedType - The permitted identifier type ('email', 'username', 'phone', or 'email_or_username')
+     * @returns True if the identifier conforms to the allowed type, otherwise false
+     */
+    validateIdentifierType(identifier: string, allowedType: 'email' | 'username' | 'phone' | 'email_or_username'): boolean;
+    /**
+     * Ensures email, phone, and username are unique for other users before update.
+     *
+     * Throws if another user already has the specified email, phone, or username.
+     *
+     * @param userId - Internal numeric user ID (excluded from check)
+     * @param updateData - User fields to check for uniqueness
+     * @throws {NAuthException} If a unique constraint is violated for email, phone, or username
+     */
+    validateUniquenessConstraints(userId: number, updateData: UpdateUserAttributesRequestDTO): Promise<void>;
+    /**
+     * Retrieves a user entity by login identifier.
+     *
+     * Performs a lookup for a user by email, username, or phone number.
+     * The search respects the identifierType restriction when provided, limiting which fields are queried.
+     *
+     * @param identifier - Login credential (email, username, or phone)
+     * @param identifierType - Restricts search to a specific identifier type ('email', 'username', 'phone', or 'email_or_username')
+     * @returns The user entity if found, otherwise null
+     */
+    findUserByIdentifier(identifier: string, identifierType?: 'email' | 'username' | 'phone' | 'email_or_username'): Promise<IUser | null>;
+    /**
+     * Centralized password update flow used by:
+     * - changePassword()
+     * - confirmForgotPassword()
+     * - adminSetPassword()
+     * - FORCE_CHANGE_PASSWORD challenge handler
+     *
+     * WHY:
+     * - Prevent logic drift between different password-changing entrypoints
+     * - Ensure consistent validation, history enforcement, persistence, session revocation, and audit trails
+     *
+     * @param params - Password update parameters
+     * @param passwordService - Password service (passed from AuthService)
+     * @param auditService - Audit service (optional, passed from AuthService)
+     * @returns Sessions revoked count (0 when not revoked)
+     * @throws {NAuthException} WEAK_PASSWORD | PASSWORD_REUSED | NOT_FOUND
+     */
+    updateUserPassword(params: {
+        user: IUser;
+        newPassword: string;
+        mustChangePassword: boolean;
+        revokeSessions: boolean;
+        revokeReason: string;
+        beforePersist?: () => Promise<void>;
+        audit?: {
+            eventType: AuthAuditEventType;
+            eventStatus: 'SUCCESS' | 'FAILURE' | 'INFO' | 'SUSPICIOUS';
+            reason?: string;
+            description?: string;
+            authMethod?: string;
+            metadata?: Record<string, unknown>;
+        };
+    }, passwordService: PasswordService, auditService: AuthAuditService | undefined): Promise<{
+        sessionsRevoked: number;
+    }>;
+    /**
+     * Handles a failed login by recording the attempt, applying IP-based lockout policy,
+     * and invoking relevant hooks.
+     *
+     * @param identifier - User identifier (email/username/phone)
+     * @param reason - Optional reason for failure
+     */
+    handleFailedLogin(identifier: string, reason?: string): Promise<void>;
+    /**
+     * Records a login attempt with client context.
+     *
+     * @param email - User's email address
+     * @param success - True if login succeeded, false if failed
+     * @param failureReason - Optional reason for failure
+     * @param userId - Optional internal user ID (only for successful logins)
+     */
+    recordLoginAttempt(email: string, success: boolean, failureReason?: string, userId?: number): Promise<void>;
+    /**
+     * Clear authentication cookies from response
+     *
+     * @param response - HTTP response object with clearCookie method
+     * @param forgetDevice - Whether to also clear device token cookie
+     */
+    clearAuthCookies(response: {
+        clearCookie?: (name: string, options?: unknown) => void;
+    }, forgetDevice: boolean): void;
+    /**
+     * Mask email address for privacy (show first char and domain)
+     *
+     * @param email - Email address to mask
+     * @returns Masked email (e.g., 'u***r@example.com')
+     */
+    maskEmail(email: string): string;
+    /**
+     * Mask phone number for privacy (show last 4 digits)
+     *
+     * @param phone - Phone number to mask
+     * @returns Masked phone (e.g., '***-***-1234')
+     */
+    maskPhone(phone: string): string;
+}
+//# sourceMappingURL=auth-service-internal-helpers.d.ts.map

package/dist/services/auth-service-internal-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-service-internal-helpers.d.ts","sourceRoot":"","sources":["../../src/services/auth-service-internal-helpers.ts"],"names":[],"mappings":"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"}