Skip to content

README.md

Latest commit

 

History

History
145 lines (118 loc) · 5.61 KB

README.md

File metadata and controls

145 lines (118 loc) · 5.61 KB

PasswordReset

Aplicación Next.js para gestionar intentos de reseteo de contraseña con verificación de usuario, logging de intentos y base de datos en Neon/Postgres. Incluye APIs para verificación y registro de intentos, middleware de seguridad, y scripts para inicializar y seedear la base de datos.

Índice

  • Introducción
  • Stack y Estructura
  • Requisitos
  • Variables de Entorno
  • Configuración de Base de Datos (Neon)
  • Scripts Disponibles
  • Desarrollo Local
  • Endpoints de API
  • Middleware y Seguridad
  • Flujo de Reseteo
  • Resolución de Problemas
  • Roadmap breve

Introducción

Este proyecto provee una UI simple para ingresar un identificador de usuario (por ejemplo email o username), validarlo contra una base de datos en Neon, y registrar cada intento de reseteo. Pensado para integrarse con flujos corporativos (Microsoft/SSO) o como base para un sistema propio.

Stack y Estructura

  • Next.js 14 (App Router)
  • TypeScript + Tailwind
  • Postgres en Neon (serverless)
  • Librería de componentes UI (shadcn/ui)

Estructura relevante:

  • app/ páginas, layout y rutas de API (app/api/*)
  • components/ UI y formularios (password-reset-form.tsx, microsoft-reset-form.tsx, db-status-indicator.tsx)
  • lib/ utilidades (db.ts, validation.ts)
  • scripts/ utilidades Node para Neon (check-neon.js, init-neon.js, seed-neon.js, seed-attempts.js)
  • sql/ definiciones SQL (init_neon.sql)
  • public/ assets

Requisitos

  • Node.js 18+ (se recomienda 18 LTS o 20 LTS)
  • npm o pnpm (el repo incluye package-lock.json para npm)
  • Cuenta y base de datos en Neon (Postgres)

Variables de Entorno

Crea tu .env.local en base a .env.example.

Claves típicas:

  • DATABASE_URL: cadena de conexión de Neon (formato postgres://user:pass@host/db?sslmode=require)
  • NEXT_PUBLIC_APP_NAME: nombre mostrado en la UI
  • Otras claves opcionales para logs o proveedores (según tu integración)

Notas:

  • .env* está ignorado por git (.gitignore). No subas credenciales.
  • Si usas Vercel u otro PaaS, define estas variables en su panel.

Configuración de Base de Datos (Neon)

  1. Crea el proyecto y DB en https://neon.tech
  2. Obtén la DATABASE_URL con SSL habilitado.
  3. Inicializa el esquema:
    • npm run db:init (usa sql/init_neon.sql)
  4. Opcional: poblar datos de prueba
    • npm run db:seed
  5. Verifica conexión:
    • npm run db:check

Los scripts usan la DATABASE_URL de tu entorno (.env.local).

Scripts Disponibles

Desde package.json:

  • dev: inicia Next en modo desarrollo
  • build: compila la app
  • start: ejecuta producción
  • lint: corre linter (si está configurado)
  • db:check: verifica conexión a Neon (scripts/check-neon.js)
  • db:init: aplica el esquema inicial (sql/init_neon.sql via scripts/init-neon.js)
  • db:seed: datos base de usuarios/reset attempts (scripts/seed-neon.js y/o scripts/seed-attempts.js)

Ejemplos:

npm install
npm run db:check
npm run db:init
npm run db:seed
npm run dev

Desarrollo Local

  1. Instala dependencias: npm install
  2. Configura .env.local
  3. Inicializa base de datos (sección Neon)
  4. Levanta el entorno: npm run dev

La app correrá en http://localhost:3000.

Endpoints de API

Rutas en app/api/*:

  • GET /api/check-db-connection

    • Verifica conectividad a la DB. Útil para health checks y UI de estado (db-status-indicator).

  • POST /api/verify-user

    • Body: { identifier: string } (email/username según tu modelo)
    • Respuesta: detalles mínimos del usuario o estado de validación.
    • Usa validaciones de lib/validation.ts y consultas en lib/db.ts.

  • POST /api/log-reset-attempt

    • Body: { identifier: string, status: 'success'|'fail', reason?: string }
    • Persiste cada intento en tabla de auditoría.

  • POST /api/init-neon

    • Inicialización controlada del esquema (según permisos/config). Úsalo sólo en entornos de desarrollo o protegidos.

Nota: Los nombres exactos de campos pueden variar con tu esquema. Revisa sql/init_neon.sql y lib/db.ts para detalles.

Middleware y Seguridad

  • middleware.ts: puede manejar rate limiting básico, protección de rutas o encabezados de seguridad.
  • Envía sólo información mínima al cliente; los endpoints deberían validar input y no filtrar datos sensibles.
  • Usa SSL en Neon (sslmode=require) y en despliegue.
  • Considera añadir:
    • Rate limiting por IP/identificador en log-reset-attempt
    • Captcha/turnstile para mitigar abuso
    • Logs estructurados y alertas

Flujo de Reseteo

  1. Usuario ingresa identificador en password-reset-form.tsx o flujo Microsoft.
  2. Frontend llama POST /api/verify-user.
  3. Si existe/permite reset, se registra intento via POST /api/log-reset-attempt.
  4. (Extensión) Enviar correo con token/OTP o redirigir a proveedor externo.

Componentes clave:

  • components/password-reset-form.tsx: UI principal de reseteo.
  • components/microsoft-reset-form.tsx: variante para flujos Microsoft/SSO.
  • components/db-status-indicator.tsx: muestra salud de DB consultando /api/check-db-connection.

Resolución de Problemas

  • Error de conexión a DB: revisa DATABASE_URL y que sslmode=require esté presente para Neon.
  • Migraciones/SQL fallan: asegúrate de correr npm run db:init con la URL correcta.
  • 403 al hacer push a GitHub: verifica SSH o usa HTTPS+PAT.
  • Variables no disponibles: en Next.js, las variables que necesitas en el cliente deben iniciar con NEXT_PUBLIC_.

Roadmap breve

  • Añadir tokens de reseteo con expiración y almacenamiento seguro.
  • Integración de correo (resend, SES, etc.).
  • Rate limiting y auditoría avanzada.
  • Tests e2e mínimos para flujo de reseteo.

Licencia

Ver LICENSE en la raíz del proyecto.