@gzl10/baserow 1.2.0

package/src/services/AuthService.ts

@@ -0,0 +1,472 @@
+import { AxiosResponse } from 'axios'
+import { HttpService } from './core/HttpService'
+import { HttpClient } from '../utils/axios'
+import {
+  LoginResponse,
+  RefreshTokenRequest,
+  RefreshTokenResponse,
+  BaserowError,
+  BaserowAuthTokenInvalidError,
+  BaserowReLoginRequiredError,
+  BaserowCredentials,
+  Logger
+} from '../types'
+import { validateString } from '../utils/validation'
+import { decodeJwtExpiry } from '../utils/jwt-decoder'
+
+export class AuthService extends HttpService {
+  private accessToken?: string
+  private refreshToken?: string
+  private tokenExpiry?: Date
+  private keepAliveTimer?: NodeJS.Timeout
+  private credentials?: BaserowCredentials
+
+  constructor(http: HttpClient, logger?: Logger) {
+    super(http, logger)
+  }
+
+  /**
+   * Realizar login con credenciales y obtener JWT tokens
+   *
+   * Autentica al usuario con Baserow y almacena los tokens de acceso y refresh en memoria.
+   * Si keep-alive está habilitado, también almacena las credenciales para re-login automático.
+   *
+   * @param credentials - Email y password del usuario Baserow
+   * @returns Respuesta de login con tokens y datos del usuario
+   * @throws {BaserowError} Si las credenciales son inválidas (401)
+   *
+   * @example
+   * ```typescript
+   * const response = await authService.login({
+   *   email: 'user@example.com',
+   *   password: 'securepassword'
+   * })
+   * console.log(`Logged in as: ${response.user.username}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async login(credentials: BaserowCredentials): Promise<LoginResponse> {
+    validateString(credentials.email, 'email')
+    validateString(credentials.password, 'password')
+
+    this.logger?.info?.(`🔐 Attempting login for user: ${credentials.email}`)
+
+    const loginData = {
+      username: credentials.email,
+      password: credentials.password
+    }
+
+    try {
+      const response = await this.http.post<LoginResponse>('/user/token-auth/', loginData)
+
+      // Almacenar tokens en memoria
+      this.accessToken = response.access_token
+      this.refreshToken = response.refresh_token
+
+      // Almacenar credenciales para keep-alive (re-login automático)
+      this.credentials = credentials
+
+      // Decodificar expiración desde el claim 'exp' del JWT (estándar)
+      this.tokenExpiry = decodeJwtExpiry(response.access_token, this.logger)
+      if (!this.tokenExpiry) {
+        this.logger?.warn?.('⚠️ No se pudo decodificar exp del JWT, usando fallback de 10 min')
+        this.tokenExpiry = new Date(Date.now() + 10 * 60 * 1000) // Fallback conservador
+      }
+
+      // Actualizar el token en HttpClient
+      this.http.setAuthToken(response.access_token)
+
+      this.logger?.info?.(`✅ Login successful for user: ${response.user.username} (ID: ${response.user.id})`)
+      this.logger?.debug?.(`Access token expires at: ${this.tokenExpiry.toISOString()}`)
+      this.logger?.debug?.(`Refresh token stored (expires ~7 days from now)`)
+
+      return response
+    } catch (error) {
+      if (error instanceof BaserowError && error.status === 401) {
+        this.logger?.error?.(`❌ Login failed: Invalid credentials for ${credentials.email}`)
+        throw new BaserowError('Invalid credentials', 401, 'INVALID_CREDENTIALS')
+      }
+      this.logger?.error?.('❌ Login failed with unexpected error:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Renovar access token usando refresh token
+   *
+   * IMPORTANTE: En Baserow, el refresh token NO se renueva al hacer refresh (ROTATE_REFRESH_TOKENS=False).
+   * Solo se obtiene un nuevo access_token válido por 10 minutos. El refresh_token expira 7 días después
+   * del login original y NO se extiende con actividad.
+   *
+   * Para backends 24/7, usar keep-alive con re-login automático en lugar de depender de refresh token.
+   *
+   * @returns Nuevo access token válido
+   * @throws {BaserowReLoginRequiredError} Si el refresh token expiró (401) o no está disponible
+   * @throws {BaserowAuthTokenInvalidError} Si el refresh token es inválido (400)
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const newToken = await authService.refreshAccessToken()
+   *   console.log('Token renovado exitosamente')
+   * } catch (error) {
+   *   if (error instanceof BaserowReLoginRequiredError) {
+   *     console.log('Refresh token expirado, se requiere re-login')
+   *     await authService.login(credentials)
+   *   }
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async refreshAccessToken(): Promise<string> {
+    if (!this.refreshToken) {
+      this.logger?.error?.('❌ No refresh token available - tokens may have been lost')
+      throw new BaserowReLoginRequiredError('tokens_lost', {
+        message: 'No refresh token available. This can happen after process restart or if tokens were manually cleared.'
+      })
+    }
+
+    const refreshData: RefreshTokenRequest = {
+      refresh_token: this.refreshToken
+    }
+
+    try {
+      this.logger?.debug?.('🔄 Attempting to refresh access token...')
+
+      const response = await this.http.post<RefreshTokenResponse>('/user/token-refresh/', refreshData)
+
+      // Actualizar tokens almacenados
+      this.accessToken = response.access_token
+      // El refresh token se mantiene igual, no se renueva
+
+      // Decodificar expiración desde el claim 'exp' del JWT (estándar)
+      this.tokenExpiry = decodeJwtExpiry(response.access_token, this.logger)
+      if (!this.tokenExpiry) {
+        this.logger?.warn?.('⚠️ No se pudo decodificar exp del JWT, usando fallback de 10 min')
+        this.tokenExpiry = new Date(Date.now() + 10 * 60 * 1000) // Fallback conservador
+      }
+
+      // Actualizar el token en HttpClient
+      this.http.setAuthToken(response.access_token)
+
+      this.logger?.info?.('✅ Refresh token successful - new access token obtained')
+      this.logger?.debug?.(`New token expires at: ${this.tokenExpiry.toISOString()}`)
+
+      return response.access_token
+    } catch (error) {
+      // Si el refresh falla, limpiar tokens
+      this.clearTokens()
+
+      // Proporcionar mensajes de error específicos y accionables
+      if (error instanceof BaserowError) {
+        if (error.status === 401) {
+          // 401 en refresh significa que el refresh token expiró (típicamente después de ~7 días de inactividad)
+          this.logger?.error?.('❌ Refresh token has EXPIRED - Re-authentication required')
+          this.logger?.error?.('   Refresh tokens expire after ~7 days of inactivity in Baserow')
+          this.logger?.error?.('   User must login again with email/password')
+
+          throw new BaserowReLoginRequiredError('refresh_token_expired', {
+            originalError: error.message,
+            hint: 'Baserow refresh tokens expire after approximately 7 days. User must re-authenticate with credentials.'
+          })
+        } else if (error.status === 400) {
+          this.logger?.error?.('❌ Refresh token invalid or corrupted')
+          throw new BaserowAuthTokenInvalidError('Refresh token is invalid or corrupted', {
+            originalStatus: error.status,
+            originalCode: error.code
+          })
+        }
+      }
+
+      this.logger?.error?.('❌ Refresh token failed with unexpected error:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Verificar si el token actual ha expirado
+   *
+   * Considera el token expirado si:
+   * - No hay token almacenado
+   * - No hay fecha de expiración conocida
+   * - Expira en los próximos 5 minutos (margen de seguridad)
+   *
+   * @returns `true` si el token está expirado o próximo a expirar, `false` si es válido
+   *
+   * @example
+   * ```typescript
+   * if (authService.isTokenExpired()) {
+   *   await authService.refreshAccessToken()
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  isTokenExpired(): boolean {
+    if (!this.tokenExpiry || !this.accessToken) {
+      return true
+    }
+
+    // Verificar si expira en los próximos 5 minutos
+    const fiveMinutesFromNow = new Date(Date.now() + 5 * 60 * 1000)
+    return this.tokenExpiry <= fiveMinutesFromNow
+  }
+
+  /**
+   * Obtener token válido, renovándolo automáticamente si ha expirado
+   *
+   * Verifica la expiración del token y lo renueva automáticamente si es necesario.
+   * Ideal para usar antes de realizar requests a la API.
+   *
+   * @returns Access token válido
+   * @throws {BaserowError} Si no hay token disponible y se requiere login
+   * @throws {BaserowReLoginRequiredError} Si el refresh token expiró
+   *
+   * @example
+   * ```typescript
+   * const token = await authService.getValidToken()
+   * // Usar token en headers de request
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async getValidToken(): Promise<string> {
+    if (!this.accessToken) {
+      throw new BaserowError('No access token available, login required', 401, 'NO_ACCESS_TOKEN')
+    }
+
+    if (this.isTokenExpired()) {
+      await this.refreshAccessToken()
+    }
+
+    return this.accessToken!
+  }
+
+  /**
+   * Verificar si el usuario está autenticado con token válido
+   *
+   * @returns `true` si hay token válido y no expirado, `false` en caso contrario
+   *
+   * @example
+   * ```typescript
+   * if (!authService.isAuthenticated()) {
+   *   await authService.login(credentials)
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  isAuthenticated(): boolean {
+    return !!this.accessToken && !this.isTokenExpired()
+  }
+
+  /**
+   * Obtener el access token actual (sin validar expiración)
+   *
+   * Retorna el token almacenado en memoria sin verificar si está expirado.
+   * Para obtener un token válido garantizado, usar `getValidToken()`.
+   *
+   * @returns Access token actual o `undefined` si no hay token
+   *
+   * @example
+   * ```typescript
+   * const token = authService.getCurrentToken()
+   * if (token) {
+   *   console.log('Token disponible')
+   * }
+   * ```
+   *
+   * @since 1.0.0
+   */
+  getCurrentToken(): string | undefined {
+    return this.accessToken
+  }
+
+  /**
+   * Limpiar todos los tokens y credenciales almacenadas
+   *
+   * Limpia access token, refresh token, credenciales y detiene el keep-alive si está activo.
+   * También limpia el token del HttpClient.
+   *
+   * @example
+   * ```typescript
+   * authService.clearTokens()
+   * console.log('Sesión limpiada')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  clearTokens(): void {
+    this.stopKeepAlive()
+    this.accessToken = undefined
+    this.refreshToken = undefined
+    this.tokenExpiry = undefined
+    this.credentials = undefined
+    this.http.clearAuthToken()
+  }
+
+  /**
+   * Cerrar sesión y limpiar tokens
+   *
+   * Alias de `clearTokens()`. Limpia todos los tokens, credenciales y detiene keep-alive.
+   * No hace petición al servidor (Baserow no tiene endpoint de logout).
+   *
+   * @example
+   * ```typescript
+   * authService.logout()
+   * console.log('Sesión cerrada')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  logout(): void {
+    this.clearTokens()
+  }
+
+  /**
+   * Iniciar keep-alive automático para evitar expiración de refresh token
+   *
+   * IMPORTANTE: El refresh token de Baserow expira 7 días después del login (fijo, NO se renueva con refresh).
+   * Keep-alive ejecuta RE-LOGIN completo periódicamente para obtener tokens frescos (access + refresh)
+   * y mantener la sesión activa indefinidamente en aplicaciones backend 24/7.
+   *
+   * ⚠️ SEGURIDAD: Las credenciales se almacenan en memoria del proceso.
+   * Solo usar en backends propios/confiables, NO en frontends o apps compartidas.
+   *
+   * @param intervalMinutes - Intervalo en minutos para re-login (default: 7200 = 5 días, margen 2 días)
+   *
+   * @example
+   * ```typescript
+   * // Re-login cada 5 días (recomendado para backends 24/7)
+   * authService.startKeepAlive()
+   *
+   * // Re-login cada 3 días (más conservador, margen 4 días)
+   * authService.startKeepAlive(4320)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  startKeepAlive(intervalMinutes: number = 7200): void {
+    // Prevenir múltiples timers simultáneos
+    if (this.keepAliveTimer) {
+      this.logger?.warn?.('⚠️ Keep-alive ya está activo, deteniendo timer anterior')
+      this.stopKeepAlive()
+    }
+
+    if (!this.credentials) {
+      this.logger?.error?.('❌ Keep-alive requiere credenciales almacenadas')
+      return
+    }
+
+    const intervalMs = intervalMinutes * 60 * 1000
+    const days = (intervalMinutes / 1440).toFixed(1)
+
+    this.logger?.info?.(`🔄 Keep-alive iniciado: re-login cada ${days} días (${intervalMinutes} min)`)
+
+    this.keepAliveTimer = setInterval(async () => {
+      if (!this.credentials) {
+        this.logger?.error?.('❌ Keep-alive: credenciales no disponibles')
+        return
+      }
+
+      try {
+        this.logger?.debug?.('🔄 Keep-alive: ejecutando re-login preventivo...')
+        await this.login(this.credentials)
+        this.logger?.info?.('✅ Keep-alive: Re-login exitoso, tokens renovados (válidos 7 días más)')
+      } catch (error) {
+        this.logger?.error?.('❌ Keep-alive: error en re-login preventivo:', error)
+        // No detenemos el timer, siguiente intento puede funcionar
+      }
+    }, intervalMs)
+
+    // Prevenir que el timer mantenga el proceso Node.js vivo indefinidamente
+    if (this.keepAliveTimer.unref) {
+      this.keepAliveTimer.unref()
+    }
+  }
+
+  /**
+   * Detener keep-alive automático
+   *
+   * Limpia el timer de keep-alive. Se llama automáticamente en `logout()` y `clearTokens()`.
+   *
+   * @example
+   * ```typescript
+   * // Detener manualmente el keep-alive
+   * authService.stopKeepAlive()
+   * ```
+   *
+   * @since 1.1.0
+   */
+  stopKeepAlive(): void {
+    if (this.keepAliveTimer) {
+      clearInterval(this.keepAliveTimer)
+      this.keepAliveTimer = undefined
+      this.logger?.info?.('🛑 Keep-alive detenido')
+    }
+  }
+
+  /**
+   * Configurar interceptor para auto-refresh en 401 usando interceptors nativos de Axios
+   *
+   * Intercepta respuestas 401 (Unauthorized) y automáticamente intenta renovar el token
+   * usando refresh token. Si la renovación es exitosa, reintenta la petición original.
+   *
+   * NO intercepta endpoints de autenticación (`/user/token-*`) para evitar loops infinitos.
+   *
+   * @example
+   * ```typescript
+   * await authService.login(credentials)
+   * authService.setupAutoRefresh()
+   * // Ahora los 401 se manejan automáticamente
+   * ```
+   *
+   * @since 1.0.0
+   */
+  setupAutoRefresh(): void {
+    this.http.addResponseInterceptor(
+      (response: AxiosResponse) => response,
+      async (error: any) => {
+        // El config puede venir del error original de Axios o del BaserowError transformado
+        const originalRequest = error.config
+
+        // NO hacer auto-refresh en endpoints de autenticación (previene loops infinitos)
+        const isAuthEndpoint = originalRequest?.url?.includes('/user/token-')
+
+        // Detectar 401 de cualquier fuente (error raw de Axios o BaserowError transformado)
+        const is401Error = error.response?.status === 401 || (error instanceof BaserowError && error.status === 401)
+
+        // Si recibimos 401 y tenemos refresh token, intentar renovar
+        // EXCEPTO en endpoints de autenticación (login, refresh)
+        if (is401Error && !isAuthEndpoint && this.refreshToken && originalRequest && !originalRequest._retry) {
+          originalRequest._retry = true
+
+          this.logger?.info?.('🔄 Auto-refresh: Detectado 401, intentando renovar token...')
+
+          try {
+            const newToken = await this.refreshAccessToken()
+
+            this.logger?.info?.('✅ Auto-refresh: Token renovado, reintentando request original')
+
+            // Actualizar el header Authorization con el nuevo token
+            if (originalRequest.headers && newToken) {
+              originalRequest.headers.Authorization = `JWT ${newToken}`
+            }
+
+            // Reintentar la petición original con el nuevo token actualizado
+            return this.http.axios.request(originalRequest)
+          } catch {
+            // Si el refresh falla, limpiar tokens y propagar error original
+            this.logger?.error?.('❌ Auto-refresh: Falló la renovación del token')
+            this.clearTokens()
+            throw error
+          }
+        }
+
+        throw error
+      }
+    )
+  }
+}