@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/entities/session.entity.js

@@ -1,35 +1,156 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseSession = void 0;
+/**
+ * Base Session Entity
+ *
+ * JWT session tracking with device information and security features.
+ * 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 BaseSession {
+    /**
+     * Internal session ID (auto-increment integer)
+     */
     id;
+    /**
+     * Version for optimistic locking
+     * Automatically incremented on each update by the ORM
+     * Used to detect race conditions and concurrent modifications
+     *
+     * SECURITY CRITICAL: Prevents TOCTOU vulnerabilities
+     */
     version;
+    /**
+     * Internal user ID (foreign key to users table)
+     * Uses integer for optimal performance in joins and lookups
+     */
     userId;
+    /**
+     * Access token hash (SHA-256)
+     * Used for token revocation and session tracking
+     */
     accessTokenHash;
+    /**
+     * Refresh token hash (SHA-256)
+     * Used for token rotation and reuse detection
+     */
     refreshTokenHash;
+    /**
+     * Token family identifier
+     * Used for refresh token rotation and reuse detection
+     */
     tokenFamily;
+    /**
+     * Device identifier (UUID)
+     * Unique identifier for the device/browser
+     */
     deviceId;
+    /**
+     * User-friendly device name
+     * Examples: "iPhone 15 Pro", "Chrome on MacBook"
+     */
     deviceName;
+    /**
+     * Device type
+     * Examples: "mobile", "desktop", "tablet"
+     */
     deviceType;
+    /**
+     * Device fingerprint hash
+     * Combination of device characteristics for additional security
+     */
     deviceFingerprint;
+    /**
+     * IP address when session was created
+     */
     ipAddress;
+    /**
+     * Country from IP geolocation (optional)
+     */
     ipCountry;
+    /**
+     * City from IP geolocation (optional)
+     */
     ipCity;
+    /**
+     * Latitude from IP geolocation (optional)
+     * Used for impossible travel detection
+     */
     ipLatitude;
+    /**
+     * Longitude from IP geolocation (optional)
+     * Used for impossible travel detection
+     */
     ipLongitude;
+    /**
+     * ISP from IP geolocation (optional)
+     */
     ipIsp;
+    /**
+     * User agent string
+     */
     userAgent;
+    /**
+     * Platform extracted from user agent
+     * Examples: "iOS", "Android", "Windows", "macOS"
+     */
     platform;
+    /**
+     * Browser extracted from user agent
+     * Examples: "Chrome", "Safari", "Firefox"
+     */
     browser;
+    /**
+     * Authentication method used to create this session
+     * Examples: "password", "google", "facebook", "github", "apple"
+     * null for legacy sessions
+     */
     authMethod;
+    /**
+     * "Remember me" flag
+     * Longer expiration for remembered sessions
+     */
     isRemembered;
+    /**
+     * Trusted device flag
+     * Trusted devices may skip MFA
+     */
     isTrustedDevice;
+    /**
+     * Session expiration timestamp
+     * After this time, session is invalid
+     */
     expiresAt;
+    /**
+     * Last activity timestamp
+     * Updated on each API request
+     */
     lastActivityAt;
+    /**
+     * Session revocation status
+     * Revoked sessions cannot be used
+     */
     isRevoked;
+    /**
+     * When session was revoked
+     */
     revokedAt;
+    /**
+     * Reason for session revocation
+     * Examples: "user_logout", "token_reuse_detected", "admin_revoked"
+     */
     revokeReason;
+    /**
+     * Additional session metadata (JSON)
+     */
     metadata;
+    /**
+     * Session creation timestamp
+     */
     createdAt;
 }
 exports.BaseSession = BaseSession;

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

@@ -1 +1 @@
-{"version":3,"file":"session.entity.js","sourceRoot":"","sources":["../../src/entities/session.entity.ts"],"names":[],"mappings":";;;AAUA,MAAa,WAAW;IAItB,EAAE,CAAU;IASZ,OAAO,CAAU;IAMjB,MAAM,CAAU;IAMhB,eAAe,CAAU;IAMzB,gBAAgB,CAAU;IAM1B,WAAW,CAAiB;IAM5B,QAAQ,CAAiB;IAMzB,UAAU,CAAiB;IAM3B,UAAU,CAAiB;IAM3B,iBAAiB,CAAiB;IAKlC,SAAS,CAAiB;IAK1B,SAAS,CAAiB;IAK1B,MAAM,CAAiB;IAMvB,UAAU,CAAiB;IAM3B,WAAW,CAAiB;IAK5B,KAAK,CAAiB;IAKtB,SAAS,CAAiB;IAM1B,QAAQ,CAAiB;IAMzB,OAAO,CAAiB;IAOxB,UAAU,CAAiB;IAM3B,YAAY,CAAW;IAMvB,eAAe,CAAW;IAM1B,SAAS,CAAQ;IAMjB,cAAc,CAAe;IAM7B,SAAS,CAAW;IAKpB,SAAS,CAAe;IAMxB,YAAY,CAAiB;IAK7B,QAAQ,CAAkC;IAK1C,SAAS,CAAQ;CAClB;AAzKD,kCAyKC"}
+{"version":3,"file":"session.entity.js","sourceRoot":"","sources":["../../src/entities/session.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,WAAW;IACtB;;OAEG;IACH,EAAE,CAAU;IAEZ;;;;;;OAMG;IACH,OAAO,CAAU;IAEjB;;;OAGG;IACH,MAAM,CAAU;IAEhB;;;OAGG;IACH,eAAe,CAAU;IAEzB;;;OAGG;IACH,gBAAgB,CAAU;IAE1B;;;OAGG;IACH,WAAW,CAAiB;IAE5B;;;OAGG;IACH,QAAQ,CAAiB;IAEzB;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,iBAAiB,CAAiB;IAElC;;OAEG;IACH,SAAS,CAAiB;IAE1B;;OAEG;IACH,SAAS,CAAiB;IAE1B;;OAEG;IACH,MAAM,CAAiB;IAEvB;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,WAAW,CAAiB;IAE5B;;OAEG;IACH,KAAK,CAAiB;IAEtB;;OAEG;IACH,SAAS,CAAiB;IAE1B;;;OAGG;IACH,QAAQ,CAAiB;IAEzB;;;OAGG;IACH,OAAO,CAAiB;IAExB;;;;OAIG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,YAAY,CAAW;IAEvB;;;OAGG;IACH,eAAe,CAAW;IAE1B;;;OAGG;IACH,SAAS,CAAQ;IAEjB;;;OAGG;IACH,cAAc,CAAe;IAE7B;;;OAGG;IACH,SAAS,CAAW;IAEpB;;OAEG;IACH,SAAS,CAAe;IAExB;;;OAGG;IACH,YAAY,CAAiB;IAE7B;;OAEG;IACH,QAAQ,CAAkC;IAE1C;;OAEG;IACH,SAAS,CAAQ;CAClB;AAzKD,kCAyKC"}

package/dist/entities/social-account.entity.d.ts

@@ -1,13 +1,88 @@
+/**
+ * Base Social Account Entity
+ *
+ * Stores OAuth provider linkage (no token storage, one-time attribute import).
+ * Each record represents a user's account linked to a specific social provider.
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // User has Google and Apple accounts linked
+ * const socialAccounts = [
+ *   { provider: 'google', providerId: 'google_123', providerEmail: 'user@gmail.com' },
+ *   { provider: 'apple', providerId: 'apple_456', providerEmail: 'user@icloud.com' }
+ * ];
+ * ```
+ */
 export declare class BaseSocialAccount {
+    /**
+     * Internal database ID (auto-increment integer)
+     * Used for foreign key relationships and internal queries
+     * NOT exposed externally
+     */
     id: number;
+    /**
+     * Foreign key to users table
+     * References the user who owns this social account
+     */
     userId: number;
+    /**
+     * Social provider name
+     * Examples: 'google', 'apple', 'facebook'
+     */
     provider: string;
+    /**
+     * Provider's unique identifier for this user
+     * This is the ID that the OAuth provider uses to identify the user
+     * Examples: Google sub, Apple user ID, Facebook ID
+     */
     providerId: string;
+    /**
+     * Email address from the provider (for audit/debugging)
+     * May be different from user's primary email if they have multiple emails
+     * Used for account linking by email verification
+     */
     providerEmail?: string | null;
+    /**
+     * When this social account was linked to the user
+     * Used for audit trails and account management
+     */
     linkedAt: Date;
+    /**
+     * When this social account was last used for authentication
+     * Updated on each successful social login
+     * Used for analytics and account cleanup
+     */
     lastUsedAt?: Date | null;
+    /**
+     * Raw OAuth profile data from provider (for debugging)
+     * Contains the full response from the OAuth provider
+     * Useful for troubleshooting and attribute mapping
+     *
+     * @example
+     * ```json
+     * {
+     *   "sub": "google_123",
+     *   "email": "user@gmail.com",
+     *   "given_name": "John",
+     *   "family_name": "Doe",
+     *   "picture": "https://...",
+     *   "locale": "en"
+     * }
+     * ```
+     */
     metadata?: Record<string, unknown> | null;
+    /**
+     * Account creation timestamp
+     */
     createdAt: Date;
+    /**
+     * Last account update timestamp
+     */
     updatedAt: Date;
 }
 //# sourceMappingURL=social-account.entity.d.ts.map

package/dist/entities/social-account.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"social-account.entity.d.ts","sourceRoot":"","sources":["../../src/entities/social-account.entity.ts"],"names":[],"mappings":"AAoBA,qBAAa,iBAAiB;IAM5B,EAAE,EAAG,MAAM,CAAC;IAMZ,MAAM,EAAG,MAAM,CAAC;IAMhB,QAAQ,EAAG,MAAM,CAAC;IAOlB,UAAU,EAAG,MAAM,CAAC;IAOpB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM9B,QAAQ,EAAG,IAAI,CAAC;IAOhB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAmBzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAK1C,SAAS,EAAG,IAAI,CAAC;IAKjB,SAAS,EAAG,IAAI,CAAC;CAClB"}
+{"version":3,"file":"social-account.entity.d.ts","sourceRoot":"","sources":["../../src/entities/social-account.entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAiB;IAC5B;;;;OAIG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;OAGG;IACH,MAAM,EAAG,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,EAAG,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,EAAG,MAAM,CAAC;IAEpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,QAAQ,EAAG,IAAI,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE1C;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;CAClB"}

package/dist/entities/social-account.entity.js

@@ -1,16 +1,91 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseSocialAccount = void 0;
+/**
+ * Base Social Account Entity
+ *
+ * Stores OAuth provider linkage (no token storage, one-time attribute import).
+ * Each record represents a user's account linked to a specific social provider.
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // User has Google and Apple accounts linked
+ * const socialAccounts = [
+ *   { provider: 'google', providerId: 'google_123', providerEmail: 'user@gmail.com' },
+ *   { provider: 'apple', providerId: 'apple_456', providerEmail: 'user@icloud.com' }
+ * ];
+ * ```
+ */
 class BaseSocialAccount {
+    /**
+     * Internal database ID (auto-increment integer)
+     * Used for foreign key relationships and internal queries
+     * NOT exposed externally
+     */
     id;
+    /**
+     * Foreign key to users table
+     * References the user who owns this social account
+     */
     userId;
+    /**
+     * Social provider name
+     * Examples: 'google', 'apple', 'facebook'
+     */
     provider;
+    /**
+     * Provider's unique identifier for this user
+     * This is the ID that the OAuth provider uses to identify the user
+     * Examples: Google sub, Apple user ID, Facebook ID
+     */
     providerId;
+    /**
+     * Email address from the provider (for audit/debugging)
+     * May be different from user's primary email if they have multiple emails
+     * Used for account linking by email verification
+     */
     providerEmail;
+    /**
+     * When this social account was linked to the user
+     * Used for audit trails and account management
+     */
     linkedAt;
+    /**
+     * When this social account was last used for authentication
+     * Updated on each successful social login
+     * Used for analytics and account cleanup
+     */
     lastUsedAt;
+    /**
+     * Raw OAuth profile data from provider (for debugging)
+     * Contains the full response from the OAuth provider
+     * Useful for troubleshooting and attribute mapping
+     *
+     * @example
+     * ```json
+     * {
+     *   "sub": "google_123",
+     *   "email": "user@gmail.com",
+     *   "given_name": "John",
+     *   "family_name": "Doe",
+     *   "picture": "https://...",
+     *   "locale": "en"
+     * }
+     * ```
+     */
     metadata;
+    /**
+     * Account creation timestamp
+     */
     createdAt;
+    /**
+     * Last account update timestamp
+     */
     updatedAt;
 }
 exports.BaseSocialAccount = BaseSocialAccount;

package/dist/entities/social-account.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"social-account.entity.js","sourceRoot":"","sources":["../../src/entities/social-account.entity.ts"],"names":[],"mappings":";;;AAoBA,MAAa,iBAAiB;IAM5B,EAAE,CAAU;IAMZ,MAAM,CAAU;IAMhB,QAAQ,CAAU;IAOlB,UAAU,CAAU;IAOpB,aAAa,CAAiB;IAM9B,QAAQ,CAAQ;IAOhB,UAAU,CAAe;IAmBzB,QAAQ,CAAkC;IAK1C,SAAS,CAAQ;IAKjB,SAAS,CAAQ;CAClB;AA3ED,8CA2EC"}
+{"version":3,"file":"social-account.entity.js","sourceRoot":"","sources":["../../src/entities/social-account.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,iBAAiB;IAC5B;;;;OAIG;IACH,EAAE,CAAU;IAEZ;;;OAGG;IACH,MAAM,CAAU;IAEhB;;;OAGG;IACH,QAAQ,CAAU;IAElB;;;;OAIG;IACH,UAAU,CAAU;IAEpB;;;;OAIG;IACH,aAAa,CAAiB;IAE9B;;;OAGG;IACH,QAAQ,CAAQ;IAEhB;;;;OAIG;IACH,UAAU,CAAe;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAkC;IAE1C;;OAEG;IACH,SAAS,CAAQ;IAEjB;;OAEG;IACH,SAAS,CAAQ;CAClB;AA3ED,8CA2EC"}

package/dist/entities/storage-lock.entity.d.ts

@@ -1,8 +1,36 @@
+/**
+ * Base Storage Lock Entity
+ *
+ * Stores distributed locks for transient state management.
+ * Used by DatabaseStorageAdapter for token refresh locks and other distributed operations.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
 export declare class BaseStorageLock {
+    /**
+     * Internal lock record ID (auto-increment integer)
+     */
     id: number;
+    /**
+     * Unique key identifier for the lock
+     * Format: <lock-type>:<identifier> (e.g., "refresh-lock:token-hash-123")
+     */
     key: string;
+    /**
+     * Lock value (stored as string, typically timestamp or lock holder identifier)
+     */
     value: string;
+    /**
+     * Lock expiration timestamp
+     * Used for TTL-based cleanup and automatic lock release
+     * Can be null for locks that don't expire
+     */
     expiresAt: Date | null;
+    /**
+     * Lock creation timestamp
+     */
     createdAt: Date;
 }
 //# sourceMappingURL=storage-lock.entity.d.ts.map

package/dist/entities/storage-lock.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-lock.entity.d.ts","sourceRoot":"","sources":["../../src/entities/storage-lock.entity.ts"],"names":[],"mappings":"AAUA,qBAAa,eAAe;IAI1B,EAAE,EAAG,MAAM,CAAC;IAMZ,GAAG,EAAG,MAAM,CAAC;IAKb,KAAK,EAAG,MAAM,CAAC;IAOf,SAAS,EAAG,IAAI,GAAG,IAAI,CAAC;IAKxB,SAAS,EAAG,IAAI,CAAC;CAClB"}
+{"version":3,"file":"storage-lock.entity.d.ts","sourceRoot":"","sources":["../../src/entities/storage-lock.entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAG,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAG,MAAM,CAAC;IAEf;;;;OAIG;IACH,SAAS,EAAG,IAAI,GAAG,IAAI,CAAC;IAExB;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;CAClB"}

package/dist/entities/storage-lock.entity.js

@@ -1,11 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseStorageLock = void 0;
+/**
+ * Base Storage Lock Entity
+ *
+ * Stores distributed locks for transient state management.
+ * Used by DatabaseStorageAdapter for token refresh locks and other distributed operations.
+ *
+ * @remarks
+ * This class is database-agnostic. TypeORM, Prisma, or other ORMs
+ * extend this class in their respective packages.
+ */
 class BaseStorageLock {
+    /**
+     * Internal lock record ID (auto-increment integer)
+     */
     id;
+    /**
+     * Unique key identifier for the lock
+     * Format: <lock-type>:<identifier> (e.g., "refresh-lock:token-hash-123")
+     */
     key;
+    /**
+     * Lock value (stored as string, typically timestamp or lock holder identifier)
+     */
     value;
+    /**
+     * Lock expiration timestamp
+     * Used for TTL-based cleanup and automatic lock release
+     * Can be null for locks that don't expire
+     */
     expiresAt;
+    /**
+     * Lock creation timestamp
+     */
     createdAt;
 }
 exports.BaseStorageLock = BaseStorageLock;

package/dist/entities/storage-lock.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-lock.entity.js","sourceRoot":"","sources":["../../src/entities/storage-lock.entity.ts"],"names":[],"mappings":";;;AAUA,MAAa,eAAe;IAI1B,EAAE,CAAU;IAMZ,GAAG,CAAU;IAKb,KAAK,CAAU;IAOf,SAAS,CAAe;IAKxB,SAAS,CAAQ;CAClB;AA5BD,0CA4BC"}
+{"version":3,"file":"storage-lock.entity.js","sourceRoot":"","sources":["../../src/entities/storage-lock.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,eAAe;IAC1B;;OAEG;IACH,EAAE,CAAU;IAEZ;;;OAGG;IACH,GAAG,CAAU;IAEb;;OAEG;IACH,KAAK,CAAU;IAEf;;;;OAIG;IACH,SAAS,CAAe;IAExB;;OAEG;IACH,SAAS,CAAQ;CAClB;AA5BD,0CA4BC"}

package/dist/entities/trusted-device.entity.d.ts

@@ -1,17 +1,100 @@
+/**
+ * Base Trusted Device Entity
+ *
+ * Stores trusted device information for MFA "remember device" feature.
+ * Devices marked as trusted can skip MFA verification for a configured period.
+ * Uses HttpOnly cookies for secure device token storage.
+ *
+ * @remarks
+ * Each user can have multiple trusted devices. Each record represents one device
+ * that has been marked as trusted after successful MFA verification.
+ * Trust persists across logouts and session expiration.
+ *
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @example
+ * ```typescript
+ * // Trust a device after MFA verification
+ * const trustedDevice = new TrustedDevice();
+ * trustedDevice.userId = user.id;
+ * trustedDevice.deviceTokenHash = hashToken(deviceToken);
+ * trustedDevice.trustedUntil = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+ * trustedDevice.deviceName = 'iPhone 15 Pro';
+ * trustedDevice.deviceType = 'mobile';
+ * ```
+ */
 export declare class BaseTrustedDevice {
+    /**
+     * Internal device ID (auto-increment integer)
+     */
     id: number;
+    /**
+     * Internal user ID (foreign key to users table)
+     * References the user who trusted this device
+     */
     userId: number;
+    /**
+     * Hashed device token (SHA-256)
+     * The actual token is stored in HttpOnly cookie, only hash stored in DB
+     * Used for validation and lookup
+     *
+     * SECURITY: Never store the actual token, only the hash
+     */
     deviceTokenHash: string;
+    /**
+     * Device identifier (UUID from client or generated)
+     * Used for additional validation and device management
+     * Can be used to identify the same device across different tokens
+     */
     deviceId?: string | null;
+    /**
+     * User-friendly device name
+     * Examples: "iPhone 15 Pro", "Chrome on MacBook", "Firefox on Windows"
+     */
     deviceName?: string | null;
+    /**
+     * Device type
+     * Examples: "mobile", "desktop", "tablet"
+     */
     deviceType?: string | null;
+    /**
+     * IP address when device was trusted
+     * Used for audit and security monitoring
+     */
     ipAddress?: string | null;
+    /**
+     * User agent string when device was trusted
+     * Used for audit and device identification
+     */
     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;
+    /**
+     * When trust expires
+     * After this date, device is no longer trusted and MFA is required
+     * Calculated as: createdAt + rememberDeviceDays
+     */
     trustedUntil: Date;
+    /**
+     * When this device was last used for login
+     * Updated on each successful login from this trusted device
+     */
     lastUsedAt?: Date | null;
+    /**
+     * Device creation timestamp
+     */
     createdAt: Date;
+    /**
+     * Last update timestamp
+     */
     updatedAt: Date;
 }
 //# sourceMappingURL=trusted-device.entity.d.ts.map

package/dist/entities/trusted-device.entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trusted-device.entity.d.ts","sourceRoot":"","sources":["../../src/entities/trusted-device.entity.ts"],"names":[],"mappings":"AAyBA,qBAAa,iBAAiB;IAI5B,EAAE,EAAG,MAAM,CAAC;IAMZ,MAAM,EAAG,MAAM,CAAC;IAShB,eAAe,EAAG,MAAM,CAAC;IAOzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM3B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAMzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAOxB,YAAY,EAAG,IAAI,CAAC;IAMpB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAKzB,SAAS,EAAG,IAAI,CAAC;IAKjB,SAAS,EAAG,IAAI,CAAC;CAClB"}
+{"version":3,"file":"trusted-device.entity.d.ts","sourceRoot":"","sources":["../../src/entities/trusted-device.entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,EAAE,EAAG,MAAM,CAAC;IAEZ;;;OAGG;IACH,MAAM,EAAG,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,eAAe,EAAG,MAAM,CAAC;IAEzB;;;;OAIG;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;IAE3B;;;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,GAAG,IAAI,CAAC;IAEzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB;;;;OAIG;IACH,YAAY,EAAG,IAAI,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAG,IAAI,CAAC;CAClB"}

package/dist/entities/trusted-device.entity.js

@@ -1,20 +1,103 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseTrustedDevice = void 0;
+/**
+ * Base Trusted Device Entity
+ *
+ * Stores trusted device information for MFA "remember device" feature.
+ * Devices marked as trusted can skip MFA verification for a configured period.
+ * Uses HttpOnly cookies for secure device token storage.
+ *
+ * @remarks
+ * Each user can have multiple trusted devices. Each record represents one device
+ * that has been marked as trusted after successful MFA verification.
+ * Trust persists across logouts and session expiration.
+ *
+ * Database adapters extend this class and add ORM-specific decorators.
+ *
+ * @example
+ * ```typescript
+ * // Trust a device after MFA verification
+ * const trustedDevice = new TrustedDevice();
+ * trustedDevice.userId = user.id;
+ * trustedDevice.deviceTokenHash = hashToken(deviceToken);
+ * trustedDevice.trustedUntil = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+ * trustedDevice.deviceName = 'iPhone 15 Pro';
+ * trustedDevice.deviceType = 'mobile';
+ * ```
+ */
 class BaseTrustedDevice {
+    /**
+     * Internal device ID (auto-increment integer)
+     */
     id;
+    /**
+     * Internal user ID (foreign key to users table)
+     * References the user who trusted this device
+     */
     userId;
+    /**
+     * Hashed device token (SHA-256)
+     * The actual token is stored in HttpOnly cookie, only hash stored in DB
+     * Used for validation and lookup
+     *
+     * SECURITY: Never store the actual token, only the hash
+     */
     deviceTokenHash;
+    /**
+     * Device identifier (UUID from client or generated)
+     * Used for additional validation and device management
+     * Can be used to identify the same device across different tokens
+     */
     deviceId;
+    /**
+     * User-friendly device name
+     * Examples: "iPhone 15 Pro", "Chrome on MacBook", "Firefox on Windows"
+     */
     deviceName;
+    /**
+     * Device type
+     * Examples: "mobile", "desktop", "tablet"
+     */
     deviceType;
+    /**
+     * IP address when device was trusted
+     * Used for audit and security monitoring
+     */
     ipAddress;
+    /**
+     * User agent string when device was trusted
+     * Used for audit and device identification
+     */
     userAgent;
+    /**
+     * Platform extracted from user agent
+     * Examples: "iOS", "Android", "Windows", "macOS"
+     */
     platform;
+    /**
+     * Browser extracted from user agent
+     * Examples: "Chrome", "Safari", "Firefox"
+     */
     browser;
+    /**
+     * When trust expires
+     * After this date, device is no longer trusted and MFA is required
+     * Calculated as: createdAt + rememberDeviceDays
+     */
     trustedUntil;
+    /**
+     * When this device was last used for login
+     * Updated on each successful login from this trusted device
+     */
     lastUsedAt;
+    /**
+     * Device creation timestamp
+     */
     createdAt;
+    /**
+     * Last update timestamp
+     */
     updatedAt;
 }
 exports.BaseTrustedDevice = BaseTrustedDevice;

package/dist/entities/trusted-device.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"trusted-device.entity.js","sourceRoot":"","sources":["../../src/entities/trusted-device.entity.ts"],"names":[],"mappings":";;;AAyBA,MAAa,iBAAiB;IAI5B,EAAE,CAAU;IAMZ,MAAM,CAAU;IAShB,eAAe,CAAU;IAOzB,QAAQ,CAAiB;IAMzB,UAAU,CAAiB;IAM3B,UAAU,CAAiB;IAM3B,SAAS,CAAiB;IAM1B,SAAS,CAAiB;IAM1B,QAAQ,CAAiB;IAMzB,OAAO,CAAiB;IAOxB,YAAY,CAAQ;IAMpB,UAAU,CAAe;IAKzB,SAAS,CAAQ;IAKjB,SAAS,CAAQ;CAClB;AAtFD,8CAsFC"}
+{"version":3,"file":"trusted-device.entity.js","sourceRoot":"","sources":["../../src/entities/trusted-device.entity.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,iBAAiB;IAC5B;;OAEG;IACH,EAAE,CAAU;IAEZ;;;OAGG;IACH,MAAM,CAAU;IAEhB;;;;;;OAMG;IACH,eAAe,CAAU;IAEzB;;;;OAIG;IACH,QAAQ,CAAiB;IAEzB;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,UAAU,CAAiB;IAE3B;;;OAGG;IACH,SAAS,CAAiB;IAE1B;;;OAGG;IACH,SAAS,CAAiB;IAE1B;;;OAGG;IACH,QAAQ,CAAiB;IAEzB;;;OAGG;IACH,OAAO,CAAiB;IAExB;;;;OAIG;IACH,YAAY,CAAQ;IAEpB;;;OAGG;IACH,UAAU,CAAe;IAEzB;;OAEG;IACH,SAAS,CAAQ;IAEjB;;OAEG;IACH,SAAS,CAAQ;CAClB;AAtFD,8CAsFC"}