@nauth-toolkit/core 0.1.0

package/src/services/social-auth.service.spec.ts

@@ -0,0 +1,238 @@
+import { SocialAuthService } from './social-auth.service';
+import { ISocialAuthProviderService } from '../interfaces/social-auth-provider.interface';
+import { NAuthException } from '../exceptions/nauth.exception';
+import { AuthErrorCode } from '../enums/error-codes.enum';
+
+/**
+ * Social Auth Service Unit Tests
+ *
+ * Tests social authentication provider registry functionality.
+ * Covers provider registration, lookup, and listing.
+ *
+ * Platform-agnostic: Uses direct instantiation, no NestJS dependencies.
+ */
+describe('SocialAuthService', () => {
+  let service: SocialAuthService;
+  let mockProvider1: jest.Mocked<ISocialAuthProviderService>;
+  let mockProvider2: jest.Mocked<ISocialAuthProviderService>;
+
+  beforeEach(() => {
+    // Create mock providers
+    mockProvider1 = {
+      providerName: 'google',
+      getAuthUrl: jest.fn(),
+      handleCallback: jest.fn(),
+      verifyToken: jest.fn(),
+      linkAccount: jest.fn(),
+      getUserProfileFromCallback: jest.fn(),
+    } as any;
+
+    mockProvider2 = {
+      providerName: 'apple',
+      getAuthUrl: jest.fn(),
+      handleCallback: jest.fn(),
+      verifyToken: jest.fn(),
+      linkAccount: jest.fn(),
+      getUserProfileFromCallback: jest.fn(),
+    } as any;
+
+    // Instantiate service directly
+    service = new SocialAuthService();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  // ============================================================================
+  // Service Initialization
+  // ============================================================================
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  // ============================================================================
+  // registerProvider() Method
+  // ============================================================================
+
+  describe('registerProvider', () => {
+    it('should register provider successfully', () => {
+      service.registerProvider(mockProvider1);
+
+      expect(service.hasProvider('google')).toBe(true);
+    });
+
+    it('should throw error when provider already registered', () => {
+      service.registerProvider(mockProvider1);
+
+      expect(() => service.registerProvider(mockProvider1)).toThrow(NAuthException);
+      expect(() => service.registerProvider(mockProvider1)).toThrow('already registered');
+    });
+
+    it('should allow multiple different providers', () => {
+      service.registerProvider(mockProvider1);
+      service.registerProvider(mockProvider2);
+
+      expect(service.hasProvider('google')).toBe(true);
+      expect(service.hasProvider('apple')).toBe(true);
+    });
+
+    it('should register provider with correct name', () => {
+      service.registerProvider(mockProvider1);
+
+      const provider = service.getProvider('google');
+      expect(provider).toBe(mockProvider1);
+      expect(provider.providerName).toBe('google');
+    });
+  });
+
+  // ============================================================================
+  // getProvider() Method
+  // ============================================================================
+
+  describe('getProvider', () => {
+    it('should return registered provider', () => {
+      service.registerProvider(mockProvider1);
+
+      const provider = service.getProvider('google');
+
+      expect(provider).toBe(mockProvider1);
+    });
+
+    it('should throw error when provider not registered', () => {
+      expect(() => service.getProvider('google')).toThrow(NAuthException);
+      expect(() => service.getProvider('google')).toThrow('not registered');
+    });
+
+    it('should throw error with helpful message suggesting module import', () => {
+      try {
+        service.getProvider('facebook');
+        fail('Should have thrown NAuthException');
+      } catch (error: any) {
+        expect(error).toBeInstanceOf(NAuthException);
+        expect(error.message).toContain('Import the provider module');
+      }
+    });
+
+    it('should use correct error code when provider not found', () => {
+      try {
+        service.getProvider('google');
+      } catch (error) {
+        expect(error).toBeInstanceOf(NAuthException);
+        expect((error as NAuthException).code).toBe(AuthErrorCode.SOCIAL_CONFIG_MISSING);
+      }
+    });
+  });
+
+  // ============================================================================
+  // hasProvider() Method
+  // ============================================================================
+
+  describe('hasProvider', () => {
+    it('should return true for registered provider', () => {
+      service.registerProvider(mockProvider1);
+
+      expect(service.hasProvider('google')).toBe(true);
+    });
+
+    it('should return false for unregistered provider', () => {
+      expect(service.hasProvider('google')).toBe(false);
+    });
+
+    it('should return false for provider that was never registered', () => {
+      service.registerProvider(mockProvider1);
+
+      expect(service.hasProvider('facebook')).toBe(false);
+    });
+  });
+
+  // ============================================================================
+  // listProviders() Method
+  // ============================================================================
+
+  describe('listProviders', () => {
+    it('should return empty array when no providers registered', () => {
+      expect(service.listProviders()).toEqual([]);
+    });
+
+    it('should return all registered provider names', () => {
+      service.registerProvider(mockProvider1);
+      service.registerProvider(mockProvider2);
+
+      const providers = service.listProviders();
+
+      expect(providers).toContain('google');
+      expect(providers).toContain('apple');
+      expect(providers.length).toBe(2);
+    });
+
+    it('should return provider names in registration order', () => {
+      service.registerProvider(mockProvider1);
+      service.registerProvider(mockProvider2);
+
+      const providers = service.listProviders();
+
+      expect(providers[0]).toBe('google');
+      expect(providers[1]).toBe('apple');
+    });
+
+    it('should return updated list after new provider registered', () => {
+      expect(service.listProviders()).toEqual([]);
+
+      service.registerProvider(mockProvider1);
+      expect(service.listProviders()).toEqual(['google']);
+
+      service.registerProvider(mockProvider2);
+      expect(service.listProviders()).toEqual(['google', 'apple']);
+    });
+  });
+
+  // ============================================================================
+  // Integration Tests
+  // ============================================================================
+
+  describe('Integration', () => {
+    it('should allow full provider lifecycle', () => {
+      // Register
+      service.registerProvider(mockProvider1);
+      expect(service.hasProvider('google')).toBe(true);
+
+      // Get
+      const provider = service.getProvider('google');
+      expect(provider).toBe(mockProvider1);
+
+      // List
+      const providers = service.listProviders();
+      expect(providers).toContain('google');
+    });
+
+    it('should handle multiple providers independently', () => {
+      service.registerProvider(mockProvider1);
+      service.registerProvider(mockProvider2);
+
+      const googleProvider = service.getProvider('google');
+      const appleProvider = service.getProvider('apple');
+
+      expect(googleProvider).toBe(mockProvider1);
+      expect(appleProvider).toBe(mockProvider2);
+      expect(googleProvider).not.toBe(appleProvider);
+    });
+
+    it('should maintain provider registry across operations', () => {
+      service.registerProvider(mockProvider1);
+      service.registerProvider(mockProvider2);
+
+      // Verify both still registered
+      expect(service.hasProvider('google')).toBe(true);
+      expect(service.hasProvider('apple')).toBe(true);
+
+      // Get both
+      const google = service.getProvider('google');
+      const apple = service.getProvider('apple');
+
+      expect(google).toBe(mockProvider1);
+      expect(apple).toBe(mockProvider2);
+    });
+  });
+});

package/src/services/social-auth.service.ts

@@ -0,0 +1,436 @@
+import { Repository } from 'typeorm';
+import { IUser, ISocialAccount } from '../interfaces/entities.interface';
+import { BaseUser, BaseSocialAccount } from '../entities';
+import { AuthService } from './auth.service';
+import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
+import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
+import { NAuthException } from '../exceptions/nauth.exception';
+import { AuthErrorCode } from '../enums/error-codes.enum';
+import { NAuthLogger } from '../utils/nauth-logger';
+import { ChangePasswordRequestDTO } from '../dto/change-password-request.dto';
+import { SocialProviderRegistry } from './social-provider-registry.service';
+import { AuthResponseDTO } from '../dto/auth-response.dto';
+import {
+  GetSocialAuthUrlDTO,
+  GetSocialAuthUrlResponseDTO,
+  HandleSocialCallbackDTO,
+  LinkSocialAccountDTO,
+  LinkSocialAccountResponseDTO,
+  GetLinkedAccountsDTO,
+  GetLinkedAccountsResponseDTO,
+  UnlinkSocialAccountDTO,
+  UnlinkSocialAccountResponseDTO,
+  CanSetPasswordDTO,
+  CanSetPasswordResponseDTO,
+  SetPasswordForSocialUserDTO,
+  SetPasswordForSocialUserResponseDTO,
+} from '../dto/social-auth.dto';
+
+/**
+ * Social Auth Service
+ *
+ * Complete API for social authentication (OAuth) and account management.
+ * This service provides:
+ * - OAuth authentication flows (login/signup via social providers)
+ * - Social account linking/unlinking
+ * - Account management for social users
+ * - Password management for social-only users
+ *
+ * **Optional Feature:** Only available when social auth provider modules are imported.
+ *
+ * **Usage:**
+ * ```typescript
+ * // NestJS
+ * imports: [
+ *   AuthModule.forRoot(config),
+ *   GoogleSocialAuthModule,  // Enables Google OAuth
+ *   AppleSocialAuthModule,   // Enables Apple Sign In
+ * ]
+ *
+ * // Then inject and use
+ * constructor(private socialAuthService: SocialAuthService) {}
+ *
+ * const { url } = await this.socialAuthService.getSocialAuthUrl({ provider: 'google' });
+ * const result = await this.socialAuthService.handleSocialCallback({ provider: 'google', code, state });
+ * ```
+ */
+export class SocialAuthService {
+  constructor(
+    private readonly providerRegistry: SocialProviderRegistry,
+    private readonly userRepository: Repository<BaseUser>,
+    private readonly socialAccountRepository: Repository<BaseSocialAccount>,
+    private readonly authService: AuthService,
+    private readonly logger: NAuthLogger,
+    private readonly auditService?: AuthAuditService, // Optional - audit trail service (enabled via config.auditLogs.enabled)
+  ) {}
+
+  // ============================================================================
+  // Social Authentication Methods
+  // ============================================================================
+
+  /**
+   * Get social authentication URL
+   *
+   * Generates OAuth authorization URL for the specified provider.
+   * This is the first step in the OAuth flow - redirect user to this URL.
+   *
+   * @param dto - Request DTO containing provider and optional state
+   * @returns Response DTO with OAuth authorization URL
+   * @throws {NAuthException} SOCIAL_CONFIG_MISSING if provider not registered or configured
+   *
+   * @example
+   * ```typescript
+   * const dto = { provider: 'google', state: 'csrf-token-123' };
+   * const { url } = await socialAuthService.getSocialAuthUrl(dto);
+   * // Redirect user to url
+   * res.redirect(url);
+   * ```
+   */
+  async getSocialAuthUrl(dto: GetSocialAuthUrlDTO): Promise<GetSocialAuthUrlResponseDTO> {
+    const { provider, state } = dto;
+    const providerInstance = this.providerRegistry.getProvider(provider);
+    const url = await providerInstance.getAuthUrl(state);
+    return { url };
+  }
+
+  /**
+   * Handle social authentication callback
+   *
+   * Processes OAuth callback and authenticates user (login or signup).
+   * This is called after the user is redirected back from the OAuth provider.
+   *
+   * @param dto - Request DTO containing provider, code, and state
+   * @returns Auth response (tokens or challenge if MFA/verification required)
+   * @throws {NAuthException} Various auth errors (SOCIAL_AUTH_FAILED, etc.)
+   *
+   * @example
+   * ```typescript
+   * const dto = {
+   *   provider: 'google',
+   *   code: req.query.code,
+   *   state: req.query.state
+   * };
+   * const result = await socialAuthService.handleSocialCallback(dto);
+   * // Returns tokens or challenge
+   * ```
+   */
+  async handleSocialCallback(dto: HandleSocialCallbackDTO): Promise<AuthResponseDTO> {
+    const { provider, code, state } = dto;
+    const providerInstance = this.providerRegistry.getProvider(provider);
+    return await providerInstance.handleCallback(code, state);
+  }
+
+  /**
+   * Link social account to existing authenticated user
+   *
+   * Connects a social provider to an already logged-in user's account.
+   * User must be authenticated before calling this method.
+   *
+   * @param dto - Request DTO containing userId, provider, code, and state
+   * @returns Response DTO with success message and provider name
+   * @throws {NAuthException} SOCIAL_ALREADY_LINKED, NOT_FOUND, etc.
+   *
+   * @example
+   * ```typescript
+   * const dto = {
+   *   userId: user.sub,
+   *   provider: 'apple',
+   *   code: req.query.code,
+   *   state: req.query.state
+   * };
+   * const result = await socialAuthService.linkSocialAccount(dto);
+   * ```
+   */
+  async linkSocialAccount(dto: LinkSocialAccountDTO): Promise<LinkSocialAccountResponseDTO> {
+    const { userId, provider, code, state } = dto;
+    const providerInstance = this.providerRegistry.getProvider(provider);
+    const result = await providerInstance.linkAccount(userId, code, state);
+    return { ...result, provider };
+  }
+
+  /**
+   * List available social auth providers
+   *
+   * Returns names of all registered and enabled social auth providers.
+   * Useful for displaying available login options in the UI.
+   *
+   * @returns Array of provider names (e.g., ['google', 'apple', 'facebook'])
+   *
+   * @example
+   * ```typescript
+   * const providers = socialAuthService.listAvailableProviders();
+   * // Display social login buttons based on available providers
+   * ```
+   */
+  listAvailableProviders(): string[] {
+    return this.providerRegistry.listProviders();
+  }
+
+  // ============================================================================
+  // Social Account Management Methods
+  // ============================================================================
+
+  /**
+   * Get linked social accounts for a user
+   *
+   * @param dto - Request DTO containing userId
+   * @returns Response DTO with array of linked social accounts
+   * @throws {NAuthException} NOT_FOUND when user is not found
+   *
+   * @example
+   * ```typescript
+   * const dto = { userId: 'user-uuid' };
+   * const accounts = await socialAuthService.getLinkedAccounts(dto);
+   * console.log(accounts.accounts); // [{ provider: 'google', ... }]
+   * ```
+   */
+  async getLinkedAccounts(dto: GetLinkedAccountsDTO): Promise<GetLinkedAccountsResponseDTO> {
+    const { userId } = dto;
+    const user = (await this.userRepository.findOne({ where: { sub: userId } })) as IUser | null;
+    if (!user) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+    }
+
+    const socialAccounts = (await this.socialAccountRepository.find({
+      where: { userId: user.id },
+      order: { linkedAt: 'DESC' },
+    })) as ISocialAccount[];
+
+    return {
+      accounts: socialAccounts.map((account) => ({
+        provider: account.provider,
+        providerEmail: account.providerEmail || undefined,
+        linkedAt: account.linkedAt,
+        lastUsedAt: account.lastUsedAt || undefined,
+      })),
+    };
+  }
+
+  /**
+   * Unlink social account from user
+   *
+   * @param dto - Request DTO containing userId and provider
+   * @returns Response DTO with success message
+   * @throws {NAuthException} NOT_FOUND when user or account is not found
+   *
+   * @example
+   * ```typescript
+   * const dto = { userId: 'user-uuid', provider: 'google' };
+   * await socialAuthService.unlinkSocialAccount(dto);
+   * ```
+   */
+  async unlinkSocialAccount(dto: UnlinkSocialAccountDTO): Promise<UnlinkSocialAccountResponseDTO> {
+    const { userId, provider } = dto;
+    const user = (await this.userRepository.findOne({ where: { sub: userId } })) as IUser | null;
+    if (!user) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+    }
+
+    const socialAccount = (await this.socialAccountRepository.findOne({
+      where: { userId: user.id, provider },
+    })) as ISocialAccount | null;
+
+    if (!socialAccount) {
+      throw new NAuthException(
+        AuthErrorCode.SOCIAL_ACCOUNT_NOT_FOUND,
+        `${provider} account is not linked to this user`,
+      );
+    }
+
+    // Delete social account
+    await this.socialAccountRepository.remove(socialAccount);
+
+    // Update user's social auth flags
+    await this.updateUserSocialFlags(user.id as number);
+
+    // ============================================================================
+    // Audit: Record social account unlink
+    // ============================================================================
+    try {
+      await this.auditService?.recordEvent({
+        userId: user.id,
+        eventType: AuthAuditEventType.SOCIAL_ACCOUNT_UNLINKED,
+        eventStatus: 'INFO',
+        authMethod: provider,
+        // Client info automatically included from context
+        metadata: {
+          provider,
+          providerEmail: socialAccount.providerEmail || null,
+        },
+      });
+    } catch (auditError) {
+      // Non-blocking: Log but continue
+      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
+      this.logger?.error?.(`Failed to record SOCIAL_ACCOUNT_UNLINKED audit event: ${errorMessage}`, {
+        error: auditError,
+        userId: user.id,
+        provider,
+      });
+    }
+
+    return { message: `${provider} account unlinked successfully` };
+  }
+
+  /**
+   * Check if user can set a password
+   * Users with social-only accounts can set passwords
+   *
+   * @param dto - Request DTO containing userId
+   * @returns Response DTO indicating whether user can set password
+   *
+   * @example
+   * ```typescript
+   * const dto = { userId: 'user-uuid' };
+   * const result = await socialAuthService.canSetPassword(dto);
+   * if (result.canSetPassword) {
+   *   // Allow user to set password
+   * }
+   * ```
+   */
+  async canSetPassword(dto: CanSetPasswordDTO): Promise<CanSetPasswordResponseDTO> {
+    const { userId } = dto;
+    const user = (await this.userRepository.findOne({ where: { sub: userId } })) as IUser | null;
+    if (!user) {
+      return { canSetPassword: false };
+    }
+
+    // User can set password if they don't have one (social-only account)
+    return { canSetPassword: !user.passwordHash };
+  }
+
+  /**
+   * Set password for social-only user
+   *
+   * @param dto - Request DTO containing userId and password
+   * @returns Response DTO with success message
+   * @throws {NAuthException} NOT_FOUND when user is not found
+   * @throws {NAuthException} VALIDATION_FAILED when user already has a password
+   *
+   * @example
+   * ```typescript
+   * const dto = { userId: 'user-uuid', password: 'newpassword' };
+   * await socialAuthService.setPasswordForSocialUser(dto);
+   * ```
+   */
+  async setPasswordForSocialUser(dto: SetPasswordForSocialUserDTO): Promise<SetPasswordForSocialUserResponseDTO> {
+    const { userId, password } = dto;
+    const user = await this.userRepository.findOne({ where: { sub: userId } });
+    if (!user) {
+      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
+    }
+
+    if (user.passwordHash) {
+      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'User already has a password', {
+        field: 'password',
+      });
+    }
+
+    // Use AuthService to set password (includes validation and hashing)
+    // For social-only users, we bypass old password validation since they don't have one
+    // Note: This requires type casting as ChangePasswordRequestDTO requires oldPassword, but
+    // the auth service will handle the case where user has no passwordHash
+    const changePasswordDto = new ChangePasswordRequestDTO();
+    changePasswordDto.sub = userId; // userId is the sub (external UUID) in this context
+    changePasswordDto.oldPassword = ''; // Social-only users don't have a password
+    changePasswordDto.newPassword = password;
+    await this.authService.changePassword(changePasswordDto);
+
+    return { message: 'Password set successfully' };
+  }
+
+  /**
+   * Find social account by provider and provider ID
+   *
+   * @param provider - Provider name (e.g., 'google', 'apple')
+   * @param providerId - Provider user ID
+   * @returns Social account with user relation, or null
+   * @internal - For use by BaseSocialAuthProviderService
+   */
+  async findSocialAccountByProvider(provider: string, providerId: string): Promise<ISocialAccount | null> {
+    return (await this.socialAccountRepository.findOne({
+      where: { provider, providerId },
+      relations: ['user'],
+    })) as ISocialAccount | null;
+  }
+
+  /**
+   * Find social account by user ID and provider
+   *
+   * @param userId - User ID (internal)
+   * @param provider - Provider name
+   * @returns Social account or null
+   * @internal - For use by BaseSocialAuthProviderService
+   */
+  async findSocialAccountByUser(userId: number, provider: string): Promise<ISocialAccount | null> {
+    return (await this.socialAccountRepository.findOne({
+      where: { userId, provider },
+    })) as ISocialAccount | null;
+  }
+
+  /**
+   * Create or update social account
+   *
+   * @param userId - User ID (internal)
+   * @param provider - Provider name
+   * @param providerId - Provider user ID
+   * @param providerEmail - Provider email
+   * @param metadata - Optional raw profile data
+   * @internal - For use by BaseSocialAuthProviderService
+   */
+  async createOrUpdateSocialAccount(
+    userId: number,
+    provider: string,
+    providerId: string,
+    providerEmail?: string | null,
+    metadata?: any,
+  ): Promise<void> {
+    const existingAccount = await this.findSocialAccountByUser(userId, provider);
+
+    if (existingAccount) {
+      // Update existing account
+      existingAccount.providerEmail = providerEmail || null;
+      existingAccount.lastUsedAt = new Date();
+      existingAccount.metadata = metadata || null;
+      await this.socialAccountRepository.save(existingAccount);
+    } else {
+      // Create new account
+      const socialAccount = this.socialAccountRepository.create({
+        userId,
+        provider,
+        providerId,
+        providerEmail: providerEmail || null,
+        linkedAt: new Date(),
+        lastUsedAt: new Date(),
+        metadata: metadata || null,
+      });
+
+      await this.socialAccountRepository.save(socialAccount);
+    }
+
+    // Update user's social auth flags
+    await this.updateUserSocialFlags(userId);
+  }
+
+  /**
+   * Update user's social authentication flags
+   *
+   * @param userId - User ID (internal)
+   * @internal - For use by BaseSocialAuthProviderService
+   */
+  async updateUserSocialFlags(userId: number): Promise<void> {
+    const socialAccounts = (await this.socialAccountRepository.find({
+      where: { userId },
+    })) as ISocialAccount[];
+
+    const providers = socialAccounts?.map((account) => account.provider) || [];
+    const hasSocialAuth = socialAccounts && socialAccounts.length > 0;
+
+    // Use save() instead of update() to ensure TypeORM properly serializes simple-array fields
+    const user = await this.userRepository.findOne({ where: { id: userId } });
+    if (user) {
+      user.hasSocialAuth = hasSocialAuth;
+      user.socialProviders = providers.length > 0 ? providers : null;
+      await this.userRepository.save(user);
+    }
+  }
+}