@ackplus/nest-auth 0.1.51 → 1.1.0

package/src/lib/auth/dto/credentials/phone-credentials.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNotEmpty, IsPhoneNumber } from 'class-validator';
+
+/**
+ * Phone-based login credentials
+ */
+export class PhoneCredentialsDto {
+    @ApiProperty({
+        description: 'User phone number',
+        example: '+1234567890',
+    })
+    @IsPhoneNumber()
+    @IsNotEmpty()
+    phone: string;
+
+    @ApiProperty({
+        description: 'User password',
+        example: 'SecurePass123!',
+        minLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    password: string;
+}

package/src/lib/auth/dto/credentials/social-credentials.dto.ts

@@ -0,0 +1,15 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNotEmpty } from 'class-validator';
+
+/**
+ * Social login credentials (Google, Facebook, Apple, GitHub)
+ */
+export class SocialCredentialsDto {
+    @ApiProperty({
+        description: 'OAuth token or ID token from social provider',
+        example: 'ya29.a0AfH6SMBx1234567890abcdefghijklmnop',
+    })
+    @IsString()
+    @IsNotEmpty()
+    accessToken: string;
+}

package/src/lib/auth/dto/index.ts

@@ -0,0 +1 @@
+ 

package/src/lib/auth/dto/requests/change-password.request.dto.ts

@@ -0,0 +1,34 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, MinLength, Validate, ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+@ValidatorConstraint({ name: 'passwordNotSameAsCurrent', async: false })
+class PasswordNotSameAsCurrent implements ValidatorConstraintInterface {
+    validate(newPassword: string, args: ValidationArguments) {
+        const obj = args.object as any;
+        return typeof newPassword === 'string' && newPassword !== obj.currentPassword;
+    }
+    defaultMessage(_args: ValidationArguments) {
+        return 'New password must be different from the current password';
+    }
+}
+
+export class ChangePasswordRequestDto {
+    @ApiProperty({
+        description: 'Current password',
+        example: 'DemoOwner1!',
+        minLength: 8,
+    })
+    @IsString()
+    @MinLength(8)
+    currentPassword: string;
+
+    @ApiProperty({
+        description: 'New password',
+        example: 'DemoOwner1!New',
+        minLength: 8,
+    })
+    @IsString()
+    @MinLength(8)
+    @Validate(PasswordNotSameAsCurrent)
+    newPassword: string;
+}

package/src/lib/auth/dto/requests/forgot-password.request.dto.ts

@@ -0,0 +1,30 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsPhoneNumber, ValidateIf, IsUUID, IsOptional } from 'class-validator';
+
+export class ForgotPasswordRequestDto {
+    @ApiPropertyOptional({
+        description: 'User email address (required if phone not provided)',
+        example: 'user@example.com',
+    })
+    @ValidateIf(o => !o.phone)
+    @IsEmail()
+    @IsNotEmpty()
+    email?: string;
+
+    @ApiPropertyOptional({
+        description: 'User phone number (required if email not provided)',
+        example: '+1234567890',
+    })
+    @ValidateIf(o => !o.email)
+    @IsPhoneNumber()
+    @IsNotEmpty()
+    phone?: string;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/initialize-admin.request.dto.ts

@@ -0,0 +1,51 @@
+import { IsEmail, IsNotEmpty, IsOptional, IsString, MinLength, Matches, IsObject } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class InitializeAdminRequestDto {
+    @ApiProperty({
+        description: 'Super admin email address',
+        example: 'admin@example.com'
+    })
+    @IsEmail()
+    @IsNotEmpty()
+    email: string;
+
+    @ApiProperty({
+        description: 'Super admin password (minimum 8 characters, must contain uppercase, lowercase, number, and special character)',
+        example: 'SecurePassword123!',
+        minLength: 8
+    })
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    @Matches(
+        /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
+        { message: 'Password must contain uppercase, lowercase, number, and special character' }
+    )
+    password: string;
+
+    @ApiProperty({
+        description: 'Secret key for authorization (provided in module configuration)',
+        example: 'your-secret-key'
+    })
+    @IsString()
+    @IsNotEmpty()
+    secretKey: string;
+
+    @ApiProperty({
+        description: 'Tenant ID (optional, uses default tenant if not provided)',
+        required: false
+    })
+    @IsOptional()
+    @IsString()
+    tenantId?: string;
+
+    @ApiProperty({
+        description: 'Additional metadata for the admin user (free-form object for storing firstName, lastName, department, etc.)',
+        required: false,
+        example: { firstName: 'Admin', lastName: 'User', department: 'IT' }
+    })
+    @IsOptional()
+    @IsObject()
+    metadata?: Record<string, any>;
+}

package/src/lib/auth/dto/requests/login.request.dto.ts

@@ -0,0 +1,65 @@
+import { IsString, IsUUID, IsOptional, IsObject, IsBoolean } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional, ApiExtraModels, getSchemaPath } from '@nestjs/swagger';
+import { EmailCredentialsDto } from '../credentials/email-credentials.dto';
+import { PhoneCredentialsDto } from '../credentials/phone-credentials.dto';
+import { SocialCredentialsDto } from '../credentials/social-credentials.dto';
+
+/**
+ * Login request DTO supporting multiple authentication providers
+ */
+@ApiExtraModels(EmailCredentialsDto, PhoneCredentialsDto, SocialCredentialsDto)
+export class LoginRequestDto {
+
+    @ApiPropertyOptional({
+        description: 'Authentication provider name',
+        example: 'email',
+        enum: ['email', 'phone', 'google', 'facebook', 'apple', 'github'],
+        default: 'email',
+    })
+    @IsString()
+    @IsOptional()
+    providerName?: string;
+
+    @ApiProperty({
+        description: 'Login credentials - type varies by provider',
+        required: false,
+        examples: {
+            emailLogin: {
+                summary: 'Email Login',
+                value: { email: 'user@example.com', password: 'SecurePass123!' },
+            },
+            phoneLogin: {
+                summary: 'Phone Login',
+                value: { phone: '+1234567890', password: 'SecurePass123!' },
+            },
+            socialLogin: {
+                summary: 'Social Login (Google/Facebook/etc)',
+                value: { token: 'ya29.a0AfH6SMBx...' },
+            },
+        },
+        oneOf: [
+            { $ref: getSchemaPath(EmailCredentialsDto) },
+            { $ref: getSchemaPath(PhoneCredentialsDto) },
+            { $ref: getSchemaPath(SocialCredentialsDto) },
+        ],
+    })
+    @IsObject()
+    @IsOptional()
+    credentials?: EmailCredentialsDto | PhoneCredentialsDto | SocialCredentialsDto | Record<string, any>;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+
+    @ApiPropertyOptional({
+        description: 'Auto-create user if not exists (for social auth)',
+        default: false,
+    })
+    @IsBoolean()
+    @IsOptional()
+    createUserIfNotExists?: boolean;
+}

package/src/lib/auth/dto/requests/refresh-token.request.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNotEmpty } from 'class-validator';
+
+export class RefreshTokenRequestDto {
+    @ApiProperty({
+        description: 'Refresh token to obtain new access token',
+        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCJ9.abc123',
+    })
+    @IsString()
+    @IsNotEmpty()
+    refreshToken: string;
+}

package/src/lib/auth/dto/requests/reset-password-with-token.request.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString, MinLength } from 'class-validator';
+
+export class ResetPasswordWithTokenRequestDto {
+    @ApiProperty({
+        description: 'Password reset token (JWT) received after OTP verification',
+        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGFzc3dvcmQtcmVzZXQifQ.xyz',
+    })
+    @IsString()
+    @IsNotEmpty()
+    token: string;
+
+    @ApiProperty({
+        description: 'New password',
+        example: 'NewSecurePass123!',
+        minLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    newPassword: string;
+}

package/src/lib/auth/dto/requests/reset-password.request.dto.ts

@@ -0,0 +1,50 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsNotEmpty, IsPhoneNumber, IsString, ValidateIf, IsUUID, IsOptional, MinLength } from 'class-validator';
+
+export class ResetPasswordRequestDto {
+    @ApiPropertyOptional({
+        description: 'User email address (required if phone not provided)',
+        example: 'user@example.com',
+    })
+    @ValidateIf(o => !o.phone)
+    @IsEmail()
+    @IsNotEmpty()
+    email?: string;
+
+    @ApiPropertyOptional({
+        description: 'User phone number (required if email not provided)',
+        example: '+1234567890',
+    })
+    @ValidateIf(o => !o.email)
+    @IsPhoneNumber()
+    @IsNotEmpty()
+    phone?: string;
+
+    @ApiProperty({
+        description: 'One-time password (OTP) received via email or SMS',
+        example: '123456',
+        minLength: 6,
+        maxLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    otp: string;
+
+    @ApiProperty({
+        description: 'New password',
+        example: 'NewSecurePass123!',
+        minLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    newPassword: string;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/send-email-verification.request.dto.ts

@@ -0,0 +1,12 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsUUID, IsOptional } from 'class-validator';
+
+export class SendEmailVerificationRequestDto {
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/send-mfa-code.request.dto.ts

@@ -0,0 +1,19 @@
+import { IsEnum } from "class-validator";
+import { MFAMethodEnum } from "../../../core";
+import { ApiProperty } from "@nestjs/swagger";
+
+export class SendMfaCodeRequestDto {
+    @ApiProperty({
+        description: 'MFA delivery method',
+        enum: MFAMethodEnum,
+        example: MFAMethodEnum.EMAIL,
+        enumName: 'MFAMethodEnum',
+        examples: {
+            email: { value: MFAMethodEnum.EMAIL, description: 'Send OTP via email' },
+            sms: { value: MFAMethodEnum.SMS, description: 'Send OTP via SMS' },
+            totp: { value: MFAMethodEnum.TOTP, description: 'Use authenticator app (TOTP)' },
+        },
+    })
+    @IsEnum(MFAMethodEnum)
+    method: MFAMethodEnum;
+}

package/src/lib/auth/dto/requests/signup.request.dto.ts

@@ -0,0 +1,42 @@
+import { IsEmail, IsString, IsOptional, IsNotEmpty, MinLength, ValidateIf } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class SignupRequestDto {
+    [x: string]: any;
+
+    @ApiPropertyOptional({
+        description: 'User email address (required if phone not provided)',
+        example: 'user@example.com',
+    })
+    @ValidateIf(o => !o.phone)
+    @IsEmail()
+    @IsNotEmpty()
+    email?: string;
+
+    @ApiPropertyOptional({
+        description: 'User phone number (required if email not provided)',
+        example: '+1234567890',
+    })
+    @ValidateIf(o => !o.email)
+    @IsString()
+    @IsNotEmpty()
+    phone?: string;
+
+    @ApiProperty({
+        description: 'User password',
+        example: 'SecurePass123!',
+        minLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    @MinLength(8)
+    password: string;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsString()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/toggle-mfa.request.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsBoolean, IsDefined } from 'class-validator';
+
+export class ToggleMfaRequestDto {
+    @ApiProperty({
+        description: 'Whether MFA should be enabled for the current user',
+        example: true,
+    })
+    @IsDefined()
+    @IsBoolean()
+    enabled: boolean;
+}

package/src/lib/auth/dto/requests/verify-2fa.request.dto.ts

@@ -0,0 +1,24 @@
+import { IsEnum, IsString, IsNotEmpty } from "class-validator";
+import { MFAMethodEnum } from "../../../core";
+import { ApiProperty } from "@nestjs/swagger";
+
+export class Verify2faRequestDto {
+    @ApiProperty({
+        description: 'MFA method used',
+        enum: MFAMethodEnum,
+        example: MFAMethodEnum.TOTP,
+        enumName: 'MFAMethodEnum',
+    })
+    @IsEnum(MFAMethodEnum)
+    method: MFAMethodEnum;
+
+    @ApiProperty({
+        description: 'One-time password code',
+        example: '123456',
+        minLength: 6,
+        maxLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    otp: string;
+}

package/src/lib/auth/dto/requests/verify-email.request.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsString, IsNotEmpty, IsUUID, IsOptional } from 'class-validator';
+
+export class VerifyEmailRequestDto {
+    @ApiProperty({
+        description: 'One-time password code received via email',
+        example: '123456',
+        minLength: 6,
+        maxLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    otp: string;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/verify-forgot-password-otp-request-dto.ts

@@ -0,0 +1,41 @@
+import { IsEmail, IsEnum, IsNotEmpty, IsOptional, IsPhoneNumber, IsString, IsUUID, ValidateIf } from "class-validator";
+import { MFAMethodEnum } from "../../../core";
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+
+export class VerifyForgotPasswordOtpRequestDto {
+    @ApiPropertyOptional({
+        description: 'User email address (required if phone not provided)',
+        example: 'user@example.com',
+    })
+    @ValidateIf(o => !o.phone)
+    @IsEmail()
+    @IsNotEmpty()
+    email?: string;
+
+    @ApiPropertyOptional({
+        description: 'User phone number (required if email not provided)',
+        example: '+1234567890',
+    })
+    @ValidateIf(o => !o.email)
+    @IsString()
+    @IsNotEmpty()
+    phone?: string;
+
+    @ApiProperty({
+        description: 'One-time password code received via email or SMS',
+        example: '123456',
+        minLength: 6,
+        maxLength: 8,
+    })
+    @IsString()
+    @IsNotEmpty()
+    otp: string;
+
+    @ApiPropertyOptional({
+        description: 'Tenant ID for multi-tenant applications',
+        example: '123e4567-e89b-12d3-a456-426614174000',
+    })
+    @IsUUID()
+    @IsOptional()
+    tenantId?: string;
+}

package/src/lib/auth/dto/requests/verify-totp-setup.request.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, IsNotEmpty } from "class-validator";
+
+export class VerifyTotpSetupRequestDto {
+    @ApiProperty({
+        description: 'The TOTP code from authenticator app',
+        example: '123456',
+        minLength: 6,
+        maxLength: 6,
+    })
+    @IsString()
+    @IsNotEmpty()
+    otp: string;
+
+    @ApiProperty({
+        description: 'Secret key from TOTP setup',
+        example: 'JBSWY3DPEHPK3PXP',
+    })
+    @IsString()
+    @IsNotEmpty()
+    secret: string;
+}

package/src/lib/auth/dto/responses/auth-cookie.response.dto.ts

@@ -0,0 +1,58 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+/**
+ * Auth Cookie Response DTO
+ *
+ * Used when `accessTokenType: 'cookie'` - tokens are set in HTTP-only cookies.
+ *
+ * Response Format:
+ * - Contains `message` and optionally `isRequiresMfa`
+ * - Does NOT contain `accessToken` or `refreshToken` (they're in cookies)
+ *
+ * Endpoints:
+ * - Login/Signup/Refresh: Returns `message` and `isRequiresMfa`
+ * - Verify 2FA: Returns only `message`
+ *
+ * Note: When using header mode (`accessTokenType: 'header'`),
+ * the response includes tokens AND message (see AuthWithTokensResponseDto).
+ *
+ * @example Cookie Mode - Login Response
+ * ```json
+ * {
+ *   "message": "Login successful",
+ *   "isRequiresMfa": false
+ * }
+ * ```
+ * Tokens are in Set-Cookie headers, not in response body.
+ *
+ * @example Header Mode - Login Response
+ * ```json
+ * {
+ *   "message": "Login successful",
+ *   "accessToken": "eyJhbGc...",
+ *   "refreshToken": "eyJhbGc...",
+ *   "isRequiresMfa": false
+ * }
+ * ```
+ * Tokens are in response body.
+ */
+export class AuthCookieResponseDto {
+    @ApiProperty({
+        description: 'Success message indicating the operation result',
+        example: 'Authentication successful',
+        examples: [
+            'Signup successful',
+            'Login successful',
+            'Token refreshed successfully',
+            '2FA verification successful'
+        ]
+    })
+    message: string;
+
+    @ApiPropertyOptional({
+        description: 'Whether multi-factor authentication is required (only for login/signup/refresh)',
+        example: false,
+        required: false
+    })
+    isRequiresMfa?: boolean;
+}

package/src/lib/auth/dto/responses/auth-success.response.dto.ts

@@ -0,0 +1,58 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+/**
+ * Auth Success Response DTO
+ *
+ * Used when `accessTokenType: 'cookie'` - tokens are set in HTTP-only cookies.
+ *
+ * Response Format:
+ * - Contains `message` and optionally `isRequiresMfa`
+ * - Does NOT contain `accessToken` or `refreshToken` (they're in cookies)
+ *
+ * Endpoints:
+ * - Login/Signup/Refresh: Returns `message` and `isRequiresMfa`
+ * - Verify 2FA: Returns only `message`
+ *
+ * Note: When using header mode (`accessTokenType: 'header'`),
+ * the response includes tokens AND message (see AuthResponseDto).
+ *
+ * @example Cookie Mode - Login Response
+ * ```json
+ * {
+ *   "message": "Login successful",
+ *   "isRequiresMfa": false
+ * }
+ * ```
+ * Tokens are in Set-Cookie headers, not in response body.
+ *
+ * @example Header Mode - Login Response
+ * ```json
+ * {
+ *   "message": "Login successful",
+ *   "accessToken": "eyJhbGc...",
+ *   "refreshToken": "eyJhbGc...",
+ *   "isRequiresMfa": false
+ * }
+ * ```
+ * Tokens are in response body.
+ */
+export class AuthSuccessResponseDto {
+    @ApiProperty({
+        description: 'Success message indicating the operation result',
+        example: 'Authentication successful',
+        examples: [
+            'Signup successful',
+            'Login successful',
+            'Token refreshed successfully',
+            '2FA verification successful'
+        ]
+    })
+    message: string;
+
+    @ApiPropertyOptional({
+        description: 'Whether multi-factor authentication is required (only for login/signup/refresh)',
+        example: false,
+        required: false
+    })
+    isRequiresMfa?: boolean;
+}