@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/dto/verify-phone.dto.d.ts

@@ -1,24 +1,163 @@
+/**
+ * Verify Phone with Code DTO
+ *
+ * Used for phone verification with 6-digit OTP code.
+ *
+ * Security:
+ * - Phone validated against E.164 format (prevents SQL injection)
+ * - Code validated for exact 6 digits
+ * - All fields match DB constraints
+ *
+ * @example
+ * ```typescript
+ * POST /auth/verify-phone/verify
+ * {
+ *   "phone": "+1234567890",
+ *   "code": "123456"
+ * }
+ * ```
+ */
 export declare class VerifyPhoneWithCodeDTO {
+    /**
+     * User's phone number in E.164 format
+     *
+     * Validation:
+     * - Must be a string
+     * - Must match E.164 format: +[country code][number]
+     * - Max 20 characters (matches DB constraint: varchar(20))
+     *
+     * Sanitization:
+     * - Trimmed
+     * - Whitespace removed
+     *
+     * @example "+1234567890"
+     */
     phone: string;
+    /**
+     * 6-digit verification code
+     *
+     * Validation:
+     * - Must be a string
+     * - Exactly 6 digits (numeric only)
+     * - No letters, spaces, or special characters
+     * - Fixed length prevents timing attacks
+     *
+     * Sanitization:
+     * - Removes all whitespace (users might copy "123 456")
+     * - Ensures only numeric string
+     *
+     * @example "123456"
+     */
     code: string;
+    /**
+     * Challenge session ID (internal use)
+     * Optional - used internally to link verification to specific challenge session.
+     * Provides security by ensuring codes are only valid for the session they were created for.
+     *
+     * Validation:
+     * - Must be a positive integer if provided
+     * - Optional (for backward compatibility and direct verification flows)
+     */
     challengeSessionId?: number;
 }
+/**
+ * DTO for sending verification SMS
+ *
+ * Security:
+ * - User sub validated as UUID v4
+ * - Skip flag is boolean (prevents injection)
+ */
 export declare class SendVerificationSMSDTO {
+    /**
+     * User identifier (UUID v4)
+     *
+     * Validation:
+     * - Must be valid UUID v4 format
+     *
+     * Sanitization:
+     * - Trimmed and lowercased
+     */
     sub: string;
+    /**
+     * Skip the "already verified" check
+     * Used for MFA contexts where codes are needed even if phone is verified
+     *
+     * Validation:
+     * - Must be boolean
+     * - Optional (defaults to true)
+     */
     skipAlreadyVerifiedCheck?: boolean;
+    /**
+     * Challenge session ID to link this verification token to
+     * Optional - for linking verification tokens to specific challenge sessions.
+     * Provides security by preventing old tokens from being used with new sessions.
+     *
+     * Validation:
+     * - Must be a positive integer
+     * - Optional (for backward compatibility and non-challenge flows)
+     */
     challengeSessionId?: number;
 }
+/**
+ * Response DTO for sendVerificationSMS
+ */
 export declare class SendVerificationSMSResponseDTO {
+    /**
+     * Verification token ID (internal integer)
+     */
     tokenId: number;
 }
+/**
+ * Response DTO for verifyPhoneWithCode and verifyPhoneWithCodeBySub
+ */
 export declare class VerifyPhoneResponseDTO {
+    /**
+     * Success message
+     */
     message: string;
 }
+/**
+ * DTO for resending verification SMS
+ *
+ * Supports both sub and phone-based resend
+ *
+ * Security:
+ * - Either sub or phone must be provided (conditional validation)
+ * - Rate limiting applied in service layer
+ * - Input sanitization prevents abuse
+ */
 export declare class ResendVerificationSMSDTO {
+    /**
+     * User identifier (UUID v4) - optional if phone provided
+     *
+     * Validation:
+     * - Must be valid UUID v4 format if provided
+     * - Required if phone is not provided
+     *
+     * Sanitization:
+     * - Trimmed and lowercased
+     */
     sub?: string;
+    /**
+     * User's phone number - optional if sub provided
+     *
+     * Validation:
+     * - Must match E.164 format if provided
+     * - Max 20 characters (DB limit)
+     * - Required if sub is not provided
+     *
+     * Sanitization:
+     * - Whitespace removed
+     */
     phone?: string;
 }
+/**
+ * Response DTO for resendVerificationSMS
+ */
 export declare class ResendVerificationSMSResponseDTO {
+    /**
+     * Verification token ID (internal integer)
+     */
     tokenId: number;
 }
 //# sourceMappingURL=verify-phone.dto.d.ts.map

package/dist/dto/verify-phone.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-phone.dto.d.ts","sourceRoot":"","sources":["../../src/dto/verify-phone.dto.ts"],"names":[],"mappings":"AAkCA,qBAAa,sBAAsB;IA4BjC,KAAK,EAAG,MAAM,CAAC;IA2Bf,IAAI,EAAG,MAAM,CAAC;IAcd,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AASD,qBAAa,sBAAsB;IAiBjC,GAAG,EAAG,MAAM,CAAC;IAYb,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAcnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAKD,qBAAa,8BAA8B;IAIzC,OAAO,EAAG,MAAM,CAAC;CAClB;AAKD,qBAAa,sBAAsB;IAIjC,OAAO,EAAG,MAAM,CAAC;CAClB;AAYD,qBAAa,wBAAwB;IAmBnC,GAAG,CAAC,EAAE,MAAM,CAAC;IAyBb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,qBAAa,gCAAgC;IAI3C,OAAO,EAAG,MAAM,CAAC;CAClB"}
+{"version":3,"file":"verify-phone.dto.d.ts","sourceRoot":"","sources":["../../src/dto/verify-phone.dto.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,sBAAsB;IACjC;;;;;;;;;;;;;OAaG;IAcH,KAAK,EAAG,MAAM,CAAC;IAEf;;;;;;;;;;;;;;OAcG;IAWH,IAAI,EAAG,MAAM,CAAC;IAEd;;;;;;;;OAQG;IAIH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB;IACjC;;;;;;;;OAQG;IAQH,GAAG,EAAG,MAAM,CAAC;IAEb;;;;;;;OAOG;IAGH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;OAQG;IAIH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,8BAA8B;IACzC;;OAEG;IACH,OAAO,EAAG,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,sBAAsB;IACjC;;OAEG;IACH,OAAO,EAAG,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;OASG;IASH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;OAUG;IAaH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,gCAAgC;IAC3C;;OAEG;IACH,OAAO,EAAG,MAAM,CAAC;CAClB"}

package/dist/dto/verify-phone.dto.js

@@ -12,9 +12,66 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResendVerificationSMSResponseDTO = exports.ResendVerificationSMSDTO = exports.VerifyPhoneResponseDTO = exports.SendVerificationSMSResponseDTO = exports.SendVerificationSMSDTO = exports.VerifyPhoneWithCodeDTO = void 0;
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
+/**
+ * Verify Phone with Code DTO
+ *
+ * Used for phone verification with 6-digit OTP code.
+ *
+ * Security:
+ * - Phone validated against E.164 format (prevents SQL injection)
+ * - Code validated for exact 6 digits
+ * - All fields match DB constraints
+ *
+ * @example
+ * ```typescript
+ * POST /auth/verify-phone/verify
+ * {
+ *   "phone": "+1234567890",
+ *   "code": "123456"
+ * }
+ * ```
+ */
 class VerifyPhoneWithCodeDTO {
+    /**
+     * User's phone number in E.164 format
+     *
+     * Validation:
+     * - Must be a string
+     * - Must match E.164 format: +[country code][number]
+     * - Max 20 characters (matches DB constraint: varchar(20))
+     *
+     * Sanitization:
+     * - Trimmed
+     * - Whitespace removed
+     *
+     * @example "+1234567890"
+     */
     phone;
+    /**
+     * 6-digit verification code
+     *
+     * Validation:
+     * - Must be a string
+     * - Exactly 6 digits (numeric only)
+     * - No letters, spaces, or special characters
+     * - Fixed length prevents timing attacks
+     *
+     * Sanitization:
+     * - Removes all whitespace (users might copy "123 456")
+     * - Ensures only numeric string
+     *
+     * @example "123456"
+     */
     code;
+    /**
+     * Challenge session ID (internal use)
+     * Optional - used internally to link verification to specific challenge session.
+     * Provides security by ensuring codes are only valid for the session they were created for.
+     *
+     * Validation:
+     * - Must be a positive integer if provided
+     * - Optional (for backward compatibility and direct verification flows)
+     */
     challengeSessionId;
 }
 exports.VerifyPhoneWithCodeDTO = VerifyPhoneWithCodeDTO;
@@ -27,6 +84,7 @@ __decorate([
     }),
     (0, class_transformer_1.Transform)(({ value }) => {
         if (typeof value === 'string') {
+            // Remove all whitespace and keep only digits and +
             return value.replace(/\s/g, '');
         }
         return value;
@@ -38,8 +96,9 @@ __decorate([
     (0, class_validator_1.Length)(6, 6, { message: 'Verification code must be exactly 6 digits' }),
     (0, class_transformer_1.Transform)(({ value }) => {
         if (typeof value === 'string') {
+            // Remove all whitespace and non-digit characters
             const cleaned = value.replace(/\D/g, '');
-            return cleaned.length === 6 ? cleaned : value;
+            return cleaned.length === 6 ? cleaned : value; // Return original if not 6 digits (let validator catch it)
         }
         return value;
     }),
@@ -51,9 +110,42 @@ __decorate([
     (0, class_validator_1.Min)(1, { message: 'challengeSessionId must be a positive integer' }),
     __metadata("design:type", Number)
 ], VerifyPhoneWithCodeDTO.prototype, "challengeSessionId", void 0);
+/**
+ * DTO for sending verification SMS
+ *
+ * Security:
+ * - User sub validated as UUID v4
+ * - Skip flag is boolean (prevents injection)
+ */
 class SendVerificationSMSDTO {
+    /**
+     * User identifier (UUID v4)
+     *
+     * Validation:
+     * - Must be valid UUID v4 format
+     *
+     * Sanitization:
+     * - Trimmed and lowercased
+     */
     sub;
+    /**
+     * Skip the "already verified" check
+     * Used for MFA contexts where codes are needed even if phone is verified
+     *
+     * Validation:
+     * - Must be boolean
+     * - Optional (defaults to true)
+     */
     skipAlreadyVerifiedCheck;
+    /**
+     * Challenge session ID to link this verification token to
+     * Optional - for linking verification tokens to specific challenge sessions.
+     * Provides security by preventing old tokens from being used with new sessions.
+     *
+     * Validation:
+     * - Must be a positive integer
+     * - Optional (for backward compatibility and non-challenge flows)
+     */
     challengeSessionId;
 }
 exports.SendVerificationSMSDTO = SendVerificationSMSDTO;
@@ -78,16 +170,59 @@ __decorate([
     (0, class_validator_1.Min)(1, { message: 'challengeSessionId must be a positive integer' }),
     __metadata("design:type", Number)
 ], SendVerificationSMSDTO.prototype, "challengeSessionId", void 0);
+/**
+ * Response DTO for sendVerificationSMS
+ */
 class SendVerificationSMSResponseDTO {
+    /**
+     * Verification token ID (internal integer)
+     */
     tokenId;
 }
 exports.SendVerificationSMSResponseDTO = SendVerificationSMSResponseDTO;
+/**
+ * Response DTO for verifyPhoneWithCode and verifyPhoneWithCodeBySub
+ */
 class VerifyPhoneResponseDTO {
+    /**
+     * Success message
+     */
     message;
 }
 exports.VerifyPhoneResponseDTO = VerifyPhoneResponseDTO;
+/**
+ * DTO for resending verification SMS
+ *
+ * Supports both sub and phone-based resend
+ *
+ * Security:
+ * - Either sub or phone must be provided (conditional validation)
+ * - Rate limiting applied in service layer
+ * - Input sanitization prevents abuse
+ */
 class ResendVerificationSMSDTO {
+    /**
+     * User identifier (UUID v4) - optional if phone provided
+     *
+     * Validation:
+     * - Must be valid UUID v4 format if provided
+     * - Required if phone is not provided
+     *
+     * Sanitization:
+     * - Trimmed and lowercased
+     */
     sub;
+    /**
+     * User's phone number - optional if sub provided
+     *
+     * Validation:
+     * - Must match E.164 format if provided
+     * - Max 20 characters (DB limit)
+     * - Required if sub is not provided
+     *
+     * Sanitization:
+     * - Whitespace removed
+     */
     phone;
 }
 exports.ResendVerificationSMSDTO = ResendVerificationSMSDTO;
@@ -117,7 +252,13 @@ __decorate([
     }),
     __metadata("design:type", String)
 ], ResendVerificationSMSDTO.prototype, "phone", void 0);
+/**
+ * Response DTO for resendVerificationSMS
+ */
 class ResendVerificationSMSResponseDTO {
+    /**
+     * Verification token ID (internal integer)
+     */
     tokenId;
 }
 exports.ResendVerificationSMSResponseDTO = ResendVerificationSMSResponseDTO;

package/dist/dto/verify-phone.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify-phone.dto.js","sourceRoot":"","sources":["../../src/dto/verify-phone.dto.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verify-phone.dto.js","sourceRoot":"","sources":["../../src/dto/verify-phone.dto.ts"],"names":[],"mappings":"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"}

package/dist/dto.d.ts

@@ -1,2 +1,12 @@
+/**
+ * DTO barrel export (shim)
+ *
+ * This file exists to ensure TypeScript's emitted declaration paths (e.g. `./dto.js`)
+ * resolve correctly for consumers using Node's `exports`/ESM-style resolution.
+ *
+ * Without a top-level `dto.ts` file, `export * from './dto'` may emit `./dto.js` in
+ * `dist/index.d.ts` while the build output only contains `dist/dto/index.js`, causing
+ * missing exports in downstream packages.
+ */
 export * from './dto/index';
 //# sourceMappingURL=dto.d.ts.map

package/dist/dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"AAUA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,aAAa,CAAC"}

package/dist/dto.js

@@ -14,5 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * DTO barrel export (shim)
+ *
+ * This file exists to ensure TypeScript's emitted declaration paths (e.g. `./dto.js`)
+ * resolve correctly for consumers using Node's `exports`/ESM-style resolution.
+ *
+ * Without a top-level `dto.ts` file, `export * from './dto'` may emit `./dto.js` in
+ * `dist/index.d.ts` while the build output only contains `dist/dto/index.js`, causing
+ * missing exports in downstream packages.
+ */
 __exportStar(require("./dto/index"), exports);
 //# sourceMappingURL=dto.js.map

package/dist/dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"dto.js","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAUA,8CAA4B"}
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,8CAA4B"}

package/dist/entities/auth-audit.entity.d.ts

@@ -1,31 +1,190 @@
 import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+/**
+ * Authentication Audit Event Status
+ *
+ * Classification of event outcomes for filtering and analysis.
+ */
 export type AuthAuditEventStatus = 'SUCCESS' | 'FAILURE' | 'INFO' | 'SUSPICIOUS';
+/**
+ * Base Authentication Audit Entity
+ *
+ * Core audit record with all fields and business logic.
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ *
+ * **Design Notes:**
+ * - Only stores `userId` (integer internal ID) - no `userSub` duplication
+ * - Risk tracking fields are infrastructure for future adaptive MFA (no business logic)
+ * - All audit integrations are non-blocking (errors logged, don't throw)
+ */
 export declare class BaseAuthAudit {
+    /**
+     * Internal audit record ID (auto-increment integer)
+     */
     id: number;
+    /**
+     * Internal user ID (foreign key to users table)
+     * Uses integer for optimal performance in joins and lookups.
+     * API methods accepting userSub will resolve to userId before querying.
+     *
+     * @remarks
+     * No userSub field to avoid duplication. All queries use userId
+     * for efficient database operations.
+     */
     userId: number;
+    /**
+     * Type of authentication/security event
+     */
     eventType: AuthAuditEventType;
+    /**
+     * Event classification status
+     * - SUCCESS: Operation completed successfully
+     * - FAILURE: Operation failed (login failed, verification failed, etc.)
+     * - INFO: Informational event (profile update, device added, etc.)
+     * - SUSPICIOUS: Security violation or suspicious activity detected
+     */
     eventStatus: AuthAuditEventStatus;
+    /**
+     * Risk factor score (0-100)
+     * Calculated during adaptive MFA evaluation (future implementation).
+     * null if not applicable (non-adaptive flows).
+     *
+     * @remarks
+     * This is infrastructure for future adaptive MFA. The audit service
+     * records risk data but does NOT calculate risk scores. Risk calculation
+     * and adaptive MFA business logic will be implemented in future phases.
+     */
     riskFactor?: number | null;
+    /**
+     * Risk factors that contributed to the risk score
+     * Examples: ['new_device', 'new_ip', 'new_country', 'impossible_travel']
+     *
+     * @remarks
+     * Infrastructure field for future adaptive MFA implementation.
+     */
     riskFactors?: string[] | null;
+    /**
+     * Whether adaptive MFA was triggered for this event
+     * true if MFA was conditionally required based on risk (future implementation).
+     * null if not applicable.
+     *
+     * @remarks
+     * Infrastructure field for future adaptive MFA implementation.
+     */
     adaptiveMfaTriggered?: boolean | null;
+    /**
+     * IP address where event occurred
+     */
     ipAddress?: string | null;
+    /**
+     * Country from IP geolocation (optional, for geographic risk assessment)
+     */
     ipCountry?: string | null;
+    /**
+     * City from IP geolocation (optional, for geographic risk assessment)
+     */
     ipCity?: string | null;
+    /**
+     * Latitude from IP geolocation (optional, for impossible travel detection)
+     */
     ipLatitude?: number | null;
+    /**
+     * Longitude from IP geolocation (optional, for impossible travel detection)
+     */
     ipLongitude?: number | null;
+    /**
+     * User agent string
+     */
     userAgent?: string | null;
+    /**
+     * Platform extracted from user agent
+     * Examples: "iOS", "Android", "Windows", "macOS"
+     */
     platform?: string | null;
+    /**
+     * Browser extracted from user agent
+     * Examples: "Chrome", "Safari", "Firefox"
+     */
     browser?: string | null;
+    /**
+     * Device identifier (UUID)
+     * Unique identifier for the device/browser
+     */
     deviceId?: string | null;
+    /**
+     * User-friendly device name
+     * Examples: "iPhone 15 Pro", "Chrome on MacBook"
+     */
     deviceName?: string | null;
+    /**
+     * Device type
+     * Examples: "mobile", "desktop", "tablet"
+     */
     deviceType?: string | null;
+    /**
+     * Session ID (if event is related to a session)
+     * Foreign key to sessions table
+     */
     sessionId?: number | null;
+    /**
+     * Challenge session ID (if event is related to a challenge)
+     * Foreign key to challenge_sessions table
+     */
     challengeSessionId?: number | null;
+    /**
+     * Authentication method used
+     * Examples: "password", "google", "apple", "facebook"
+     * Used for social login provider tracking
+     */
     authMethod?: string | null;
+    /**
+     * Who performed this action (for admin/CLI/automated operations)
+     * - Admin user ID or email for manual admin actions
+     * - CLI identifier for command-line operations
+     * - 'system' for automated actions
+     * - null for user-initiated actions
+     *
+     * @example
+     * performedBy: 'admin@example.com'
+     * performedBy: 'cli-migration-2025'
+     * performedBy: 'system'
+     */
     performedBy?: string | null;
+    /**
+     * Reason for the event (optional)
+     * Used for security events, account locks, etc.
+     */
     reason?: string | null;
+    /**
+     * Detailed description of the event
+     */
     description?: string | null;
+    /**
+     * Rich metadata (JSON)
+     * Event-specific data stored without requiring schema changes.
+     *
+     * @example
+     * ```typescript
+     * // Social login
+     * metadata: { provider: 'google', isNewUser: true }
+     *
+     * // Challenge event
+     * metadata: { challengeName: 'VERIFY_EMAIL', challengeSessionId: 123 }
+     *
+     * // MFA device
+     * metadata: { deviceType: 'totp', deviceName: 'iPhone Authenticator' }
+     *
+     * // Token reuse
+     * metadata: { tokenFamily: 'abc123', action: 'token_family_revoked' }
+     * ```
+     */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Timestamp when event occurred
+     */
     createdAt: Date;
 }
 //# sourceMappingURL=auth-audit.entity.d.ts.map

package/dist/entities/auth-audit.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-audit.entity.d.ts","sourceRoot":"","sources":["../../src/entities/auth-audit.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAOzE,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAiBjF,qBAAa,aAAa;IAIxB,EAAE,EAAG,MAAM,CAAC;IAWZ,MAAM,EAAG,MAAM,CAAC;IAKhB,SAAS,EAAG,kBAAkB,CAAC;IAS/B,WAAW,EAAG,oBAAoB,CAAC;IAgBnC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAS3B,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAU9B,oBAAoB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAStC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAK1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAK1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAKvB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAK3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAK5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAU3B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAOnC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAc3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAU5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAKvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAqB5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAK1C,SAAS,EAAG,IAAI,CAAC;CAClB"}
+{"version":3,"file":"auth-audit.entity.d.ts","sourceRoot":"","sources":["../../src/entities/auth-audit.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;IACxB;;OAEG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;;;;;;OAQG;IACH,MAAM,EAAG,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAG,kBAAkB,CAAC;IAE/B;;;;;;OAMG;IACH,WAAW,EAAG,oBAAoB,CAAC;IAMnC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAE9B;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAMtC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;CAClB"}