@nauth-toolkit/core 0.1.37 → 0.1.40

package/dist/dto/update-verified-status-request.dto.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Update Verified Status Request DTO
+ *
+ * Request DTO for updating email and/or phone verification status.
+ * Intended for admin use cases such as migration or offline validation.
+ *
+ * Security:
+ * - User sub validated (UUID)
+ * - Cannot set verified=true if email/phone doesn't exist
+ * - Can set verified=false even if email/phone doesn't exist (default state)
+ * - Only updates provided fields (partial update)
+ *
+ * @example
+ * ```typescript
+ * // Update email verification only
+ * await authService.updateVerifiedStatus({
+ *   sub: 'user-uuid',
+ *   isEmailVerified: true
+ * });
+ *
+ * // Update both email and phone verification
+ * await authService.updateVerifiedStatus({
+ *   sub: 'user-uuid',
+ *   isEmailVerified: true,
+ *   isPhoneVerified: false
+ * });
+ * ```
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateVerifiedStatusRequestDTO = void 0;
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+/**
+ * Request DTO for updating verification status
+ */
+class UpdateVerifiedStatusRequestDTO {
+    /**
+     * User's unique identifier (UUID v4)
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Matches DB constraint: char(36) or uuid
+     *
+     * Sanitization:
+     * - Trimmed
+     * - Lowercased for consistency
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
+    sub;
+    /**
+     * Email verification status
+     *
+     * Validation:
+     * - If set to true, user must have an email address
+     * - If set to false, can be set even if email doesn't exist (default state)
+     * - Optional - only updates if provided
+     *
+     * @example true
+     */
+    isEmailVerified;
+    /**
+     * Phone verification status
+     *
+     * Validation:
+     * - If set to true, user must have a phone number
+     * - If set to false, can be set even if phone doesn't exist (default state)
+     * - Optional - only updates if provided
+     *
+     * @example true
+     */
+    isPhoneVerified;
+}
+exports.UpdateVerifiedStatusRequestDTO = UpdateVerifiedStatusRequestDTO;
+__decorate([
+    (0, class_validator_1.IsUUID)('4', { message: 'User sub must be a valid UUID v4 format' }),
+    (0, class_transformer_1.Transform)(({ value }) => {
+        if (typeof value === 'string') {
+            return value.trim().toLowerCase();
+        }
+        return value;
+    }),
+    __metadata("design:type", String)
+], UpdateVerifiedStatusRequestDTO.prototype, "sub", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)({ message: 'isEmailVerified must be a boolean' }),
+    (0, class_validator_1.ValidateIf)((o) => o.isEmailVerified !== undefined),
+    __metadata("design:type", Boolean)
+], UpdateVerifiedStatusRequestDTO.prototype, "isEmailVerified", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)({ message: 'isPhoneVerified must be a boolean' }),
+    (0, class_validator_1.ValidateIf)((o) => o.isPhoneVerified !== undefined),
+    __metadata("design:type", Boolean)
+], UpdateVerifiedStatusRequestDTO.prototype, "isPhoneVerified", void 0);
+//# sourceMappingURL=update-verified-status-request.dto.js.map

package/dist/dto/update-verified-status-request.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-verified-status-request.dto.js","sourceRoot":"","sources":["../../src/dto/update-verified-status-request.dto.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;;;;;;;AAEH,qDAA4E;AAC5E,yDAA8C;AAE9C;;GAEG;AACH,MAAa,8BAA8B;IACzC;;;;;;;;;;;;OAYG;IAQH,GAAG,CAAU;IAEb;;;;;;;;;OASG;IAIH,eAAe,CAAW;IAE1B;;;;;;;;;OASG;IAIH,eAAe,CAAW;CAC3B;AApDD,wEAoDC;AA/BC;IAPC,IAAA,wBAAM,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,yCAAyC,EAAE,CAAC;IACnE,IAAA,6BAAS,EAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE;QACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;;2DACW;AAeb;IAHC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,EAAC,EAAE,OAAO,EAAE,mCAAmC,EAAE,CAAC;IAC3D,IAAA,4BAAU,EAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC;;uEACzB;AAe1B;IAHC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,EAAC,EAAE,OAAO,EAAE,mCAAmC,EAAE,CAAC;IAC3D,IAAA,4BAAU,EAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,SAAS,CAAC;;uEACzB"}

package/dist/interfaces/hooks.interface.d.ts

@@ -96,5 +96,134 @@ export interface SignupMetadata {
      * false (or undefined) for regular user signups
      */
     adminSignup?: boolean;
+    /**
+     * Social metadata from OAuth provider (only present for social signups)
+     *
+     * Contains the raw OAuth profile data stored in the social account metadata field.
+     * This includes all provider-specific fields like sub, given_name, family_name, locale, etc.
+     *
+     * @example
+     * ```json
+     * {
+     *   "sub": "google_123",
+     *   "email": "user@gmail.com",
+     *   "given_name": "John",
+     *   "family_name": "Doe",
+     *   "picture": "https://...",
+     *   "locale": "en"
+     * }
+     * ```
+     */
+    socialMetadata?: Record<string, unknown> | null;
+    /**
+     * Profile picture URL from OAuth provider (only present for social signups)
+     *
+     * Extracted from the OAuth profile for convenience.
+     * Also available in socialMetadata.picture.
+     *
+     * @example "https://lh3.googleusercontent.com/a/..."
+     */
+    profilePicture?: string | null;
+}
+/**
+ * User profile update source
+ *
+ * Indicates what triggered the profile update.
+ */
+export type UserProfileUpdateSource = 'user_request' | 'admin_action' | 'email_verification' | 'phone_verification';
+/**
+ * Changed field metadata
+ *
+ * Tracks old and new values for a single field.
+ */
+export interface ChangedField {
+    /**
+     * Field name that changed
+     */
+    fieldName: string;
+    /**
+     * Previous value before update
+     */
+    oldValue: unknown;
+    /**
+     * New value after update
+     */
+    newValue: unknown;
+}
+/**
+ * User profile updated metadata
+ *
+ * Provides context about the profile update event.
+ */
+export interface UserProfileUpdatedMetadata {
+    /**
+     * Updated user entity (full object after change)
+     */
+    user: IUser;
+    /**
+     * Array of fields that changed with old and new values
+     */
+    changedFields: ChangedField[];
+    /**
+     * What triggered the update
+     */
+    updateSource: UserProfileUpdateSource;
+    /**
+     * Admin user sub who performed the action (only for admin_action source)
+     */
+    performedBy?: string;
+    /**
+     * Client information (IP address, user agent)
+     */
+    clientInfo?: {
+        ipAddress?: string;
+        userAgent?: string;
+        ipCountry?: string;
+        ipCity?: string;
+    };
+}
+/**
+ * User profile updated hook provider interface
+ *
+ * Executes actions after user profile attributes change (non-blocking).
+ * Errors are logged but do not affect the update operation.
+ *
+ * @remarks
+ * This hook is triggered when:
+ * - Core attributes change (firstName, lastName, username, email, phone, metadata)
+ * - Verification status changes (isEmailVerified, isPhoneVerified)
+ *
+ * This hook is NOT triggered for:
+ * - Password changes
+ * - Account lock/unlock
+ * - Login state changes
+ * - MFA changes
+ * - Social account linkages
+ *
+ * The hook is non-blocking. If it throws an error, the error is logged but the update continues.
+ * The user profile has already been updated when the hook is called.
+ *
+ * @example
+ * ```typescript
+ * export class CrmSyncHook implements IUserProfileUpdatedHookProvider {
+ *   async execute(metadata: UserProfileUpdatedMetadata): Promise<void> {
+ *     // Sync to CRM when email changes
+ *     const emailChange = metadata.changedFields.find(f => f.fieldName === 'email');
+ *     if (emailChange) {
+ *       await this.crmService.updateContact(metadata.user.sub, {
+ *         email: emailChange.newValue
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface IUserProfileUpdatedHookProvider {
+    /**
+     * Execute user profile updated actions
+     *
+     * @param metadata - Profile update context with user, changed fields, and update source
+     */
+    execute(metadata: UserProfileUpdatedMetadata): Promise<void>;
 }
 //# sourceMappingURL=hooks.interface.d.ts.map

package/dist/interfaces/hooks.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/hooks.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;OAQG;IACH,OAAO,CACL,IAAI,EAAE,iBAAiB,EACvB,UAAU,EAAE,UAAU,GAAG,QAAQ,EACjC,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}
+{"version":3,"file":"hooks.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/hooks.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;OAQG;IACH,OAAO,CACL,IAAI,EAAE,iBAAiB,EACvB,UAAU,EAAE,UAAU,GAAG,QAAQ,EACjC,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhD;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAMD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,IAAI,EAAE,KAAK,CAAC;IAEZ;;OAEG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;IAE9B;;OAEG;IACH,YAAY,EAAE,uBAAuB,CAAC;IAEtC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D"}

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":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,4CAA4C,CAAC;AAC1F,OAAO,EAAE,wBAAwB,IAAI,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE,OAAO,EACL,qBAAqB,EAErB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EAExB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,8BAA8B,EAAE,MAAM,2CAA2C,CAAC;AAK3F,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIpD;;;;;;;;;;GAUG;AACH,qBAAa,0BAA0B;IAEnC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,wBAAwB;IACzC,OAAO,CAAC,QAAQ,CAAC,wBAAwB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAVN,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,sBAAsB,EAAE,UAAU,CAAC,gBAAgB,CAAC,EACpD,wBAAwB,EAAE,wBAAwB,EAClD,wBAAwB,EAAE,wBAAwB,GAAG,SAAS,EAC9D,gBAAgB,EAAE,gBAAgB,EAClC,eAAe,EAAE,0BAA0B,EAC3C,iBAAiB,EAAE,iBAAiB,EACpC,cAAc,EAAE,cAAc,EAC9B,qBAAqB,EAAE,4BAA4B,EACnD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW;IAOtC;;;;;;OAMG;IACG,iBAAiB,CACrB,gBAAgB,EAAE,oBAAoB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,EAC5D,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC;IA2D3B;;;;;;OAMG;IACG,iBAAiB,CACrB,gBAAgB,EAAE,oBAAoB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,EAC5D,IAAI,EAAE,mBAAmB,GAAG,oBAAoB,GAC/C,OAAO,CAAC,eAAe,CAAC;IA4I3B;;;;;;;;;OASG;IACG,qBAAqB,CACzB,gBAAgB,EAAE,oBAAoB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,EAC5D,IAAI,EAAE,qBAAqB,GAAG,wBAAwB,EACtD,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,oBAAoB,EAAE,oBAAoB,GAAG,SAAS,EACtD,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,OAAO,CAAC,eAAe,CAAC;IAmP3B;;;;;;;;OAQG;IACG,yBAAyB,CAC7B,gBAAgB,EAAE,oBAAoB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,EAC5D,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,eAAe,EAChC,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,OAAO,CAAC,eAAe,CAAC;IAiE3B;;;;;;;;OAQG;IACG,cAAc,CAClB,gBAAgB,EAAE,oBAAoB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,CAAA;KAAE,EAC5D,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,aAAa,EAAE,gBAAgB,GAAG,SAAS,GAC1C,OAAO,CAAC,eAAe,CAAC;IA+E3B;;;;;;OAMG;IACH,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IASpE;;;;;;;;;OASG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI;IA0ExE;;;;;;;;;OASG;IACH,sBAAsB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,mBAAmB,GAChE,OAAO;IAsBV;;;;;;;;OAQG;IACG,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IA4C9G;;;;;;;;;OASG;IACG,oBAAoB,CACxB,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,mBAAmB,GACpE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAiExB;;;;;;;;;;;;;;;;OAgBG;IACG,kBAAkB,CACtB,MAAM,EAAE;QACN,IAAI,EAAE,KAAK,CAAC;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,cAAc,EAAE,OAAO,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,KAAK,CAAC,EAAE;YACN,SAAS,EAAE,kBAAkB,CAAC;YAC9B,WAAW,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;YAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACpC,CAAC;KACH,EACD,eAAe,EAAE,eAAe,EAChC,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,OAAO,CAAC;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAiGvC;;;;;;OAMG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB3E;;;;;;;OAOG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBjH;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE;QAAE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,EAAE,YAAY,EAAE,OAAO,GAAG,IAAI;IA+BpH;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAQhC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAKjC"}