@nauth-toolkit/core 0.1.39 → 0.1.40

package/dist/services/user.service.d.ts

@@ -0,0 +1,274 @@
+import { Repository } from 'typeorm';
+import { IUser } from '../interfaces/entities.interface';
+import { BaseUser, BaseMFADevice, BaseChallengeSession, BaseVerificationToken, BaseSocialAccount, BaseAuthAudit, BaseTrustedDevice, BaseSession, BaseLoginAttempt } from '../entities';
+import { SessionService } from './session.service';
+import { ClientInfoService } from './client-info.service';
+import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
+import { HookRegistryService } from './hook-registry.service';
+import { NAuthConfig } from '../interfaces/config.interface';
+import { NAuthLogger } from '../utils/nauth-logger';
+import { GetUsersDTO, GetUsersResponseDTO } from '../dto/get-users.dto';
+import { GetUserByIdDTO } from '../dto/get-user-by-id.dto';
+import { GetUserByEmailDTO } from '../dto/get-user-by-email.dto';
+import { UpdateUserAttributesRequestDTO } from '../dto/update-user-attributes-request.dto';
+import { UpdateVerifiedStatusRequestDTO } from '../dto/update-verified-status-request.dto';
+import { DeleteUserDTO, DeleteUserResponseDTO } from '../dto/delete-user.dto';
+import { DisableUserDTO, DisableUserResponseDTO } from '../dto/disable-user.dto';
+import { EnableUserDTO, EnableUserResponseDTO } from '../dto/enable-user.dto';
+import { SetMustChangePasswordDTO } from '../dto/set-must-change-password.dto';
+import { SetMustChangePasswordResponseDTO } from '../dto/set-must-change-password-response.dto';
+import { UserResponseDto } from '../dto/user-response.dto';
+import { AuthServiceInternalHelpers } from './auth-service-internal-helpers';
+/**
+ * Internal user data management service
+ *
+ * Handles all user storage, query, and lifecycle operations.
+ * 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 UserService {
+    private readonly userRepository;
+    private readonly loginAttemptRepository;
+    private readonly sessionService;
+    private readonly config;
+    private readonly logger;
+    private readonly mfaDeviceRepository?;
+    private readonly auditService?;
+    private readonly hookRegistry?;
+    private readonly clientInfoService;
+    private readonly sessionRepository?;
+    private readonly verificationTokenRepository?;
+    private readonly socialAccountRepository?;
+    private readonly challengeSessionRepository?;
+    private readonly authAuditRepository?;
+    private readonly trustedDeviceRepository?;
+    private readonly helpers;
+    constructor(userRepository: Repository<BaseUser>, loginAttemptRepository: Repository<BaseLoginAttempt>, sessionService: SessionService, config: NAuthConfig, logger: NAuthLogger, mfaDeviceRepository?: Repository<BaseMFADevice> | undefined, auditService?: AuthAuditService | undefined, hookRegistry?: HookRegistryService | undefined, clientInfoService?: ClientInfoService, sessionRepository?: Repository<BaseSession> | undefined, verificationTokenRepository?: Repository<BaseVerificationToken> | undefined, socialAccountRepository?: Repository<BaseSocialAccount> | undefined, challengeSessionRepository?: Repository<BaseChallengeSession> | undefined, authAuditRepository?: Repository<BaseAuthAudit> | undefined, trustedDeviceRepository?: Repository<BaseTrustedDevice> | undefined, helpers?: AuthServiceInternalHelpers);
+    /**
+     * Get paginated list of users with advanced filtering
+     *
+     * Supports pagination, boolean filters, exact match filters,
+     * date filters with operators (gt, gte, lt, lte, eq), and flexible sorting.
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Returns sanitized user data (no passwordHash, secrets)
+     *
+     * @param dto - Filters, pagination, sorting
+     * @returns Paginated user list with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.getUsers({
+     *   page: 1,
+     *   limit: 20,
+     *   isEmailVerified: true,
+     *   hasSocialAuth: true,
+     *   createdAt: { operator: 'gte', value: new Date('2024-01-01') },
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    getUsers(dto: GetUsersDTO): Promise<GetUsersResponseDTO>;
+    /**
+     * Get user by external identifier (sub/UUID).
+     *
+     * @param dto - GetUserByIdDTO containing sub
+     * @returns User response DTO or null if not found
+     *
+     * @example
+     * ```typescript
+     * const user = await userService.getUserById({ sub: 'user-uuid' });
+     * ```
+     */
+    getUserById(dto: GetUserByIdDTO): Promise<UserResponseDto | null>;
+    /**
+     * Get user by email address.
+     *
+     * @param dto - GetUserByEmailDTO containing email and optional requireEmailVerified
+     * @returns User response DTO or null if not found
+     * @internal - For use by social auth providers
+     *
+     * @example
+     * ```typescript
+     * const user = await userService.getUserByEmail({ email: 'user@example.com', requireEmailVerified: true });
+     * ```
+     */
+    getUserByEmail(dto: GetUserByEmailDTO): Promise<UserResponseDto | null>;
+    /**
+     * Get user for authentication context
+     *
+     * Loads user by sub (external identifier) with all fields needed for auth context.
+     * Computes hasPasswordHash from passwordHash, then removes passwordHash and other sensitive fields.
+     *
+     * This method is used by AuthHandler and AuthGuard to load authenticated users.
+     * It ensures consistent user object shape across platforms (core + NestJS).
+     *
+     * @param sub - External user identifier (UUID)
+     * @returns User object with hasPasswordHash flag, without sensitive fields
+     * @throws {NAuthException} If user not found or account is inactive
+     *
+     * @example
+     * ```typescript
+     * const user = await userService.getUserForAuthContext('user-uuid-123');
+     * // user.hasPasswordHash === true/false
+     * // user.passwordHash === undefined (removed)
+     * ```
+     */
+    getUserForAuthContext(sub: string): Promise<IUser>;
+    /**
+     * Update user profile attributes.
+     *
+     * Updates user fields (name, email, phone, username, metadata) and enforces unique constraints and verification rules.
+     *
+     * @param dto - UpdateUserAttributesRequestDTO containing sub and fields to update
+     * @returns Updated user object
+     * @throws {NAuthException} If user not found or unique constraint violated
+     *
+     * @example
+     * ```typescript
+     * await userService.updateUserAttributes({ sub: 'user-uuid', email: 'test@example.com' });
+     * ```
+     */
+    updateUserAttributes(dto: UpdateUserAttributesRequestDTO): Promise<UserResponseDto>;
+    /**
+     * Update email and/or phone verification status.
+     *
+     * Intended for admin use cases such as migration or offline validation.
+     * Updates verification status without requiring actual verification codes.
+     *
+     * Validation:
+     * - 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)
+     *
+     * Audit:
+     * - Records EMAIL_VERIFIED or PHONE_VERIFIED audit events
+     * - Includes performedBy from authenticated admin context
+     *
+     * @param dto - Request DTO containing sub and verification status flags
+     * @returns Updated user object
+     * @throws {NAuthException} If user not found or trying to verify non-existent email/phone
+     *
+     * @example
+     * ```typescript
+     * // Update email verification only
+     * await userService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true
+     * });
+     *
+     * // Update both email and phone verification
+     * await userService.updateVerifiedStatus({
+     *   sub: 'user-uuid',
+     *   isEmailVerified: true,
+     *   isPhoneVerified: false
+     * });
+     * ```
+     */
+    updateVerifiedStatus(dto: UpdateVerifiedStatusRequestDTO): Promise<UserResponseDto>;
+    /**
+     * Delete a user and all associated data (cascade deletion).
+     *
+     * Permanently removes a user account and all related records:
+     * - Sessions
+     * - Verification tokens
+     * - MFA devices
+     * - Trusted devices
+     * - Social accounts
+     * - Login attempts
+     * - Challenge sessions
+     * - Audit logs (user-specific)
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Records ACCOUNT_DELETED audit event before deletion
+     * - Returns counts of deleted records for confirmation
+     *
+     * @param dto - DeleteUserDTO containing sub
+     * @returns Response with success status and deleted record counts
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.deleteUser({ sub: 'user-uuid-123' });
+     * console.log(`Deleted ${result.deletedRecords.sessions} sessions`);
+     * ```
+     */
+    deleteUser(dto: DeleteUserDTO): Promise<DeleteUserResponseDTO>;
+    /**
+     * Administrative permanent account locking
+     *
+     * Sets permanent lock (lockedUntil=NULL) and immediately revokes all active sessions.
+     * Reuses existing rate-limit lock fields (isLocked, lockReason, lockedAt, lockedUntil).
+     *
+     * Permanent vs Temporary locks:
+     * - Rate limiting: lockedUntil = future date (temporary auto-unlock)
+     * - Admin disableUser: lockedUntil = NULL (permanent manual lock)
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Revokes all sessions immediately (forced logout)
+     * - Records ACCOUNT_DISABLED audit event with admin identifier
+     *
+     * @param dto - User sub and optional reason
+     * @returns User object with updated lock status and revoked session count
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.disableUser({
+     *   sub: 'user-uuid-123',
+     *   reason: 'Suspicious activity detected'
+     * });
+     * console.log(`Revoked ${result.revokedSessions} sessions`);
+     * ```
+     */
+    disableUser(dto: DisableUserDTO): Promise<DisableUserResponseDTO>;
+    /**
+     * Enable (unlock) user account
+     *
+     * Unlocks a previously locked user account by clearing all lock fields.
+     * This reverses the effect of disableUser() or rate-limit lockouts.
+     *
+     * Security:
+     * - NO built-in authentication - endpoint MUST be protected by admin guards
+     * - Clears lock fields (isLocked, lockReason, lockedAt, lockedUntil)
+     * - Resets failed login attempts counter
+     * - Records ACCOUNT_ENABLED audit event with admin identifier
+     *
+     * @param dto - User sub to enable
+     * @returns User object with updated lock status
+     * @throws {NAuthException} USER_NOT_FOUND
+     *
+     * @example
+     * ```typescript
+     * const result = await userService.enableUser({
+     *   sub: 'user-uuid-123'
+     * });
+     * console.log(`User unlocked: ${result.user.email}`);
+     * ```
+     */
+    enableUser(dto: EnableUserDTO): Promise<EnableUserResponseDTO>;
+    /**
+     * Require user to change password at next login.
+     *
+     * Throws if user not found or has no password set (e.g. social login only).
+     *
+     * @param dto - SetMustChangePasswordDTO containing userId (sub)
+     * @returns Success response
+     * @throws {NAuthException} If user is not found or cannot change password
+     *
+     * @example
+     * ```typescript
+     * await userService.setMustChangePassword({ userId: 'user-uuid-123' });
+     * ```
+     */
+    setMustChangePassword(dto: SetMustChangePasswordDTO): Promise<SetMustChangePasswordResponseDTO>;
+}
+//# sourceMappingURL=user.service.d.ts.map

package/dist/services/user.service.d.ts.map

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