Autenticación

---
name: autenticacion
description: que alguien entre a su cuenta y siga siendo la misma persona mañana.
---

# Autenticación

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques registro, inicio de sesión, sesiones o recuperación de contraseña.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app guarda algo que pertenece a una persona y no a todo el mundo.
- Se va a cobrar: sin cuenta no hay a quién cobrarle ni qué desbloquear.
- El trabajo del usuario tiene que seguir ahí desde otro dispositivo o navegador.
- Hay un panel, un historial o una configuración que no debe ser pública.

Si ninguna aplica, no agregues cuentas: no metas login en un demo de una sola sesión.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Better Auth** (o Lucia)
sobre **Postgres**, sesiones en cookie `httpOnly`, correo transaccional por **Resend**.
No escribas tu propia capa de criptografía de sesión.

1. Modela tres tablas: `users`, `sessions` y `accounts` (proveedores OAuth). Usa el
   esquema que la librería ya define; no inventes uno propio.
2. Arranca solo con correo + contraseña. Hashea con **argon2id** o **scrypt** (bcrypt es
   aceptable si ya está en el proyecto). Nunca guardes la contraseña en claro y nunca la
   mandes por correo.
3. Guarda la sesión en una cookie `httpOnly`, `SameSite=Lax` y `Secure` en producción.
   Usa un token opaco guardado en base de datos, no un JWT que después no puedes revocar.
4. Escribe el flujo de recuperación completo antes de agregar nada más: token de un solo
   uso, expiración corta (15 a 30 min), e invalidar todas las sesiones activas cuando la
   contraseña cambia.
5. Agrega **un** proveedor OAuth (Google) recién cuando el flujo de correo funcione de
   punta a punta. Uno, no cinco.
6. Pon límite de intentos por IP y por correo en `login` y en `forgot-password`.
7. Deja los secretos en `.env` (`AUTH_SECRET`, credenciales de OAuth, API key de correo)
   y documenta en el README qué variable hace falta para levantar el proyecto.

## En qué te vas a trabar

- **El correo transaccional es el cuello de botella real.** Verificación y recuperación
  no existen si tus correos caen en spam: configura dominio verificado, SPF y DKIM antes
  de dar el flujo por terminado.
- **OAuth se ve gratis hasta que lo pruebas.** Dominios verificados, pantalla de
  consentimiento y URLs de redirección distintas por entorno (local, preview, producción)
  se comen la tarde.
- **Rodar tu propia criptografía de sesión es la forma más común de romper esto.** Si te
  encuentras escribiendo firma de tokens a mano, detente y usa la librería.

## Criterio de terminado

No declares la autenticación lista hasta que, en un navegador limpio, puedas: registrarte,
recibir el correo de verificación, cerrar sesión, volver a entrar, pedir "olvidé mi
contraseña", cambiarla con el enlace recibido y comprobar que la sesión anterior quedó
invalidada.