@nauth-toolkit/core 0.1.13 → 0.1.17

package/dist/entities/user.entity.d.ts

@@ -1,41 +1,207 @@
+/**
+ * Base User Entity
+ *
+ * Core user authentication 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.
+ */
 export declare class BaseUser {
+    /**
+     * Internal database ID (auto-increment integer)
+     * Used for foreign key relationships and internal queries
+     * NOT exposed externally
+     */
     id: number;
+    /**
+     * External user identifier (UUID)
+     * Exposed in API responses and JWT tokens as 'sub' (subject)
+     * This is what consuming applications should use
+     */
     sub: string;
+    /**
+     * User's username (optional, unique if set)
+     */
     username: string | null;
+    /**
+     * User's first name
+     */
     firstName: string | null;
+    /**
+     * User's last name
+     */
     lastName: string | null;
+    /**
+     * User's email address (required, unique)
+     */
     email: string;
+    /**
+     * User's phone number in E.164 format (optional)
+     */
     phone: string | null;
+    /**
+     * Hashed password (Argon2)
+     * NULL for social-only accounts
+     */
     passwordHash: string | null;
+    /**
+     * When password was last changed
+     * Used for password expiry policies
+     */
     passwordChangedAt: Date | null;
+    /**
+     * Password history (hashed)
+     * Used to prevent password reuse
+     */
     passwordHistory: string[] | null;
+    /**
+     * Flag to force password change on next login
+     * When true, user must complete FORCE_CHANGE_PASSWORD challenge
+     * Can be set by admin or by password expiration policy
+     */
     mustChangePassword: boolean;
+    /**
+     * Email verification status
+     */
     isEmailVerified: boolean;
+    /**
+     * Phone verification status
+     */
     isPhoneVerified: boolean;
+    /**
+     * Account active status
+     * Inactive accounts cannot login
+     */
     isActive: boolean;
+    /**
+     * Account lock status
+     * Locked accounts cannot login until unlocked
+     */
     isLocked: boolean;
+    /**
+     * Reason for account lock
+     */
     lockReason: string | null;
+    /**
+     * When account was locked
+     */
     lockedAt: Date | null;
+    /**
+     * When account lock expires (NULL = permanent)
+     */
     lockedUntil: Date | null;
+    /**
+     * Number of consecutive failed login attempts
+     */
     failedLoginAttempts: number;
+    /**
+     * When last failed login occurred
+     */
     lastFailedLoginAt: Date | null;
+    /**
+     * When user last successfully logged in
+     */
     lastLoginAt: Date | null;
+    /**
+     * IP address of last successful login
+     */
     lastLoginIp: string | null;
+    /**
+     * MFA enabled status
+     */
     mfaEnabled: boolean;
+    /**
+     * List of enabled MFA methods
+     * Examples: ['totp', 'sms', 'passkey']
+     */
     mfaMethods: string[] | null;
+    /**
+     * When MFA was enforced for this user
+     */
     mfaEnforcedAt?: Date | null;
+    /**
+     * TOTP secret (encrypted)
+     * DEPRECATED: Use MFADevice entity instead
+     */
     totpSecret?: string | null;
+    /**
+     * Backup recovery codes (hashed)
+     * Single-use codes for account recovery
+     */
     backupCodes: string[] | null;
+    /**
+     * User's preferred MFA method
+     * Used to pre-select MFA method during authentication
+     */
     preferredMfaMethod: string | null;
+    /**
+     * MFA exemption status
+     *
+     * When true, user is exempt from MFA requirements (both setup and verification).
+     * This is an admin-only field and should only be set through admin functions.
+     *
+     * SECURITY: Exemption only affects MFA - other security measures (account lock,
+     * email verification, password change) still apply normally.
+     *
+     * @default false
+     */
     mfaExempt?: boolean;
+    /**
+     * Reason for MFA exemption (optional, for audit trail)
+     *
+     * Admin should provide reason when granting exemption (e.g., "Internal service account",
+     * "Legacy system integration", "Special access approval")
+     *
+     * @default null
+     */
     mfaExemptReason?: string | null;
+    /**
+     * When MFA exemption was granted
+     *
+     * Used for audit trail and potentially for expiration logic in future.
+     *
+     * @default null
+     */
     mfaExemptGrantedAt?: Date | null;
+    /**
+     * Who granted the MFA exemption (optional, admin identifier)
+     *
+     * For audit trail - store admin user ID or identifier who granted exemption.
+     *
+     * @default null
+     */
     mfaExemptGrantedBy?: string | null;
+    /**
+     * Optimization flag: indicates if user has any social authentication methods
+     * Prevents unnecessary joins for password-only users (80%+ of users)
+     * Updated automatically when social accounts are linked/unlinked
+     */
     hasSocialAuth: boolean;
+    /**
+     * Array of social providers linked to this account
+     * Examples: ['google', 'apple', 'facebook']
+     * Updated automatically when social accounts are linked/unlinked
+     */
     socialProviders: string[] | null;
+    /**
+     * Additional user metadata (JSON)
+     * For custom application-specific data
+     */
     metadata: Record<string, unknown> | null;
+    /**
+     * Account creation timestamp
+     */
     createdAt: Date;
+    /**
+     * Last account update timestamp
+     */
     updatedAt: Date;
+    /**
+     * Soft delete timestamp
+     * NULL if account is not deleted
+     */
     deletedAt: Date | null;
 }
 //# sourceMappingURL=user.entity.d.ts.map

package/dist/entities/user.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.entity.d.ts","sourceRoot":"","sources":["../../src/entities/user.entity.ts"],"names":[],"mappings":"AAUA,qBAAa,QAAQ;IAMnB,EAAE,EAAG,MAAM,CAAC;IAOZ,GAAG,EAAG,MAAM,CAAC;IAKb,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAKzB,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAK1B,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAKzB,KAAK,EAAG,MAAM,CAAC;IAKf,KAAK,EAAG,MAAM,GAAG,IAAI,CAAC;IAMtB,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAM7B,iBAAiB,EAAG,IAAI,GAAG,IAAI,CAAC;IAMhC,eAAe,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAOlC,kBAAkB,EAAG,OAAO,CAAC;IAK7B,eAAe,EAAG,OAAO,CAAC;IAK1B,eAAe,EAAG,OAAO,CAAC;IAM1B,QAAQ,EAAG,OAAO,CAAC;IAMnB,QAAQ,EAAG,OAAO,CAAC;IAKnB,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAK3B,QAAQ,EAAG,IAAI,GAAG,IAAI,CAAC;IAKvB,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;IAK1B,mBAAmB,EAAG,MAAM,CAAC;IAK7B,iBAAiB,EAAG,IAAI,GAAG,IAAI,CAAC;IAKhC,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;IAK1B,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAK5B,UAAU,EAAG,OAAO,CAAC;IAMrB,UAAU,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAK7B,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAM5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B,WAAW,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAM9B,kBAAkB,EAAG,MAAM,GAAG,IAAI,CAAC;IAanC,SAAS,CAAC,EAAE,OAAO,CAAC;IAUpB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAShC,kBAAkB,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IASjC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAOnC,aAAa,EAAG,OAAO,CAAC;IAOxB,eAAe,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAMlC,QAAQ,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAK1C,SAAS,EAAG,IAAI,CAAC;IAKjB,SAAS,EAAG,IAAI,CAAC;IAMjB,SAAS,EAAG,IAAI,GAAG,IAAI,CAAC;CACzB"}
+{"version":3,"file":"user.entity.d.ts","sourceRoot":"","sources":["../../src/entities/user.entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IACnB;;;;OAIG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;;OAIG;IACH,GAAG,EAAG,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,QAAQ,EAAG,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,KAAK,EAAG,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,EAAG,MAAM,GAAG,IAAI,CAAC;IAEtB;;;OAGG;IACH,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAE7B;;;OAGG;IACH,iBAAiB,EAAG,IAAI,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,eAAe,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAElC;;;;OAIG;IACH,kBAAkB,EAAG,OAAO,CAAC;IAE7B;;OAEG;IACH,eAAe,EAAG,OAAO,CAAC;IAE1B;;OAEG;IACH,eAAe,EAAG,OAAO,CAAC;IAE1B;;;OAGG;IACH,QAAQ,EAAG,OAAO,CAAC;IAEnB;;;OAGG;IACH,QAAQ,EAAG,OAAO,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAG,MAAM,GAAG,IAAI,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAG,IAAI,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,mBAAmB,EAAG,MAAM,CAAC;IAE7B;;OAEG;IACH,iBAAiB,EAAG,IAAI,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAE5B;;OAEG;IACH,UAAU,EAAG,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;OAGG;IACH,WAAW,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,kBAAkB,EAAG,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEjC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;OAIG;IACH,aAAa,EAAG,OAAO,CAAC;IAExB;;;;OAIG;IACH,eAAe,EAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAElC;;;OAGG;IACH,QAAQ,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;;OAGG;IACH,SAAS,EAAG,IAAI,GAAG,IAAI,CAAC;CACzB"}

package/dist/entities/user.entity.js

@@ -1,44 +1,210 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseUser = void 0;
+/**
+ * Base User Entity
+ *
+ * Core user authentication 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.
+ */
 class BaseUser {
+    /**
+     * Internal database ID (auto-increment integer)
+     * Used for foreign key relationships and internal queries
+     * NOT exposed externally
+     */
     id;
+    /**
+     * External user identifier (UUID)
+     * Exposed in API responses and JWT tokens as 'sub' (subject)
+     * This is what consuming applications should use
+     */
     sub;
+    /**
+     * User's username (optional, unique if set)
+     */
     username;
+    /**
+     * User's first name
+     */
     firstName;
+    /**
+     * User's last name
+     */
     lastName;
+    /**
+     * User's email address (required, unique)
+     */
     email;
+    /**
+     * User's phone number in E.164 format (optional)
+     */
     phone;
+    /**
+     * Hashed password (Argon2)
+     * NULL for social-only accounts
+     */
     passwordHash;
+    /**
+     * When password was last changed
+     * Used for password expiry policies
+     */
     passwordChangedAt;
+    /**
+     * Password history (hashed)
+     * Used to prevent password reuse
+     */
     passwordHistory;
+    /**
+     * Flag to force password change on next login
+     * When true, user must complete FORCE_CHANGE_PASSWORD challenge
+     * Can be set by admin or by password expiration policy
+     */
     mustChangePassword;
+    /**
+     * Email verification status
+     */
     isEmailVerified;
+    /**
+     * Phone verification status
+     */
     isPhoneVerified;
+    /**
+     * Account active status
+     * Inactive accounts cannot login
+     */
     isActive;
+    /**
+     * Account lock status
+     * Locked accounts cannot login until unlocked
+     */
     isLocked;
+    /**
+     * Reason for account lock
+     */
     lockReason;
+    /**
+     * When account was locked
+     */
     lockedAt;
+    /**
+     * When account lock expires (NULL = permanent)
+     */
     lockedUntil;
+    /**
+     * Number of consecutive failed login attempts
+     */
     failedLoginAttempts;
+    /**
+     * When last failed login occurred
+     */
     lastFailedLoginAt;
+    /**
+     * When user last successfully logged in
+     */
     lastLoginAt;
+    /**
+     * IP address of last successful login
+     */
     lastLoginIp;
+    /**
+     * MFA enabled status
+     */
     mfaEnabled;
+    /**
+     * List of enabled MFA methods
+     * Examples: ['totp', 'sms', 'passkey']
+     */
     mfaMethods;
+    /**
+     * When MFA was enforced for this user
+     */
     mfaEnforcedAt;
+    /**
+     * TOTP secret (encrypted)
+     * DEPRECATED: Use MFADevice entity instead
+     */
     totpSecret;
+    /**
+     * Backup recovery codes (hashed)
+     * Single-use codes for account recovery
+     */
     backupCodes;
+    /**
+     * User's preferred MFA method
+     * Used to pre-select MFA method during authentication
+     */
     preferredMfaMethod;
+    /**
+     * MFA exemption status
+     *
+     * When true, user is exempt from MFA requirements (both setup and verification).
+     * This is an admin-only field and should only be set through admin functions.
+     *
+     * SECURITY: Exemption only affects MFA - other security measures (account lock,
+     * email verification, password change) still apply normally.
+     *
+     * @default false
+     */
     mfaExempt;
+    /**
+     * Reason for MFA exemption (optional, for audit trail)
+     *
+     * Admin should provide reason when granting exemption (e.g., "Internal service account",
+     * "Legacy system integration", "Special access approval")
+     *
+     * @default null
+     */
     mfaExemptReason;
+    /**
+     * When MFA exemption was granted
+     *
+     * Used for audit trail and potentially for expiration logic in future.
+     *
+     * @default null
+     */
     mfaExemptGrantedAt;
+    /**
+     * Who granted the MFA exemption (optional, admin identifier)
+     *
+     * For audit trail - store admin user ID or identifier who granted exemption.
+     *
+     * @default null
+     */
     mfaExemptGrantedBy;
+    /**
+     * Optimization flag: indicates if user has any social authentication methods
+     * Prevents unnecessary joins for password-only users (80%+ of users)
+     * Updated automatically when social accounts are linked/unlinked
+     */
     hasSocialAuth;
+    /**
+     * Array of social providers linked to this account
+     * Examples: ['google', 'apple', 'facebook']
+     * Updated automatically when social accounts are linked/unlinked
+     */
     socialProviders;
+    /**
+     * Additional user metadata (JSON)
+     * For custom application-specific data
+     */
     metadata;
+    /**
+     * Account creation timestamp
+     */
     createdAt;
+    /**
+     * Last account update timestamp
+     */
     updatedAt;
+    /**
+     * Soft delete timestamp
+     * NULL if account is not deleted
+     */
     deletedAt;
 }
 exports.BaseUser = BaseUser;

package/dist/entities/user.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"user.entity.js","sourceRoot":"","sources":["../../src/entities/user.entity.ts"],"names":[],"mappings":";;;AAUA,MAAa,QAAQ;IAMnB,EAAE,CAAU;IAOZ,GAAG,CAAU;IAKb,QAAQ,CAAiB;IAKzB,SAAS,CAAiB;IAK1B,QAAQ,CAAiB;IAKzB,KAAK,CAAU;IAKf,KAAK,CAAiB;IAMtB,YAAY,CAAiB;IAM7B,iBAAiB,CAAe;IAMhC,eAAe,CAAmB;IAOlC,kBAAkB,CAAW;IAK7B,eAAe,CAAW;IAK1B,eAAe,CAAW;IAM1B,QAAQ,CAAW;IAMnB,QAAQ,CAAW;IAKnB,UAAU,CAAiB;IAK3B,QAAQ,CAAe;IAKvB,WAAW,CAAe;IAK1B,mBAAmB,CAAU;IAK7B,iBAAiB,CAAe;IAKhC,WAAW,CAAe;IAK1B,WAAW,CAAiB;IAK5B,UAAU,CAAW;IAMrB,UAAU,CAAmB;IAK7B,aAAa,CAAe;IAM5B,UAAU,CAAiB;IAM3B,WAAW,CAAmB;IAM9B,kBAAkB,CAAiB;IAanC,SAAS,CAAW;IAUpB,eAAe,CAAiB;IAShC,kBAAkB,CAAe;IASjC,kBAAkB,CAAiB;IAOnC,aAAa,CAAW;IAOxB,eAAe,CAAmB;IAMlC,QAAQ,CAAkC;IAK1C,SAAS,CAAQ;IAKjB,SAAS,CAAQ;IAMjB,SAAS,CAAe;CACzB;AAxOD,4BAwOC"}
+{"version":3,"file":"user.entity.js","sourceRoot":"","sources":["../../src/entities/user.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,QAAQ;IACnB;;;;OAIG;IACH,EAAE,CAAU;IAEZ;;;;OAIG;IACH,GAAG,CAAU;IAEb;;OAEG;IACH,QAAQ,CAAiB;IAEzB;;OAEG;IACH,SAAS,CAAiB;IAE1B;;OAEG;IACH,QAAQ,CAAiB;IAEzB;;OAEG;IACH,KAAK,CAAU;IAEf;;OAEG;IACH,KAAK,CAAiB;IAEtB;;;OAGG;IACH,YAAY,CAAiB;IAE7B;;;OAGG;IACH,iBAAiB,CAAe;IAEhC;;;OAGG;IACH,eAAe,CAAmB;IAElC;;;;OAIG;IACH,kBAAkB,CAAW;IAE7B;;OAEG;IACH,eAAe,CAAW;IAE1B;;OAEG;IACH,eAAe,CAAW;IAE1B;;;OAGG;IACH,QAAQ,CAAW;IAEnB;;;OAGG;IACH,QAAQ,CAAW;IAEnB;;OAEG;IACH,UAAU,CAAiB;IAE3B;;OAEG;IACH,QAAQ,CAAe;IAEvB;;OAEG;IACH,WAAW,CAAe;IAE1B;;OAEG;IACH,mBAAmB,CAAU;IAE7B;;OAEG;IACH,iBAAiB,CAAe;IAEhC;;OAEG;IACH,WAAW,CAAe;IAE1B;;OAEG;IACH,WAAW,CAAiB;IAE5B;;OAEG;IACH,UAAU,CAAW;IAErB;;;OAGG;IACH,UAAU,CAAmB;IAE7B;;OAEG;IACH,aAAa,CAAe;IAE5B;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,WAAW,CAAmB;IAE9B;;;OAGG;IACH,kBAAkB,CAAiB;IAEnC;;;;;;;;;;OAUG;IACH,SAAS,CAAW;IAEpB;;;;;;;OAOG;IACH,eAAe,CAAiB;IAEhC;;;;;;OAMG;IACH,kBAAkB,CAAe;IAEjC;;;;;;OAMG;IACH,kBAAkB,CAAiB;IAEnC;;;;OAIG;IACH,aAAa,CAAW;IAExB;;;;OAIG;IACH,eAAe,CAAmB;IAElC;;;OAGG;IACH,QAAQ,CAAkC;IAE1C;;OAEG;IACH,SAAS,CAAQ;IAEjB;;OAEG;IACH,SAAS,CAAQ;IAEjB;;;OAGG;IACH,SAAS,CAAe;CACzB;AAxOD,4BAwOC"}

package/dist/entities/verification-token.entity.d.ts

@@ -1,19 +1,121 @@
+/**
+ * Base Verification Token Entity
+ *
+ * Stores email/phone verification codes and password reset tokens.
+ * Supports multiple verification types with expiry and attempt tracking.
+ * 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.
+ */
 export declare class BaseVerificationToken {
+    /**
+     * Internal verification token ID (auto-increment integer)
+     */
     id: number;
+    /**
+     * Internal user ID (foreign key to users table)
+     * Uses integer for optimal performance
+     */
     userId: number;
+    /**
+     * Challenge session ID (foreign key to challenge sessions table)
+     * Links verification token to specific challenge session for security.
+     * Prevents old tokens from being used with new challenge sessions.
+     * NULL for password reset tokens (not tied to challenges)
+     */
     challengeSessionId?: number | null;
+    /**
+     * Token type
+     * - 'email': Email verification
+     * - 'phone': Phone verification
+     * - 'password_reset': Password reset
+     */
     type: 'email' | 'phone' | 'password_reset';
+    /**
+     * Verification token (hashed for security)
+     * Used for magic links and password reset
+     */
     token: string;
+    /**
+     * Verification code (for email/SMS OTP)
+     * Usually 6 digits, stored as string for flexibility
+     */
     code?: string | null;
+    /**
+     * Token expiration timestamp
+     * After this time, token/code is invalid
+     */
     expiresAt: Date;
+    /**
+     * Number of failed verification attempts
+     * Used to prevent brute force attacks
+     */
     attempts: number;
+    /**
+     * When token was successfully used
+     * NULL if not yet used
+     */
     usedAt?: Date | null;
+    /**
+     * IP address when token was created
+     * For security auditing
+     */
     ipAddress?: string | null;
+    /**
+     * User agent when token was created
+     * For security auditing
+     */
     userAgent?: string | null;
+    /**
+     * Additional metadata (JSON)
+     * For storing additional verification-specific data
+     */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Creation timestamp
+     */
     createdAt: Date;
+    /**
+     * Check if token is expired
+     *
+     * @returns true if token is expired
+     *
+     * @example
+     * ```typescript
+     * if (token.isExpired()) {
+     *   throw new Error('Verification code has expired');
+     * }
+     * ```
+     */
     isExpired(): boolean;
+    /**
+     * Check if token has been used
+     *
+     * @returns true if token has been used
+     *
+     * @example
+     * ```typescript
+     * if (token.isUsed()) {
+     *   throw new Error('Verification code has already been used');
+     * }
+     * ```
+     */
     isUsed(): boolean;
+    /**
+     * Check if max attempts exceeded
+     *
+     * @param maxAttempts - Maximum allowed attempts
+     * @returns true if max attempts exceeded
+     *
+     * @example
+     * ```typescript
+     * if (token.maxAttemptsExceeded(3)) {
+     *   throw new Error('Too many failed attempts');
+     * }
+     * ```
+     */
     maxAttemptsExceeded(maxAttempts: number): boolean;
 }
 //# sourceMappingURL=verification-token.entity.d.ts.map

package/dist/entities/verification-token.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verification-token.entity.d.ts","sourceRoot":"","sources":["../../src/entities/verification-token.entity.ts"],"names":[],"mappings":"AAWA,qBAAa,qBAAqB;IAIhC,EAAE,EAAG,MAAM,CAAC;IAMZ,MAAM,EAAG,MAAM,CAAC;IAQhB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAQnC,IAAI,EAAG,OAAO,GAAG,OAAO,GAAG,gBAAgB,CAAC;IAM5C,KAAK,EAAG,MAAM,CAAC;IAMf,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMrB,SAAS,EAAG,IAAI,CAAC;IAMjB,QAAQ,EAAG,MAAM,CAAC;IAMlB,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAMrB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAK1C,SAAS,EAAG,IAAI,CAAC;IAcjB,SAAS,IAAI,OAAO;IAgBpB,MAAM,IAAI,OAAO;IAiBjB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAGlD"}
+{"version":3,"file":"verification-token.entity.d.ts","sourceRoot":"","sources":["../../src/entities/verification-token.entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IAChC;;OAEG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;OAGG;IACH,MAAM,EAAG,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,IAAI,EAAG,OAAO,GAAG,OAAO,GAAG,gBAAgB,CAAC;IAE5C;;;OAGG;IACH,KAAK,EAAG,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;;OAGG;IACH,QAAQ,EAAG,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;;;;;;;;;;OAWG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;;;;;;OAWG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAGlD"}

package/dist/entities/verification-token.entity.js

@@ -1,26 +1,128 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseVerificationToken = void 0;
+/**
+ * Base Verification Token Entity
+ *
+ * Stores email/phone verification codes and password reset tokens.
+ * Supports multiple verification types with expiry and attempt tracking.
+ * 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.
+ */
 class BaseVerificationToken {
+    /**
+     * Internal verification token ID (auto-increment integer)
+     */
     id;
+    /**
+     * Internal user ID (foreign key to users table)
+     * Uses integer for optimal performance
+     */
     userId;
+    /**
+     * Challenge session ID (foreign key to challenge sessions table)
+     * Links verification token to specific challenge session for security.
+     * Prevents old tokens from being used with new challenge sessions.
+     * NULL for password reset tokens (not tied to challenges)
+     */
     challengeSessionId;
+    /**
+     * Token type
+     * - 'email': Email verification
+     * - 'phone': Phone verification
+     * - 'password_reset': Password reset
+     */
     type;
+    /**
+     * Verification token (hashed for security)
+     * Used for magic links and password reset
+     */
     token;
+    /**
+     * Verification code (for email/SMS OTP)
+     * Usually 6 digits, stored as string for flexibility
+     */
     code;
+    /**
+     * Token expiration timestamp
+     * After this time, token/code is invalid
+     */
     expiresAt;
+    /**
+     * Number of failed verification attempts
+     * Used to prevent brute force attacks
+     */
     attempts;
+    /**
+     * When token was successfully used
+     * NULL if not yet used
+     */
     usedAt;
+    /**
+     * IP address when token was created
+     * For security auditing
+     */
     ipAddress;
+    /**
+     * User agent when token was created
+     * For security auditing
+     */
     userAgent;
+    /**
+     * Additional metadata (JSON)
+     * For storing additional verification-specific data
+     */
     metadata;
+    /**
+     * Creation timestamp
+     */
     createdAt;
+    /**
+     * Check if token is expired
+     *
+     * @returns true if token is expired
+     *
+     * @example
+     * ```typescript
+     * if (token.isExpired()) {
+     *   throw new Error('Verification code has expired');
+     * }
+     * ```
+     */
     isExpired() {
         return new Date() > this.expiresAt;
     }
+    /**
+     * Check if token has been used
+     *
+     * @returns true if token has been used
+     *
+     * @example
+     * ```typescript
+     * if (token.isUsed()) {
+     *   throw new Error('Verification code has already been used');
+     * }
+     * ```
+     */
     isUsed() {
         return this.usedAt !== null && this.usedAt !== undefined;
     }
+    /**
+     * Check if max attempts exceeded
+     *
+     * @param maxAttempts - Maximum allowed attempts
+     * @returns true if max attempts exceeded
+     *
+     * @example
+     * ```typescript
+     * if (token.maxAttemptsExceeded(3)) {
+     *   throw new Error('Too many failed attempts');
+     * }
+     * ```
+     */
     maxAttemptsExceeded(maxAttempts) {
         return this.attempts >= maxAttempts;
     }

package/dist/entities/verification-token.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"verification-token.entity.js","sourceRoot":"","sources":["../../src/entities/verification-token.entity.ts"],"names":[],"mappings":";;;AAWA,MAAa,qBAAqB;IAIhC,EAAE,CAAU;IAMZ,MAAM,CAAU;IAQhB,kBAAkB,CAAiB;IAQnC,IAAI,CAAwC;IAM5C,KAAK,CAAU;IAMf,IAAI,CAAiB;IAMrB,SAAS,CAAQ;IAMjB,QAAQ,CAAU;IAMlB,MAAM,CAAe;IAMrB,SAAS,CAAiB;IAM1B,SAAS,CAAiB;IAM1B,QAAQ,CAAkC;IAK1C,SAAS,CAAQ;IAcjB,SAAS;QACP,OAAO,IAAI,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;IACrC,CAAC;IAcD,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;IAC3D,CAAC;IAeD,mBAAmB,CAAC,WAAmB;QACrC,OAAO,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;IACtC,CAAC;CACF;AAjID,sDAiIC"}
+{"version":3,"file":"verification-token.entity.js","sourceRoot":"","sources":["../../src/entities/verification-token.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,MAAa,qBAAqB;IAChC;;OAEG;IACH,EAAE,CAAU;IAEZ;;;OAGG;IACH,MAAM,CAAU;IAEhB;;;;;OAKG;IACH,kBAAkB,CAAiB;IAEnC;;;;;OAKG;IACH,IAAI,CAAwC;IAE5C;;;OAGG;IACH,KAAK,CAAU;IAEf;;;OAGG;IACH,IAAI,CAAiB;IAErB;;;OAGG;IACH,SAAS,CAAQ;IAEjB;;;OAGG;IACH,QAAQ,CAAU;IAElB;;;OAGG;IACH,MAAM,CAAe;IAErB;;;OAGG;IACH,SAAS,CAAiB;IAE1B;;;OAGG;IACH,SAAS,CAAiB;IAE1B;;;OAGG;IACH,QAAQ,CAAkC;IAE1C;;OAEG;IACH,SAAS,CAAQ;IAEjB;;;;;;;;;;;OAWG;IACH,SAAS;QACP,OAAO,IAAI,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;IAC3D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,WAAmB;QACrC,OAAO,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;IACtC,CAAC;CACF;AAjID,sDAiIC"}