Adrian Flores Cortes 54ea125d82 docs(auth): Document BLOCKER-001 Token Refresh improvements (Phases 1-2)

FASE 1 ✅: Rate limiting específico para /auth/refresh
- Nuevo refreshTokenRateLimiter (15 refreshes/15min por token)
- Key generator: IP + hash(refreshToken)
- Previene abuse de tokens individuales

FASE 2 ✅: Token rotation mechanism
- Backend code implementado (backward-compatible)
- Detección de token reuse → revoca todas las sesiones
- Nuevo refresh token en cada refresh
- Migration SQL creada: apps/database/migrations/2026-01-27_add_token_rotation.sql

Archivos de código modificados (en .gitignore):
- apps/backend/src/core/middleware/rate-limiter.ts
- apps/backend/src/modules/auth/auth.routes.ts
- apps/backend/src/modules/auth/services/token.service.ts
- apps/backend/src/modules/auth/types/auth.types.ts
- apps/database/ddl/schemas/auth/tables/04-sessions.sql
- apps/database/migrations/2026-01-27_add_token_rotation.sql

Pendiente: FASE 3 (Session Validation) y FASE 4 (Proactive Refresh)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-27 00:46:19 -06:00

2.4 KiB

Raw Blame History

01-CONTEXTO.md - BLOCKER-001 Token Refresh

Situación Actual

El sistema de token refresh YA ESTÁ IMPLEMENTADO AL 90% y funciona correctamente:

✅ Implementación Existente

Ubicación: apps/frontend/src/lib/apiClient.ts:133-191

Características actuales:

✅ Interceptor Axios detecta 401 automáticamente
✅ Backend endpoint /auth/refresh funcional
✅ Request queueing previene refreshes duplicados
✅ Retry automático del request original con nuevo token
✅ Logout automático en caso de fallo de refresh

Código funcional:

// Interceptor que detecta 401
axiosInstance.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401 && !originalRequest._retry) {
      if (isRefreshing) {
        return new Promise((resolve, reject) => {
          failedQueue.push({ resolve, reject });
        }).then(token => { /* retry with new token */ });
      }
      // Refresh token logic...
    }
  }
);

Problema

No es un blocker crítico, pero faltan mejoras de seguridad y UX:

Rate limiting genérico - /auth/refresh usa el mismo rate limit que otros endpoints (100/15min)
Sin token rotation - El mismo refresh token se puede usar múltiples veces
Sin session validation - No valida que la sesión esté activa en BD
Sin proactive refresh - Espera a que el token expire (UX subóptima)

Impacto

Sin estas mejoras:

🔴 Vulnerabilidad a token replay attacks
🟡 UX subóptima (espera a 401 para refrescar)
🟡 Posible race condition en refreshes concurrentes (raro)
🔴 No detecta sesiones revocadas hasta que falla el request

Alcance de la Tarea

NO: Reescribir el sistema de auth SÍ: Agregar 4 mejoras incrementales a código existente

Esfuerzo: 12h distribuidas en 4 fases

Archivos Críticos Existentes

apps/frontend/src/lib/apiClient.ts - Interceptor Axios (191 LOC)
apps/backend/src/modules/auth/services/token.service.ts - Token generation (450 LOC)
apps/backend/src/modules/auth/auth.routes.ts - Routes (120 LOC)
apps/backend/src/core/middleware/auth.middleware.ts - Auth middleware (280 LOC)
apps/database/ddl/schemas/auth/tables/04-sessions.sql - Sessions table

Referencias

Plan completo: C:\Users\cx_ad\.claude\projects\C--Empresas-ISEM-workspace-v2\d20bcdfd-6fd5-402d-ae54-fce930f9c826.jsonl

Sección del plan: BLOCKER-001: Token Refresh Improvements (12h)

2.4 KiB Raw Blame History