valtech-components 2.0.795 → 2.0.796

package/src/lib/services/auth/auth.service.ts

@@ -1,1387 +0,0 @@
-import { Injectable, Inject, OnDestroy, Optional } from '@angular/core';
-import { HttpClient, HttpErrorResponse } from '@angular/common/http';
-import { Router } from '@angular/router';
-import { Observable, throwError, of, from, firstValueFrom, Subscription } from 'rxjs';
-import { tap, catchError, switchMap, map } from 'rxjs/operators';
-
-import { VALTECH_AUTH_CONFIG } from './config';
-import { AuthStateService } from './auth-state.service';
-import { TokenService } from './token.service';
-import { AuthStorageService } from './storage.service';
-import { AuthSyncService } from './sync.service';
-import {
-  SigninRequest,
-  SigninResponse,
-  SignupRequest,
-  SignupResponse,
-  VerifyEmailRequest,
-  VerifyEmailResponse,
-  ResendCodeRequest,
-  ResendCodeResponse,
-  MFAVerifyResponse,
-  RefreshResponse,
-  GetPermissionsResponse,
-  GetProfileResponse,
-  UpdateProfileRequest,
-  UpdateProfileResponse,
-  MFASetupResponse,
-  MFAConfirmResponse,
-  MFADisableResponse,
-  ForgotPasswordRequest,
-  ForgotPasswordResponse,
-  ResetPasswordRequest,
-  ResetPasswordResponse,
-  ChangePasswordRequest,
-  ChangePasswordResponse,
-  DeleteAccountRequest,
-  DeleteAccountResponse,
-  SwitchOrgResponse,
-  MFAMethod,
-  AuthError,
-  AuthSyncEvent,
-  ValtechAuthConfig,
-  RegisterDeviceResponse,
-  EnableNotificationsResult,
-  NotificationPermissionState,
-  RegisterDeviceResult,
-  // TOTP MFA types
-  TOTPSetupResponse,
-  TOTPVerifySetupResponse,
-  TOTPDisableResponse,
-  RegenerateBackupCodesResponse,
-  BackupCodesCountResponse,
-  // OAuth types
-  OAuthProvider,
-  OAuthResult,
-  LinkedProvider,
-  HasPasswordResponse,
-  // Handle types
-  UpdateHandleResponse,
-  CheckHandleResponse,
-  // Avatar types
-  UpdateAvatarRequest,
-  UpdateAvatarResponse,
-} from './types';
-import { OAuthService } from './oauth.service';
-import { FirebaseService, MessagingService } from '../firebase';
-import { I18nService, I18nLang } from '../i18n';
-import { ConfirmationDialogService } from '../confirmation-dialog/confirmation-dialog.service';
-
-/**
- * Servicio principal de autenticación.
- *
- * @example
- * ```typescript
- * import { AuthService } from 'valtech-components';
- *
- * @Component({...})
- * export class LoginComponent {
- *   private auth = inject(AuthService);
- *
- *   async login() {
- *     await firstValueFrom(this.auth.signin({ email, password }));
- *     if (this.auth.mfaPending().required) {
- *       // Mostrar UI de MFA
- *     } else {
- *       this.router.navigate(['/']);
- *     }
- *   }
- * }
- * ```
- */
-@Injectable({ providedIn: 'root' })
-export class AuthService implements OnDestroy {
-  // Timer para refresh proactivo
-  private refreshTimerId: ReturnType<typeof setTimeout> | null = null;
-  private syncSubscription: Subscription | null = null;
-
-  constructor(
-    @Inject(VALTECH_AUTH_CONFIG) private config: ValtechAuthConfig,
-    private http: HttpClient,
-    private router: Router,
-    private stateService: AuthStateService,
-    private tokenService: TokenService,
-    private storageService: AuthStorageService,
-    private syncService: AuthSyncService,
-    private firebaseService: FirebaseService,
-    private oauthService: OAuthService,
-    @Optional() private messagingService: MessagingService | null,
-    @Optional() private i18nService: I18nService | null,
-    private confirmationService: ConfirmationDialogService
-  ) {}
-
-  // =============================================
-  // ESTADO PÚBLICO (Signals readonly)
-  // =============================================
-
-  /** Estado completo de autenticación */
-  readonly state = this.stateService.state;
-
-  /** Usuario está autenticado */
-  readonly isAuthenticated = this.stateService.isAuthenticated;
-
-  /** Estado de carga */
-  readonly isLoading = this.stateService.isLoading;
-
-  /** Información del usuario */
-  readonly user = this.stateService.user;
-
-  /** Token de acceso */
-  readonly accessToken = this.stateService.accessToken;
-
-  /** Roles del usuario */
-  readonly roles = this.stateService.roles;
-
-  /** Permisos del usuario */
-  readonly permissions = this.stateService.permissions;
-
-  /** Usuario es super admin */
-  readonly isSuperAdmin = this.stateService.isSuperAdmin;
-
-  /** Estado de MFA pendiente */
-  readonly mfaPending = this.stateService.mfaPending;
-
-  /** Error actual */
-  readonly error = this.stateService.error;
-
-  // =============================================
-  // INICIALIZACIÓN
-  // =============================================
-
-  /**
-   * Inicializa el servicio de autenticación.
-   * Llamado automáticamente por provideValtechAuth.
-   */
-  async initialize(): Promise<void> {
-    // 1. Cargar estado desde storage
-    const storedState = this.storageService.loadState();
-
-    if (storedState.accessToken) {
-      // 2. Verificar si token es válido
-      if (this.tokenService.isTokenValid(storedState.accessToken)) {
-        this.stateService.restoreFromStorage(storedState);
-
-        // Extraer info del token
-        const claims = this.tokenService.parseToken(storedState.accessToken);
-        if (claims) {
-          this.stateService.updateUserInfo(claims.uid, claims.email);
-        }
-
-        // 3. Iniciar timer de refresco proactivo
-        this.startRefreshTimer();
-      } else if (storedState.refreshToken) {
-        // 4. Token expirado pero hay refresh token - intentar refrescar
-        try {
-          await firstValueFrom(this.refreshAccessToken());
-        } catch {
-          this.signOutFirebase();
-          this.clearState();
-        }
-      } else {
-        this.signOutFirebase();
-        this.clearState();
-      }
-    }
-
-    // 5. Iniciar sincronización entre pestañas
-    if (this.config.enableTabSync) {
-      this.syncService.start();
-      this.syncSubscription = this.syncService.onEvent$.subscribe(event =>
-        this.handleSyncEvent(event)
-      );
-    }
-
-    this.stateService.setLoading(false);
-  }
-
-  ngOnDestroy(): void {
-    this.stopRefreshTimer();
-    this.syncSubscription?.unsubscribe();
-  }
-
-  // =============================================
-  // AUTENTICACIÓN
-  // =============================================
-
-  /**
-   * Inicia sesión con email y contraseña.
-   * Detecta automáticamente la plataforma para identificar dispositivos nuevos.
-   */
-  signin(request: SigninRequest): Observable<SigninResponse> {
-    this.stateService.clearError();
-
-    // Agregar info de plataforma para device detection
-    const platformInfo = this.detectPlatformInfo();
-    const enrichedRequest: SigninRequest = {
-      ...request,
-      platform: request.platform ?? platformInfo.platform,
-      browser: request.browser ?? platformInfo.browser,
-      os: request.os ?? platformInfo.os,
-    };
-
-    return this.http.post<SigninResponse>(`${this.baseUrl}/signin`, enrichedRequest).pipe(
-      tap(response => {
-        if (response.mfaRequired) {
-          // MFA requerido - guardar estado temporal
-          this.stateService.setMFAPending({
-            required: true,
-            mfaToken: response.mfaToken!,
-            method: response.mfaMethod!,
-          });
-        } else if (response.accessToken) {
-          // Login exitoso sin MFA
-          this.handleSuccessfulAuth(response);
-
-          // Notificar si es un dispositivo nuevo
-          if (response.isNewDevice) {
-            console.log('[ValtechAuth] New device detected:', response.deviceId);
-          }
-        }
-      }),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  // =============================================
-  // OAUTH (Login social)
-  // =============================================
-
-  /**
-   * Inicia sesión con OAuth (Google, Apple, Microsoft).
-   * Abre un popup para el flujo de autenticación.
-   *
-   * @param provider - Proveedor OAuth ('google', 'apple', 'microsoft')
-   * @returns Observable que emite SigninResponse cuando se completa
-   *
-   * @example
-   * ```typescript
-   * this.auth.signinWithOAuth('google').subscribe({
-   *   next: () => this.router.navigate(['/']),
-   *   error: (err) => console.error('OAuth failed:', err)
-   * });
-   * ```
-   */
-  signinWithOAuth(provider: OAuthProvider): Observable<SigninResponse> {
-    this.stateService.clearError();
-
-    return this.oauthService.startFlow(provider).pipe(
-      tap(result => {
-        // DEBUG: Log OAuth result to check firebaseToken
-        console.log('[ValtechAuth] OAuth result received:', {
-          hasAccessToken: !!result.accessToken,
-          hasRefreshToken: !!result.refreshToken,
-          hasFirebaseToken: !!result.firebaseToken,
-          firebaseTokenLength: result.firebaseToken?.length || 0,
-        });
-
-        // Convertir OAuthResult a SigninResponse compatible
-        const response: SigninResponse = {
-          operationId: 'oauth',
-          accessToken: result.accessToken,
-          refreshToken: result.refreshToken,
-          firebaseToken: result.firebaseToken,
-          expiresIn: result.expiresIn,
-          roles: result.roles,
-          permissions: result.permissions,
-        };
-        this.handleSuccessfulAuth(response);
-      }),
-      map(
-        result =>
-          ({
-            operationId: 'oauth',
-            accessToken: result.accessToken,
-            refreshToken: result.refreshToken,
-            firebaseToken: result.firebaseToken,
-            expiresIn: result.expiresIn,
-            roles: result.roles,
-            permissions: result.permissions,
-          }) as SigninResponse
-      ),
-      catchError(error => {
-        const authError: AuthError = {
-          code: error.code || 'OAUTH_ERROR',
-          message: error.message || 'Error de autenticación OAuth',
-        };
-        this.stateService.setError(authError);
-        return throwError(() => authError);
-      })
-    );
-  }
-
-  /**
-   * Vincula un proveedor OAuth adicional a la cuenta actual.
-   * Requiere que el usuario esté autenticado.
-   *
-   * @param provider - Proveedor OAuth a vincular
-   */
-  linkOAuthProvider(provider: OAuthProvider): Observable<{ success: boolean }> {
-    return this.oauthService.startLinkFlow(provider).pipe(
-      map(() => ({ success: true })),
-      catchError(error => {
-        const authError: AuthError = {
-          code: error.code || 'LINK_ERROR',
-          message: error.message || 'Error al vincular proveedor',
-        };
-        this.stateService.setError(authError);
-        return throwError(() => authError);
-      })
-    );
-  }
-
-  /**
-   * Obtiene los proveedores OAuth vinculados al usuario.
-   */
-  getLinkedProviders(): Observable<LinkedProvider[]> {
-    return this.oauthService.getLinkedProviders();
-  }
-
-  /**
-   * Desvincula un proveedor OAuth de la cuenta.
-   *
-   * @param provider - Proveedor a desvincular
-   */
-  unlinkOAuthProvider(provider: OAuthProvider): Observable<{ success: boolean }> {
-    return this.oauthService.unlinkProvider(provider);
-  }
-
-  /**
-   * Establece contraseña para usuarios que solo tienen OAuth.
-   * Permite que usuarios OAuth-only puedan también usar email/password.
-   *
-   * @param password - Nueva contraseña
-   */
-  setPasswordForOAuthUser(password: string): Observable<{ success: boolean }> {
-    return this.oauthService.setPassword(password);
-  }
-
-  /**
-   * Verifica si el usuario tiene contraseña establecida.
-   * Útil para mostrar/ocultar opciones de cambio de contraseña.
-   */
-  checkHasPassword(): Observable<HasPasswordResponse> {
-    return this.oauthService.hasPassword();
-  }
-
-  /**
-   * Registra un nuevo usuario.
-   * El usuario queda en estado PENDING hasta verificar su email.
-   */
-  signup(request: SignupRequest): Observable<SignupResponse> {
-    this.stateService.clearError();
-
-    return this.http
-      .post<SignupResponse>(`${this.baseUrl}/signup`, request)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Verifica email con código de 6 dígitos.
-   * Si es exitoso, hace auto-login y retorna tokens.
-   */
-  verifyEmail(request: VerifyEmailRequest): Observable<VerifyEmailResponse> {
-    this.stateService.clearError();
-
-    return this.http.post<VerifyEmailResponse>(`${this.baseUrl}/verify-email`, request).pipe(
-      tap(response => {
-        if (response.verified && response.accessToken) {
-          // Auto-login: guardar tokens y actualizar estado
-          this.handleSuccessfulAuth(response as unknown as SigninResponse);
-        }
-      }),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  /**
-   * Reenvía código de verificación al email.
-   */
-  resendCode(request: ResendCodeRequest): Observable<ResendCodeResponse> {
-    return this.http
-      .post<ResendCodeResponse>(`${this.baseUrl}/resend-code`, request)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Verifica código MFA.
-   */
-  verifyMFA(code: string): Observable<MFAVerifyResponse> {
-    const mfaState = this.mfaPending();
-    if (!mfaState.mfaToken) {
-      return throwError(() => ({
-        code: 'MFA_NOT_PENDING',
-        message: 'No hay verificación MFA pendiente',
-      }));
-    }
-
-    return this.http
-      .post<MFAVerifyResponse>(`${this.baseUrl}/mfa/verify`, {
-        mfaToken: mfaState.mfaToken,
-        code,
-      })
-      .pipe(
-        tap(response => {
-          this.stateService.clearMFAPending();
-          this.handleSuccessfulAuth(response);
-        }),
-        catchError(error => this.handleAuthError(error))
-      );
-  }
-
-  /**
-   * Refresca el token de acceso.
-   * Implementa token rotation: cada refresh genera un nuevo refresh token
-   * que el cliente debe guardar para el próximo refresh.
-   */
-  refreshAccessToken(): Observable<RefreshResponse> {
-    const refreshToken = this.state().refreshToken;
-    if (!refreshToken) {
-      return throwError(() => ({
-        code: 'NO_REFRESH_TOKEN',
-        message: 'No hay token de refresco',
-      }));
-    }
-
-    return this.http.post<RefreshResponse>(`${this.baseUrl}/refresh`, { refreshToken }).pipe(
-      tap(response => {
-        const expiresAt = Date.now() + response.expiresIn * 1000;
-
-        // Token rotation: guardar nuevo access token Y refresh token
-        this.stateService.updateAccessToken(response.accessToken, response.expiresIn);
-        this.stateService.updateRefreshToken(response.refreshToken); // NUEVO: guardar refresh rotado
-        this.storageService.saveAccessToken(response.accessToken, expiresAt);
-        this.storageService.saveRefreshToken(response.refreshToken); // NUEVO: persistir refresh rotado
-
-        if (this.config.enableFirebaseIntegration && response.firebaseToken) {
-          this.signInWithFirebase(response.firebaseToken);
-        }
-
-        this.startRefreshTimer();
-        this.syncService.broadcast({
-          type: 'TOKEN_REFRESH',
-          payload: {
-            accessToken: response.accessToken,
-            refreshToken: response.refreshToken, // NUEVO: sincronizar entre tabs
-            expiresAt,
-          },
-        });
-      }),
-      catchError(error => {
-        this.logout();
-        return throwError(() => error);
-      })
-    );
-  }
-
-  /**
-   * Maneja autenticación exitosa desde fuentes externas (OAuth, etc).
-   * Guarda tokens, actualiza estado, inicia Firebase si corresponde.
-   *
-   * @param authResult - Resultado de autenticación con tokens
-   *
-   * @example
-   * ```typescript
-   * // Desde un flujo OAuth externo
-   * externalOAuth.signIn().subscribe({
-   *   next: (result) => {
-   *     this.authService.setExternalAuth(result);
-   *   }
-   * });
-   * ```
-   */
-  setExternalAuth(authResult: {
-    accessToken: string;
-    refreshToken: string;
-    firebaseToken?: string;
-    expiresIn: number;
-    roles?: string[];
-    permissions?: string[];
-  }): void {
-    this.handleSuccessfulAuth({
-      ...authResult,
-      operationId: 'external-auth',
-      tokenType: 'Bearer',
-    } as SigninResponse);
-  }
-
-  /**
-   * Cierra sesión tras pedir confirmación al usuario.
-   *
-   * Muestra un diálogo nativo (estilo destructivo). Si el usuario confirma,
-   * ejecuta `logout()`. Si cancela, no pasa nada.
-   *
-   * Texto por defecto desde `_global` i18n: `logoutConfirmTitle`,
-   * `logoutConfirmMessage`, `logout`, `cancel`. Override via `opts`.
-   *
-   * @returns true si el usuario confirmó (logout ejecutado), false si canceló.
-   *
-   * @example
-   * onLogoutClick() { this.auth.logoutWithConfirmation(); }
-   */
-  async logoutWithConfirmation(opts?: {
-    title?: string;
-    message?: string;
-    confirmText?: string;
-    cancelText?: string;
-  }): Promise<boolean> {
-    const t = (key: string, fallback: string) => this.i18nService?.t(key) || fallback;
-    const result = await this.confirmationService.confirmDestructive({
-      title: opts?.title ?? t('logoutConfirmTitle', 'Cerrar sesión'),
-      message: opts?.message ?? t('logoutConfirmMessage', '¿Seguro que deseas cerrar sesión?'),
-      confirmButton: { text: opts?.confirmText ?? t('logout', 'Cerrar sesión') },
-      cancelButton: { text: opts?.cancelText ?? t('cancel', 'Cancelar') },
-    });
-
-    if (result.confirmed) {
-      await this.logout();
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Cierra sesión.
-   */
-  async logout(): Promise<void> {
-    const refreshToken = this.state().refreshToken;
-
-    // Eliminar dispositivo del backend antes de cerrar sesión
-    await this.unregisterDevice();
-
-    // Notificar al backend (fire and forget)
-    if (refreshToken) {
-      this.http
-        .post(`${this.baseUrl}/logout`, { refreshToken })
-        .pipe(catchError(() => of(null)))
-        .subscribe();
-    }
-
-    // Cerrar sesión de Firebase si está integrado
-    this.signOutFirebase();
-
-    this.clearState();
-    this.syncService.broadcast({ type: 'LOGOUT' });
-    this.router.navigate([this.config.loginRoute]);
-  }
-
-  // =============================================
-  // MFA SETUP (usuario autenticado)
-  // =============================================
-
-  /**
-   * Configura MFA para el usuario.
-   */
-  setupMFA(method: MFAMethod, phone?: string): Observable<MFASetupResponse> {
-    return this.http
-      .post<MFASetupResponse>(`${this.baseUrl}/mfa/setup`, { method, phone })
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Confirma la configuración de MFA.
-   */
-  confirmMFA(code: string): Observable<MFAConfirmResponse> {
-    return this.http
-      .post<MFAConfirmResponse>(`${this.baseUrl}/mfa/confirm`, { code })
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Deshabilita MFA.
-   */
-  disableMFA(password: string): Observable<MFADisableResponse> {
-    return this.http
-      .post<MFADisableResponse>(`${this.baseUrl}/mfa/disable`, { password })
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  // =============================================
-  // TOTP MFA (Google Authenticator)
-  // =============================================
-
-  /**
-   * Inicia configuración de TOTP MFA.
-   * Retorna el secreto, URL para QR code y códigos de respaldo.
-   */
-  setupTOTP(): Observable<TOTPSetupResponse> {
-    return this.http
-      .post<TOTPSetupResponse>(`${this.baseUrl}/mfa/totp/setup`, {})
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Verifica el código TOTP y activa MFA.
-   * Debe llamarse después de setupTOTP con el código del authenticator.
-   */
-  verifyTOTPSetup(code: string): Observable<TOTPVerifySetupResponse> {
-    return this.http
-      .post<TOTPVerifySetupResponse>(`${this.baseUrl}/mfa/totp/verify`, { code })
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Regenera los códigos de respaldo TOTP.
-   * Los códigos anteriores son invalidados.
-   */
-  regenerateBackupCodes(): Observable<RegenerateBackupCodesResponse> {
-    return this.http
-      .post<RegenerateBackupCodesResponse>(`${this.baseUrl}/mfa/totp/backup-codes`, {})
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Obtiene la cantidad de códigos de respaldo restantes.
-   */
-  getBackupCodesCount(): Observable<BackupCodesCountResponse> {
-    return this.http
-      .get<BackupCodesCountResponse>(`${this.baseUrl}/mfa/totp/backup-codes/count`)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Desactiva TOTP MFA (requiere contraseña).
-   */
-  disableTOTP(password: string): Observable<TOTPDisableResponse> {
-    return this.http
-      .post<TOTPDisableResponse>(`${this.baseUrl}/mfa/totp/disable`, { password })
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  // =============================================
-  // ORGANIZACIONES
-  // =============================================
-
-  /**
-   * Cambia la organización activa del usuario.
-   * Genera un nuevo Firebase token con el activeOrg actualizado.
-   *
-   * @param organizationId - ID de la organización a la que cambiar
-   * @returns Observable con el nuevo Firebase token y activeOrg
-   *
-   * @example
-   * ```typescript
-   * await firstValueFrom(this.auth.switchOrg('org_xyz789'));
-   * // Firebase ya está re-autenticado con la nueva org
-   * const activeOrg = await this.firebase.getActiveOrg();
-   * ```
-   */
-  switchOrg(organizationId: string): Observable<SwitchOrgResponse> {
-    return this.http.post<SwitchOrgResponse>(`${this.baseUrl}/switch-org`, { organizationId }).pipe(
-      switchMap(response => {
-        // Re-autenticar en Firebase con el nuevo token
-        // Usar switchMap + from para esperar a que Firebase complete
-        const firebaseAuth$ = response.firebaseToken
-          ? from(this.signInWithFirebase(response.firebaseToken))
-          : of(undefined);
-
-        return firebaseAuth$.pipe(
-          tap(() => {
-            // Notificar cambio a otras pestañas
-            this.syncService.broadcast({
-              type: 'ORG_SWITCH',
-              payload: { activeOrg: response.activeOrg },
-            });
-          }),
-          // Retornar response original después de que Firebase complete
-          map(() => response)
-        );
-      }),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  // =============================================
-  // PERFIL DE USUARIO
-  // =============================================
-
-  /**
-   * Obtiene el perfil del usuario autenticado.
-   * Incluye información de MFA y teléfono. Hidrata el state automáticamente
-   * con `name/handle/avatarUrl/phone` para que `auth.user()` los retorne.
-   */
-  getProfile(): Observable<GetProfileResponse> {
-    return this.http.get<GetProfileResponse>(`${this.baseUrl}/profile`).pipe(
-      tap(profile =>
-        this.stateService.updateProfileFields({
-          name: profile.name,
-          handle: profile.handle ?? null,
-          avatarUrl: profile.avatarUrl ?? null,
-          phone: profile.phone ?? null,
-        })
-      ),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  /**
-   * Actualiza el perfil del usuario. Sincroniza state con los nuevos values
-   * (name/phone) — el backend response no los echo'a pero el caller ya tiene
-   * los valores que mandó.
-   */
-  updateProfile(request: UpdateProfileRequest): Observable<UpdateProfileResponse> {
-    return this.http.put<UpdateProfileResponse>(`${this.baseUrl}/profile`, request).pipe(
-      tap(() => this.stateService.updateProfileFields(request)),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  /**
-   * Actualiza el avatar del usuario en el backend. Sincroniza state con el
-   * `avatarUrl` retornado para que el header / dashboard se refresquen sin
-   * necesidad de un getProfile adicional.
-   */
-  updateAvatar(request: UpdateAvatarRequest): Observable<UpdateAvatarResponse> {
-    return this.http.put<UpdateAvatarResponse>(`${this.baseUrl}/profile/avatar`, request).pipe(
-      tap(res => this.stateService.updateProfileFields({ avatarUrl: res.avatarUrl })),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  // =============================================
-  // RECUPERACIÓN DE CONTRASEÑA
-  // =============================================
-
-  /**
-   * Inicia el proceso de recuperación de contraseña.
-   * Envía un código al email del usuario.
-   */
-  forgotPassword(request: ForgotPasswordRequest): Observable<ForgotPasswordResponse> {
-    return this.http
-      .post<ForgotPasswordResponse>(`${this.baseUrl}/forgot-password`, request)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Resetea la contraseña usando el código enviado por email.
-   */
-  resetPassword(request: ResetPasswordRequest): Observable<ResetPasswordResponse> {
-    return this.http
-      .post<ResetPasswordResponse>(`${this.baseUrl}/reset-password`, request)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  /**
-   * Cambia la contraseña del usuario autenticado.
-   * Requiere la contraseña actual para verificación.
-   */
-  changePassword(currentPassword: string, newPassword: string): Observable<ChangePasswordResponse> {
-    const request: ChangePasswordRequest = { currentPassword, newPassword };
-    return this.http
-      .post<ChangePasswordResponse>(`${this.baseUrl}/change-password`, request)
-      .pipe(catchError(error => this.handleAuthError(error)));
-  }
-
-  // =============================================
-  // ELIMINACIÓN DE CUENTA
-  // =============================================
-
-  /**
-   * Elimina la cuenta del usuario (soft delete).
-   * Requiere confirmación de contraseña por seguridad.
-   * Después de eliminar, cierra sesión automáticamente.
-   *
-   * @param password - Contraseña actual para confirmar
-   * @returns Observable con resultado de la eliminación
-   *
-   * @example
-   * ```typescript
-   * async confirmDeleteAccount(password: string) {
-   *   try {
-   *     const result = await firstValueFrom(this.auth.deleteAccount(password));
-   *     console.log(result.message); // "Tu cuenta ha sido eliminada..."
-   *     // Usuario es redirigido automáticamente al login
-   *   } catch (error) {
-   *     // Manejar error (contraseña incorrecta, etc)
-   *   }
-   * }
-   * ```
-   */
-  deleteAccount(password: string): Observable<DeleteAccountResponse> {
-    const request: DeleteAccountRequest = { password };
-    return this.http
-      .delete<DeleteAccountResponse>(`${this.baseUrl}/account`, { body: request })
-      .pipe(
-        tap(response => {
-          if (response.deleted) {
-            // Limpiar estado y cerrar sesión sin notificar al backend
-            // (la sesión ya fue revocada por el backend)
-            this.signOutFirebase();
-            this.clearState();
-            this.syncService.broadcast({ type: 'LOGOUT' });
-            this.router.navigate([this.config.loginRoute]);
-          }
-        }),
-        catchError(error => this.handleAuthError(error))
-      );
-  }
-
-  // =============================================
-  // PERMISOS
-  // =============================================
-
-  /**
-   * Obtiene los permisos actualizados del backend.
-   */
-  fetchPermissions(): Observable<GetPermissionsResponse> {
-    return this.http.get<GetPermissionsResponse>(`${this.baseUrl}/permissions`).pipe(
-      tap(response => {
-        this.stateService.updatePermissions(
-          response.roles,
-          response.permissions,
-          response.isSuperAdmin
-        );
-        this.storageService.savePermissions(response);
-        this.syncService.broadcast({ type: 'PERMISSIONS_UPDATE' });
-      }),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  /**
-   * Verifica si el usuario tiene un permiso específico.
-   * Formato: "resource:action" (ej: "templates:edit")
-   */
-  hasPermission(permission: string): boolean {
-    if (this.isSuperAdmin()) return true;
-
-    const [resource, action] = permission.split(':');
-    return this.permissions().some(p => {
-      const [pResource, pAction] = p.split(':');
-      return (
-        (pResource === '*' || pResource === resource) && (pAction === '*' || pAction === action)
-      );
-    });
-  }
-
-  /**
-   * Verifica si el usuario tiene alguno de los permisos dados.
-   */
-  hasAnyPermission(permissions: string[]): boolean {
-    return permissions.some(p => this.hasPermission(p));
-  }
-
-  /**
-   * Verifica si el usuario tiene todos los permisos dados.
-   */
-  hasAllPermissions(permissions: string[]): boolean {
-    return permissions.every(p => this.hasPermission(p));
-  }
-
-  /**
-   * Verifica si el usuario tiene un rol específico.
-   */
-  hasRole(role: string): boolean {
-    return this.roles().some(r => r.toLowerCase() === role.toLowerCase());
-  }
-
-  // =============================================
-  // HANDLE (USERNAME)
-  // =============================================
-
-  /**
-   * Actualiza el handle (@username) del usuario.
-   * @param handle - Nuevo handle (sin @, ej: "victorv")
-   */
-  updateHandle(handle: string): Observable<UpdateHandleResponse> {
-    return this.http.put<UpdateHandleResponse>(`${this.baseUrl}/profile/handle`, { handle }).pipe(
-      tap(() => this.stateService.updateProfileFields({ handle })),
-      catchError(error => this.handleAuthError(error))
-    );
-  }
-
-  /**
-   * Verifica si un handle está disponible.
-   * @param handle - Handle a verificar (sin @)
-   */
-  checkHandleAvailability(handle: string): Observable<CheckHandleResponse> {
-    // Server response: { operationId, user?, found }. found=true → handle taken.
-    // Lib semantic: available = !found.
-    return this.http
-      .get<{
-        operationId: string;
-        found: boolean;
-      }>(`${this.usersBaseUrl}/handle/${encodeURIComponent(handle)}`)
-      .pipe(
-        map(raw => ({
-          operationId: raw.operationId,
-          handle,
-          available: !raw.found,
-        })),
-        catchError(error => this.handleAuthError(error))
-      );
-  }
-
-  // =============================================
-  // PRIVATE METHODS
-  // =============================================
-
-  private get baseUrl(): string {
-    return `${this.config.apiUrl}${this.config.authPrefix}`;
-  }
-
-  /** Base for /v2/users endpoints (separate from /v2/auth). */
-  private get usersBaseUrl(): string {
-    return `${this.config.apiUrl}/v2/users`;
-  }
-
-  private handleSuccessfulAuth(response: SigninResponse | MFAVerifyResponse): void {
-    const expiresAt = Date.now() + response.expiresIn! * 1000;
-    const tokenData = this.tokenService.parseToken(response.accessToken!);
-    const isPremium = tokenData?.premium === true;
-
-    this.stateService.setAuthenticated({
-      accessToken: response.accessToken!,
-      refreshToken: response.refreshToken!,
-      userId: tokenData?.uid,
-      email: tokenData?.email,
-      roles: response.roles || [],
-      permissions: response.permissions || [],
-      isSuperAdmin: response.permissions?.includes('*:*') || false,
-      isPremium,
-      expiresAt,
-    });
-
-    this.storageService.saveState({
-      accessToken: response.accessToken!,
-      refreshToken: response.refreshToken!,
-      roles: response.roles || [],
-      permissions: response.permissions || [],
-      isSuperAdmin: response.permissions?.includes('*:*') || false,
-      isPremium,
-      expiresAt,
-    });
-
-    this.startRefreshTimer();
-    this.syncService.broadcast({ type: 'LOGIN' });
-
-    // Integración con Firebase
-    console.log('[ValtechAuth] handleSuccessfulAuth - Firebase check:', {
-      enableFirebaseIntegration: this.config.enableFirebaseIntegration,
-      hasFirebaseTokenKey: 'firebaseToken' in response,
-      firebaseTokenValue: !!(response as any).firebaseToken,
-      firebaseTokenLength: (response as any).firebaseToken?.length || 0,
-    });
-
-    if (
-      this.config.enableFirebaseIntegration &&
-      'firebaseToken' in response &&
-      response.firebaseToken
-    ) {
-      console.log(
-        '[ValtechAuth] Calling signInWithFirebase with token length:',
-        response.firebaseToken.length
-      );
-      this.signInWithFirebase(response.firebaseToken);
-    } else {
-      console.log('[ValtechAuth] Firebase signin skipped - conditions not met');
-    }
-
-    // Registro automático de dispositivo para push notifications
-    if (this.config.enableDeviceRegistration) {
-      this.registerDeviceIfNeeded(); // fire-and-forget
-    }
-
-    // Sincronizar idioma del usuario con i18n
-    if (this.i18nService && 'language' in response && response.language) {
-      const userLang = response.language as I18nLang;
-      const currentLang = this.i18nService.lang();
-      if (userLang !== currentLang) {
-        this.i18nService.setLanguage(userLang);
-        console.log(`[ValtechAuth] Language synced to: ${userLang}`);
-      }
-    }
-  }
-
-  private clearState(): void {
-    this.stopRefreshTimer();
-    this.stateService.reset();
-    this.storageService.clear();
-  }
-
-  private startRefreshTimer(): void {
-    this.stopRefreshTimer();
-
-    const state = this.stateService.state();
-    if (!state.expiresAt) return;
-
-    const refreshBeforeMs = (this.config.refreshBeforeExpiry || 60) * 1000;
-    const refreshAt = state.expiresAt - refreshBeforeMs;
-    const delay = refreshAt - Date.now();
-
-    if (delay > 0) {
-      this.refreshTimerId = setTimeout(() => {
-        this.refreshAccessToken().subscribe({
-          error: () => this.logout(),
-        });
-      }, delay);
-    } else if (state.refreshToken) {
-      // Token ya debería refrescarse, intentar ahora
-      this.refreshAccessToken().subscribe({
-        error: () => this.logout(),
-      });
-    }
-  }
-
-  private stopRefreshTimer(): void {
-    if (this.refreshTimerId) {
-      clearTimeout(this.refreshTimerId);
-      this.refreshTimerId = null;
-    }
-  }
-
-  private handleSyncEvent(event: AuthSyncEvent): void {
-    switch (event.type) {
-      case 'LOGIN':
-      case 'TOKEN_REFRESH': {
-        // Recargar estado desde storage
-        const state = this.storageService.loadState();
-        if (state.accessToken) {
-          this.stateService.restoreFromStorage(state);
-          const claims = this.tokenService.parseToken(state.accessToken);
-          if (claims) {
-            this.stateService.updateUserInfo(claims.uid, claims.email);
-          }
-          this.startRefreshTimer();
-        }
-        break;
-      }
-      case 'LOGOUT':
-        this.stateService.reset();
-        this.stopRefreshTimer();
-        this.router.navigate([this.config.loginRoute]);
-        break;
-      case 'PERMISSIONS_UPDATE': {
-        const perms = this.storageService.loadPermissions();
-        this.stateService.updatePermissions(perms.roles, perms.permissions, perms.isSuperAdmin);
-        break;
-      }
-      case 'ORG_SWITCH':
-        // Otra pestaña cambió de organización - recargar página para obtener nuevo estado
-        window.location.reload();
-        break;
-    }
-  }
-
-  private handleAuthError(error: HttpErrorResponse): Observable<never> {
-    const authError: AuthError = {
-      code: error.error?.code || 'UNKNOWN_ERROR',
-      message: error.error?.message || 'Error de autenticación desconocido',
-    };
-    this.stateService.setError(authError);
-    return throwError(() => authError);
-  }
-
-  // =============================================
-  // FIREBASE INTEGRATION
-  // =============================================
-
-  private async signInWithFirebase(firebaseToken: string): Promise<void> {
-    try {
-      if (this.firebaseService) {
-        await this.firebaseService.signInWithCustomToken(firebaseToken);
-        console.log('[ValtechAuth] Firebase signin successful');
-      } else {
-        console.warn(
-          '[ValtechAuth] FirebaseService not provided. Add provideValtechFirebase() to your providers.'
-        );
-      }
-    } catch (error) {
-      // No bloquear el login principal si Firebase falla
-      console.error('[ValtechAuth] Firebase signin failed:', error);
-    }
-  }
-
-  private async signOutFirebase(): Promise<void> {
-    if (!this.config.enableFirebaseIntegration) return;
-
-    try {
-      if (this.firebaseService) {
-        await this.firebaseService.signOut();
-        console.log('[ValtechAuth] Firebase signout successful');
-      }
-    } catch (error) {
-      // Ignorar errores de Firebase signout
-      console.warn('[ValtechAuth] Firebase signout failed:', error);
-    }
-  }
-
-  // =============================================
-  // DEVICE REGISTRATION (Push Notifications)
-  // =============================================
-
-  /**
-   * Solicita permisos de notificación y registra el dispositivo.
-   * Usar cuando el usuario acepta recibir notificaciones.
-   *
-   * @example
-   * ```typescript
-   * async onEnableNotifications() {
-   *   const result = await this.auth.enableNotifications();
-   *   if (result.granted) {
-   *     console.log('Notificaciones habilitadas');
-   *   }
-   * }
-   * ```
-   */
-  async enableNotifications(): Promise<EnableNotificationsResult> {
-    if (!this.messagingService) {
-      console.warn('[ValtechAuth] MessagingService not available');
-      return { granted: false };
-    }
-
-    if (!(await this.messagingService.isSupported())) {
-      console.warn('[ValtechAuth] Push notifications not supported');
-      return { granted: false };
-    }
-
-    const token = await this.messagingService.requestPermission();
-    if (!token) {
-      return { granted: false };
-    }
-
-    // Registrar dispositivo en backend
-    const registered = await this.registerDeviceIfNeeded();
-
-    return { granted: true, token, registered };
-  }
-
-  /**
-   * Desactiva las notificaciones para este dispositivo.
-   * Elimina el token del backend y de FCM.
-   * Usar desde un toggle de preferencias cuando el usuario desactiva notificaciones.
-   *
-   * NOTA: Esto NO revoca el permiso del navegador (el usuario debe hacerlo manualmente
-   * desde la configuración del navegador). Solo elimina el registro del dispositivo.
-   *
-   * @example
-   * ```typescript
-   * async onToggleNotifications(enabled: boolean) {
-   *   if (enabled) {
-   *     await this.auth.enableNotifications();
-   *   } else {
-   *     await this.auth.disableNotifications();
-   *   }
-   * }
-   * ```
-   */
-  async disableNotifications(): Promise<{ disabled: boolean }> {
-    if (!this.messagingService) {
-      return { disabled: false };
-    }
-
-    try {
-      const token = this.messagingService.currentToken;
-      if (token) {
-        // Eliminar del backend
-        await firstValueFrom(
-          this.http
-            .request('DELETE', `${this.config.apiUrl}/v2/users/me/devices/by-token`, {
-              body: { token },
-            })
-            .pipe(catchError(() => of(null)))
-        );
-
-        // Eliminar token de FCM
-        await this.messagingService.deleteToken();
-        console.log('[ValtechAuth] Notifications disabled');
-        return { disabled: true };
-      }
-
-      return { disabled: false };
-    } catch (error) {
-      console.warn('[ValtechAuth] Failed to disable notifications:', error);
-      return { disabled: false };
-    }
-  }
-
-  /**
-   * Retorna el estado actual de permisos de notificación.
-   *
-   * @returns 'granted' | 'denied' | 'default' | 'unsupported'
-   */
-  getNotificationPermissionState(): NotificationPermissionState {
-    if (!this.messagingService) {
-      return 'unsupported';
-    }
-    return this.messagingService.getPermissionState() as NotificationPermissionState;
-  }
-
-  /**
-   * Registra manualmente el dispositivo en el backend.
-   * Útil para sincronizar dispositivos que tienen token FCM pero no están registrados.
-   *
-   * @param providedToken Token FCM opcional. Si se proporciona, se usa directamente
-   *                      sin depender del MessagingService (evita timing issues).
-   * @returns Resultado del registro con deviceId si fue exitoso
-   *
-   * @example
-   * ```typescript
-   * // Sincronizar con token existente (recomendado)
-   * const result = await this.auth.registerDevice(myToken);
-   *
-   * // Sin token, intentará obtenerlo del MessagingService
-   * const result = await this.auth.registerDevice();
-   * ```
-   */
-  async registerDevice(providedToken?: string): Promise<RegisterDeviceResult> {
-    if (!this.isAuthenticated()) {
-      return { registered: false, error: 'Usuario no autenticado' };
-    }
-
-    try {
-      // Verificar permisos si tenemos MessagingService
-      if (this.messagingService) {
-        const permission = this.messagingService.getPermissionState();
-        if (permission !== 'granted') {
-          return { registered: false, error: 'Permiso de notificaciones no otorgado' };
-        }
-      }
-
-      // Usar token proporcionado primero (evita timing issues con Injector)
-      let token = providedToken || this.messagingService?.currentToken;
-
-      // Si no hay token, intentar obtenerlo del MessagingService
-      if (!token && this.messagingService) {
-        if (!(await this.messagingService.isSupported())) {
-          return { registered: false, error: 'FCM no soportado en este navegador' };
-        }
-        token = await this.messagingService.getToken();
-      }
-
-      if (!token) {
-        return { registered: false, error: 'No se pudo obtener token FCM' };
-      }
-
-      // Registrar en backend
-      const { platform, browser, os } = this.detectPlatformInfo();
-      const response = await firstValueFrom(
-        this.http.post<RegisterDeviceResponse>(`${this.config.apiUrl}/v2/users/me/devices`, {
-          token,
-          platform,
-          browser,
-          os,
-        })
-      );
-
-      console.log('[ValtechAuth] Device registered manually:', response.device.deviceId);
-      return { registered: true, deviceId: response.device.deviceId, token };
-    } catch (error: any) {
-      console.warn('[ValtechAuth] Manual device registration failed:', error);
-      return {
-        registered: false,
-        error: error?.error?.message || error?.message || 'Error al registrar dispositivo',
-      };
-    }
-  }
-
-  /**
-   * Registra el dispositivo en el backend si tiene permisos de notificación.
-   * Se llama automáticamente después de un login exitoso si enableDeviceRegistration=true.
-   */
-  private async registerDeviceIfNeeded(): Promise<boolean> {
-    // Solo si está habilitado y messaging está disponible
-    if (!this.config.enableDeviceRegistration || !this.messagingService) {
-      return false;
-    }
-
-    try {
-      // Verificar si FCM está soportado
-      if (!(await this.messagingService.isSupported())) {
-        return false;
-      }
-
-      // Verificar si ya tiene permisos
-      const permission = this.messagingService.getPermissionState();
-      if (permission !== 'granted') {
-        return false; // No solicitar automáticamente, solo registrar si ya tiene permiso
-      }
-
-      // Obtener token existente (no solicitar nuevo)
-      const token = await this.messagingService.getToken();
-      if (!token) {
-        return false;
-      }
-
-      // Registrar en backend
-      const { platform, browser, os } = this.detectPlatformInfo();
-      await firstValueFrom(
-        this.http.post<RegisterDeviceResponse>(`${this.config.apiUrl}/v2/users/me/devices`, {
-          token,
-          platform,
-          browser,
-          os,
-        })
-      );
-
-      console.log('[ValtechAuth] Device registered successfully');
-      return true;
-    } catch (error) {
-      // No bloquear auth si falla device registration
-      console.warn('[ValtechAuth] Device registration failed:', error);
-      return false;
-    }
-  }
-
-  /**
-   * Elimina el dispositivo del backend y borra el token FCM.
-   */
-  private async unregisterDevice(): Promise<void> {
-    if (!this.config.enableDeviceRegistration || !this.messagingService) {
-      return;
-    }
-
-    try {
-      const token = this.messagingService.currentToken;
-      if (token) {
-        // Delete from backend (fire and forget)
-        this.http
-          .request('DELETE', `${this.config.apiUrl}/v2/users/me/devices/by-token`, {
-            body: { token },
-          })
-          .pipe(catchError(() => of(null)))
-          .subscribe();
-
-        // Delete from FCM
-        await this.messagingService.deleteToken();
-        console.log('[ValtechAuth] Device unregistered');
-      }
-    } catch {
-      // Ignorar errores en cleanup
-    }
-  }
-
-  /**
-   * Detecta información de la plataforma del dispositivo.
-   */
-  private detectPlatformInfo(): { platform: 'web'; browser: string; os: string } {
-    const ua = navigator.userAgent;
-
-    // Detectar navegador
-    let browser = 'Unknown';
-    if (ua.includes('Firefox')) {
-      browser = 'Firefox';
-    } else if (ua.includes('Edg')) {
-      browser = 'Edge';
-    } else if (ua.includes('Chrome')) {
-      browser = 'Chrome';
-    } else if (ua.includes('Safari')) {
-      browser = 'Safari';
-    }
-
-    // Detectar OS
-    let os = 'Unknown';
-    if (ua.includes('Windows')) {
-      os = 'Windows';
-    } else if (ua.includes('Mac OS')) {
-      os = 'macOS';
-    } else if (ua.includes('Linux')) {
-      os = 'Linux';
-    } else if (ua.includes('Android')) {
-      os = 'Android';
-    } else if (ua.includes('iOS') || ua.includes('iPhone') || ua.includes('iPad')) {
-      os = 'iOS';
-    }
-
-    return { platform: 'web', browser, os };
-  }
-}