valtech-components 2.0.787 → 2.0.795

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

@@ -0,0 +1,1387 @@
+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 };
+  }
+}