@nauth-toolkit/core 0.1.14 → 0.1.18

package/dist/dto/auth-challenge.dto.d.ts

@@ -1,19 +1,189 @@
+/**
+ * Authentication Challenge Types
+ *
+ * Represents different challenges that must be completed before
+ * a user can gain full access to the system. This is similar to
+ * AWS Cognito's challenge system.
+ *
+ * @example
+ * ```typescript
+ * // After login, check for challenges
+ * const result = await authService.login(credentials);
+ * if (result.challengeName) {
+ *   // User must complete challenge before accessing system
+ *   console.log('Challenge required:', result.challengeName);
+ * }
+ * ```
+ */
 export declare enum AuthChallenge {
+    /**
+     * Email verification required
+     * User must verify their email address before proceeding
+     */
     VERIFY_EMAIL = "VERIFY_EMAIL",
+    /**
+     * Phone verification required
+     * User must verify their phone number before proceeding
+     */
     VERIFY_PHONE = "VERIFY_PHONE",
+    /**
+     * Multi-factor authentication required
+     * User must complete MFA verification (TOTP, SMS, etc.)
+     * This challenge is used when user already has MFA enabled and needs to verify
+     */
     MFA_REQUIRED = "MFA_REQUIRED",
+    /**
+     * MFA setup required
+     * User must set up multi-factor authentication before being allowed to login.
+     * This occurs when enforcement is 'REQUIRED' and grace period has expired or is disabled.
+     */
     MFA_SETUP_REQUIRED = "MFA_SETUP_REQUIRED",
+    /**
+     * Password change required
+     * User must change their password before proceeding
+     * (e.g., admin-forced password reset, expired password)
+     */
     FORCE_CHANGE_PASSWORD = "FORCE_CHANGE_PASSWORD"
 }
+/**
+ * Challenge Response DTO
+ *
+ * Used when a user's authentication is incomplete due to pending challenges.
+ * Contains minimal information about the user and what challenges they must complete.
+ *
+ * Note: This is primarily a response DTO, but validation is included for completeness.
+ *
+ * @example
+ * ```typescript
+ * // Login response with challenge
+ * {
+ *   challengeName: 'VERIFY_EMAIL',
+ *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   challengeParameters: {
+ *     email: 'user@example.com',
+ *     codeDeliveryDestination: 'u***@example.com'
+ *   },
+ *   userSub: 'a21b654c-2746-4168-acee-c175083a65cd'
+ * }
+ * ```
+ */
 export declare class AuthChallengeResponseDTO {
+    /**
+     * The challenge that must be completed
+     *
+     * Validation:
+     * - Must be a valid AuthChallenge enum value
+     */
     challengeName: AuthChallenge;
+    /**
+     * Temporary session identifier for challenge completion (UUID v4)
+     * This is NOT a full JWT token - only used for challenge verification
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Generated using randomUUID() in challenge service
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     session: string;
+    /**
+     * Challenge-specific parameters
+     * Contains information needed to complete the challenge
+     *
+     * Validation:
+     * - Must be an object
+     *
+     * @example
+     * ```typescript
+     * // For VERIFY_EMAIL
+     * {
+     *   email: 'user@example.com',
+     *   codeDeliveryDestination: 'u***@example.com'
+     * }
+     *
+     * // For VERIFY_PHONE
+     * {
+     *   phone: '+1234567890',
+     *   codeDeliveryDestination: '***-***-7890'
+     * }
+     * ```
+     */
     challengeParameters: Record<string, unknown>;
+    /**
+     * User's unique identifier (UUID v4)
+     * Provided so the client knows which user is completing challenges
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Matches DB constraint: char(36) or uuid
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     userSub: string;
 }
+/**
+ * Challenge Completion Request DTO
+ *
+ * Used to submit a response to an authentication challenge.
+ *
+ * Note: This is a legacy DTO. The codebase now uses RespondChallengeDTO for the unified API.
+ * This DTO is kept for backwards compatibility.
+ *
+ * Security:
+ * - Session token validated as UUID v4 format
+ * - Challenge name validated against enum
+ * - Challenge responses validated as object
+ *
+ * @example
+ * ```typescript
+ * // Verify email challenge
+ * const request: ChallengeResponseRequestDTO = {
+ *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   challengeName: 'VERIFY_EMAIL',
+ *   challengeResponses: {
+ *     code: '123456'
+ *   }
+ * };
+ * ```
+ */
 export declare class ChallengeResponseRequestDTO {
+    /**
+     * Temporary session from initial auth response (UUID v4)
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Generated using randomUUID() in challenge service
+     *
+     * Sanitization:
+     * - Trimmed
+     * - Lowercased for consistency
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     session: string;
+    /**
+     * The challenge being responded to
+     *
+     * Validation:
+     * - Must be a valid AuthChallenge enum value
+     */
     challengeName: AuthChallenge;
+    /**
+     * Challenge-specific responses
+     *
+     * Validation:
+     * - Must be an object
+     * - Structure validated in service layer based on challenge type
+     *
+     * @example
+     * ```typescript
+     * // For VERIFY_EMAIL or VERIFY_PHONE
+     * { code: '123456' }
+     *
+     * // For FORCE_CHANGE_PASSWORD
+     * { newPassword: 'NewSecure123!' }
+     * ```
+     */
     challengeResponses: Record<string, unknown>;
 }
 //# sourceMappingURL=auth-challenge.dto.d.ts.map

package/dist/dto/auth-challenge.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-challenge.dto.d.ts","sourceRoot":"","sources":["../../src/dto/auth-challenge.dto.ts"],"names":[],"mappings":"AAoBA,oBAAY,aAAa;IAKvB,YAAY,iBAAiB;IAM7B,YAAY,iBAAiB;IAO7B,YAAY,iBAAiB;IAO7B,kBAAkB,uBAAuB;IAOzC,qBAAqB,0BAA0B;CAChD;AAwBD,qBAAa,wBAAwB;IAUnC,aAAa,EAAG,aAAa,CAAC;IAmB9B,OAAO,EAAG,MAAM,CAAC;IAyBjB,mBAAmB,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAmB9C,OAAO,EAAG,MAAM,CAAC;CAClB;AA2BD,qBAAa,2BAA2B;IAqBtC,OAAO,EAAG,MAAM,CAAC;IAWjB,aAAa,EAAG,aAAa,CAAC;IAmB9B,kBAAkB,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C"}
+{"version":3,"file":"auth-challenge.dto.d.ts","sourceRoot":"","sources":["../../src/dto/auth-challenge.dto.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,oBAAY,aAAa;IACvB;;;OAGG;IACH,YAAY,iBAAiB;IAE7B;;;OAGG;IACH,YAAY,iBAAiB;IAE7B;;;;OAIG;IACH,YAAY,iBAAiB;IAE7B;;;;OAIG;IACH,kBAAkB,uBAAuB;IAEzC;;;;OAIG;IACH,qBAAqB,0BAA0B;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAwB;IACnC;;;;;OAKG;IAIH,aAAa,EAAG,aAAa,CAAC;IAE9B;;;;;;;;;OASG;IAQH,OAAO,EAAG,MAAM,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;;;OAqBG;IAEH,mBAAmB,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE9C;;;;;;;;;OASG;IAQH,OAAO,EAAG,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,2BAA2B;IACtC;;;;;;;;;;;;OAYG;IAQH,OAAO,EAAG,MAAM,CAAC;IAEjB;;;;;OAKG;IAIH,aAAa,EAAG,aAAa,CAAC;IAE9B;;;;;;;;;;;;;;;OAeG;IAEH,kBAAkB,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C"}

package/dist/dto/auth-challenge.dto.js

@@ -12,18 +12,128 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChallengeResponseRequestDTO = exports.AuthChallengeResponseDTO = exports.AuthChallenge = void 0;
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
+/**
+ * Authentication Challenge Types
+ *
+ * Represents different challenges that must be completed before
+ * a user can gain full access to the system. This is similar to
+ * AWS Cognito's challenge system.
+ *
+ * @example
+ * ```typescript
+ * // After login, check for challenges
+ * const result = await authService.login(credentials);
+ * if (result.challengeName) {
+ *   // User must complete challenge before accessing system
+ *   console.log('Challenge required:', result.challengeName);
+ * }
+ * ```
+ */
 var AuthChallenge;
 (function (AuthChallenge) {
+    /**
+     * Email verification required
+     * User must verify their email address before proceeding
+     */
     AuthChallenge["VERIFY_EMAIL"] = "VERIFY_EMAIL";
+    /**
+     * Phone verification required
+     * User must verify their phone number before proceeding
+     */
     AuthChallenge["VERIFY_PHONE"] = "VERIFY_PHONE";
+    /**
+     * Multi-factor authentication required
+     * User must complete MFA verification (TOTP, SMS, etc.)
+     * This challenge is used when user already has MFA enabled and needs to verify
+     */
     AuthChallenge["MFA_REQUIRED"] = "MFA_REQUIRED";
+    /**
+     * MFA setup required
+     * User must set up multi-factor authentication before being allowed to login.
+     * This occurs when enforcement is 'REQUIRED' and grace period has expired or is disabled.
+     */
     AuthChallenge["MFA_SETUP_REQUIRED"] = "MFA_SETUP_REQUIRED";
+    /**
+     * Password change required
+     * User must change their password before proceeding
+     * (e.g., admin-forced password reset, expired password)
+     */
     AuthChallenge["FORCE_CHANGE_PASSWORD"] = "FORCE_CHANGE_PASSWORD";
 })(AuthChallenge || (exports.AuthChallenge = AuthChallenge = {}));
+/**
+ * Challenge Response DTO
+ *
+ * Used when a user's authentication is incomplete due to pending challenges.
+ * Contains minimal information about the user and what challenges they must complete.
+ *
+ * Note: This is primarily a response DTO, but validation is included for completeness.
+ *
+ * @example
+ * ```typescript
+ * // Login response with challenge
+ * {
+ *   challengeName: 'VERIFY_EMAIL',
+ *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   challengeParameters: {
+ *     email: 'user@example.com',
+ *     codeDeliveryDestination: 'u***@example.com'
+ *   },
+ *   userSub: 'a21b654c-2746-4168-acee-c175083a65cd'
+ * }
+ * ```
+ */
 class AuthChallengeResponseDTO {
+    /**
+     * The challenge that must be completed
+     *
+     * Validation:
+     * - Must be a valid AuthChallenge enum value
+     */
     challengeName;
+    /**
+     * Temporary session identifier for challenge completion (UUID v4)
+     * This is NOT a full JWT token - only used for challenge verification
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Generated using randomUUID() in challenge service
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     session;
+    /**
+     * Challenge-specific parameters
+     * Contains information needed to complete the challenge
+     *
+     * Validation:
+     * - Must be an object
+     *
+     * @example
+     * ```typescript
+     * // For VERIFY_EMAIL
+     * {
+     *   email: 'user@example.com',
+     *   codeDeliveryDestination: 'u***@example.com'
+     * }
+     *
+     * // For VERIFY_PHONE
+     * {
+     *   phone: '+1234567890',
+     *   codeDeliveryDestination: '***-***-7890'
+     * }
+     * ```
+     */
     challengeParameters;
+    /**
+     * User's unique identifier (UUID v4)
+     * Provided so the client knows which user is completing challenges
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Matches DB constraint: char(36) or uuid
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     userSub;
 }
 exports.AuthChallengeResponseDTO = AuthChallengeResponseDTO;
@@ -57,9 +167,69 @@ __decorate([
     }),
     __metadata("design:type", String)
 ], AuthChallengeResponseDTO.prototype, "userSub", void 0);
+/**
+ * Challenge Completion Request DTO
+ *
+ * Used to submit a response to an authentication challenge.
+ *
+ * Note: This is a legacy DTO. The codebase now uses RespondChallengeDTO for the unified API.
+ * This DTO is kept for backwards compatibility.
+ *
+ * Security:
+ * - Session token validated as UUID v4 format
+ * - Challenge name validated against enum
+ * - Challenge responses validated as object
+ *
+ * @example
+ * ```typescript
+ * // Verify email challenge
+ * const request: ChallengeResponseRequestDTO = {
+ *   session: 'a21b654c-2746-4168-acee-c175083a65cd',
+ *   challengeName: 'VERIFY_EMAIL',
+ *   challengeResponses: {
+ *     code: '123456'
+ *   }
+ * };
+ * ```
+ */
 class ChallengeResponseRequestDTO {
+    /**
+     * Temporary session from initial auth response (UUID v4)
+     *
+     * Validation:
+     * - Must be a valid UUID v4 format
+     * - Generated using randomUUID() in challenge service
+     *
+     * Sanitization:
+     * - Trimmed
+     * - Lowercased for consistency
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     session;
+    /**
+     * The challenge being responded to
+     *
+     * Validation:
+     * - Must be a valid AuthChallenge enum value
+     */
     challengeName;
+    /**
+     * Challenge-specific responses
+     *
+     * Validation:
+     * - Must be an object
+     * - Structure validated in service layer based on challenge type
+     *
+     * @example
+     * ```typescript
+     * // For VERIFY_EMAIL or VERIFY_PHONE
+     * { code: '123456' }
+     *
+     * // For FORCE_CHANGE_PASSWORD
+     * { newPassword: 'NewSecure123!' }
+     * ```
+     */
     challengeResponses;
 }
 exports.ChallengeResponseRequestDTO = ChallengeResponseRequestDTO;

package/dist/dto/auth-challenge.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-challenge.dto.js","sourceRoot":"","sources":["../../src/dto/auth-challenge.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDAA2D;AAC3D,yDAA8C;AAmB9C,IAAY,aAiCX;AAjCD,WAAY,aAAa;IAKvB,8CAA6B,CAAA;IAM7B,8CAA6B,CAAA;IAO7B,8CAA6B,CAAA;IAO7B,0DAAyC,CAAA;IAOzC,gEAA+C,CAAA;AACjD,CAAC,EAjCW,aAAa,6BAAb,aAAa,QAiCxB;AAwBD,MAAa,wBAAwB;IAUnC,aAAa,CAAiB;IAmB9B,OAAO,CAAU;IAyBjB,mBAAmB,CAA2B;IAmB9C,OAAO,CAAU;CAClB;AA1ED,4DA0EC;AAhEC;IAHC,IAAA,wBAAM,EAAC,aAAa,EAAE;QACrB,OAAO,EAAE,yDAAyD;KACnE,CAAC;;+DAC4B;AAmB9B;IAPC,IAAA,wBAAM,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IACxE,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;;yDACe;AAyBjB;IADC,IAAA,0BAAQ,EAAC,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAC;;qEAClB;AAmB9C;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;;yDACe;AA4BnB,MAAa,2BAA2B;IAqBtC,OAAO,CAAU;IAWjB,aAAa,CAAiB;IAmB9B,kBAAkB,CAA2B;CAC9C;AApDD,kEAoDC;AA/BC;IAPC,IAAA,wBAAM,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IACxE,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;;4DACe;AAWjB;IAHC,IAAA,wBAAM,EAAC,aAAa,EAAE;QACrB,OAAO,EAAE,yDAAyD;KACnE,CAAC;;kEAC4B;AAmB9B;IADC,IAAA,0BAAQ,EAAC,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;;uEAClB"}
+{"version":3,"file":"auth-challenge.dto.js","sourceRoot":"","sources":["../../src/dto/auth-challenge.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDAA2D;AAC3D,yDAA8C;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,IAAY,aAiCX;AAjCD,WAAY,aAAa;IACvB;;;OAGG;IACH,8CAA6B,CAAA;IAE7B;;;OAGG;IACH,8CAA6B,CAAA;IAE7B;;;;OAIG;IACH,8CAA6B,CAAA;IAE7B;;;;OAIG;IACH,0DAAyC,CAAA;IAEzC;;;;OAIG;IACH,gEAA+C,CAAA;AACjD,CAAC,EAjCW,aAAa,6BAAb,aAAa,QAiCxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,wBAAwB;IACnC;;;;;OAKG;IAIH,aAAa,CAAiB;IAE9B;;;;;;;;;OASG;IAQH,OAAO,CAAU;IAEjB;;;;;;;;;;;;;;;;;;;;;OAqBG;IAEH,mBAAmB,CAA2B;IAE9C;;;;;;;;;OASG;IAQH,OAAO,CAAU;CAClB;AA1ED,4DA0EC;AAhEC;IAHC,IAAA,wBAAM,EAAC,aAAa,EAAE;QACrB,OAAO,EAAE,yDAAyD;KACnE,CAAC;;+DAC4B;AAmB9B;IAPC,IAAA,wBAAM,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IACxE,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;;yDACe;AAyBjB;IADC,IAAA,0BAAQ,EAAC,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAC;;qEAClB;AAmB9C;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;;yDACe;AAGnB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,2BAA2B;IACtC;;;;;;;;;;;;OAYG;IAQH,OAAO,CAAU;IAEjB;;;;;OAKG;IAIH,aAAa,CAAiB;IAE9B;;;;;;;;;;;;;;;OAeG;IAEH,kBAAkB,CAA2B;CAC9C;AApDD,kEAoDC;AA/BC;IAPC,IAAA,wBAAM,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,8CAA8C,EAAE,CAAC;IACxE,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;;4DACe;AAWjB;IAHC,IAAA,wBAAM,EAAC,aAAa,EAAE;QACrB,OAAO,EAAE,yDAAyD;KACnE,CAAC;;kEAC4B;AAmB9B;IADC,IAAA,0BAAQ,EAAC,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;;uEAClB"}

package/dist/dto/auth-response.dto.d.ts

@@ -1,31 +1,227 @@
 import { AuthChallenge } from './auth-challenge.dto';
+/**
+ * Unified Authentication Response DTO
+ *
+ * Used for ALL authentication operations:
+ * - Email/password login
+ * - User signup
+ * - Social authentication (Google, Apple, Facebook)
+ * - Token refresh
+ * - Challenge completions
+ *
+ * This provides a consistent interface regardless of authentication method,
+ * improving developer experience and code maintainability.
+ *
+ * When challenges are present, tokens will not be issued until all challenges
+ * are completed. This ensures proper verification and security enforcement.
+ *
+ * No validators needed - this is generated internally by the library.
+ *
+ * @example
+ * ```typescript
+ * // Successful auth with no challenges
+ * const loginResult = await authService.login(dto);
+ * // { accessToken: '...', refreshToken: '...', user: {...} }
+ *
+ * // Auth with pending challenge
+ * const signupResult = await authService.signup(dto);
+ * // { challengeName: 'VERIFY_EMAIL', session: '...', challengeParameters: {...} }
+ * ```
+ */
 export declare class AuthResponseDTO {
+    /**
+     * JWT access token for API authentication
+     * Short-lived (typically 15 minutes)
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     accessToken?: string;
+    /**
+     * JWT refresh token for obtaining new access tokens
+     * Long-lived (typically 30 days)
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     refreshToken?: string;
+    /**
+     * Access token expiration timestamp
+     * Unix timestamp in seconds
+     *
+     * @example 1730000000 (represents a specific date/time)
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     accessTokenExpiresAt?: number;
+    /**
+     * Refresh token expiration timestamp
+     * Unix timestamp in seconds
+     *
+     * @example 1732592000 (30 days after access token)
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     refreshTokenExpiresAt?: number;
+    /**
+     * Whether the current device is already trusted
+     *
+     * When true, the device has a valid trusted device token and UI should NOT show
+     * "trust device" popup.
+     *
+     * When false and rememberDevices === 'user_opt_in', UI can show popup after login
+     * to allow user to opt-in for device trust.
+     *
+     * When rememberDevices === 'always', this will always be true after successful login.
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     trusted?: boolean;
+    /**
+     * Device token for trusted device feature (UUID v4)
+     *
+     * Server-generated UUID token for identifying trusted devices.
+     * Only returned when rememberDevices is not 'never' and device is trusted.
+     *
+     * Delivery by mode:
+     * - **cookies mode**: Token set as `nauth_device_token` httpOnly cookie (not in response body)
+     * - **json/hybrid mode**: Token returned in response body for mobile apps
+     *
+     * Mobile apps should:
+     * - Store token in secure storage (iOS Keychain / Android EncryptedSharedPreferences)
+     * - Send token in `X-Device-Token` header on subsequent logins
+     * - Token persists across app restarts and survives logout
+     *
+     * Web apps:
+     * - Token automatically handled via httpOnly cookie (cookies mode)
+     * - No manual handling required
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     * WARNING: For JSON mode, ensure secure storage - token in response body can be intercepted
+     */
     deviceToken?: string;
+    /**
+     * User information
+     * Standardized across all authentication methods
+     *
+     * NOTE: Only present when authentication is complete (no pending challenges)
+     */
     user?: {
+        /**
+         * User's unique identifier (UUID v4)
+         * External identifier safe to expose in JWTs and APIs
+         */
         sub: string;
+        /**
+         * User's email address
+         */
         email: string;
+        /**
+         * User's first name (optional)
+         */
         firstName?: string | null;
+        /**
+         * User's last name (optional)
+         */
         lastName?: string | null;
+        /**
+         * User's phone number (optional)
+         * E.164 format
+         */
         phone?: string;
+        /**
+         * Email verification status
+         */
         isEmailVerified: boolean;
+        /**
+         * Phone verification status
+         */
         isPhoneVerified?: boolean;
+        /**
+         * List of linked social providers
+         * @example ['google', 'apple']
+         */
         socialProviders?: string[];
+        /**
+         * Whether this user has a password set
+         * Used to determine if user can use password-based authentication
+         * or is a pure social signup (no password, only social auth)
+         */
         hasPasswordHash?: boolean;
     };
+    /**
+     * Challenge that must be completed before authentication is granted
+     *
+     * When present, the user must complete this challenge using the
+     * challenge completion endpoint before they can access the system.
+     *
+     * Tokens (accessToken, refreshToken) will NOT be present when a challenge exists.
+     *
+     * @example 'VERIFY_EMAIL' | 'VERIFY_PHONE' | 'MFA_REQUIRED'
+     */
     challengeName?: AuthChallenge;
+    /**
+     * Temporary session identifier for challenge completion (UUID v4)
+     *
+     * This is NOT a JWT token - it's a temporary identifier that must be
+     * submitted when completing the challenge. It expires after a short time
+     * (typically 15 minutes) or after successful challenge completion.
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     *
+     * NOTE: Only present when challengeName is set
+     */
     session?: string;
+    /**
+     * Challenge-specific parameters
+     *
+     * Contains information needed to complete the challenge, such as:
+     * - Masked email/phone for delivery confirmation
+     * - Challenge type details
+     * - Instructions for the user
+     *
+     * NOTE: Only present when challengeName is set
+     *
+     * @example
+     * ```typescript
+     * {
+     *   email: 'user@example.com',
+     *   codeDeliveryDestination: 'u***@example.com'
+     * }
+     * ```
+     */
     challengeParameters?: Record<string, unknown>;
+    /**
+     * User's unique identifier (UUID v4)
+     * Present in both successful auth and challenge responses
+     * Helps the client track which user is authenticating
+     *
+     * @example "a21b654c-2746-4168-acee-c175083a65cd"
+     */
     userSub?: string;
 }
+/**
+ * Token Response DTO
+ *
+ * Returned by token refresh operations
+ * Contains new access and refresh tokens with expiration times
+ */
 export interface TokenResponse {
+    /**
+     * New JWT access token
+     */
     accessToken: string;
+    /**
+     * New JWT refresh token
+     */
     refreshToken: string;
+    /**
+     * Access token expiration (Unix timestamp in seconds)
+     */
     accessTokenExpiresAt: number;
+    /**
+     * Refresh token expiration (Unix timestamp in seconds)
+     */
     refreshTokenExpiresAt: number;
 }
 //# sourceMappingURL=auth-response.dto.d.ts.map

package/dist/dto/auth-response.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-response.dto.d.ts","sourceRoot":"","sources":["../../src/dto/auth-response.dto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+BrD,qBAAa,eAAe;IAO1B,WAAW,CAAC,EAAE,MAAM,CAAC;IAQrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAUtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAU9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAe/B,OAAO,CAAC,EAAE,OAAO,CAAC;IA0BlB,WAAW,CAAC,EAAE,MAAM,CAAC;IAQrB,IAAI,CAAC,EAAE;QAKL,GAAG,EAAE,MAAM,CAAC;QAKZ,KAAK,EAAE,MAAM,CAAC;QAKd,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAK1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAMzB,KAAK,CAAC,EAAE,MAAM,CAAC;QAKf,eAAe,EAAE,OAAO,CAAC;QAKzB,eAAe,CAAC,EAAE,OAAO,CAAC;QAM1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAO3B,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;IAgBF,aAAa,CAAC,EAAE,aAAa,CAAC;IAa9B,OAAO,CAAC,EAAE,MAAM,CAAC;IAoBjB,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAS9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAQD,MAAM,WAAW,aAAa;IAI5B,WAAW,EAAE,MAAM,CAAC;IAKpB,YAAY,EAAE,MAAM,CAAC;IAKrB,oBAAoB,EAAE,MAAM,CAAC;IAK7B,qBAAqB,EAAE,MAAM,CAAC;CAC/B"}
+{"version":3,"file":"auth-response.dto.d.ts","sourceRoot":"","sources":["../../src/dto/auth-response.dto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAe;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,IAAI,CAAC,EAAE;QACL;;;WAGG;QACH,GAAG,EAAE,MAAM,CAAC;QAEZ;;WAEG;QACH,KAAK,EAAE,MAAM,CAAC;QAEd;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAE1B;;WAEG;QACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAEzB;;;WAGG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QAEf;;WAEG;QACH,eAAe,EAAE,OAAO,CAAC;QAEzB;;WAEG;QACH,eAAe,CAAC,EAAE,OAAO,CAAC;QAE1B;;;WAGG;QACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAE3B;;;;WAIG;QACH,eAAe,CAAC,EAAE,OAAO,CAAC;KAC3B,CAAC;IAMF;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B"}