API y autenticación

El proyecto se encuentra en apps/api. Ejecuta Hono sobre Node y expone los servicios compartidos por Academy y Admin.

Desarrollo

cp apps/api/.env.example apps/api/.env
pnpm --filter @millennium/api db:migrate
pnpm --filter @millennium/api dev

Antes de iniciar, cree una base PostgreSQL local, genere BETTER_AUTH_SECRET con openssl rand -base64 32 y configure Cloudflare Email, ZeptoMail o ambos. Por defecto, la API escucha en http://localhost:4000; Academy utiliza http://localhost:3000 y Admin http://localhost:3001.

Autenticación

Better Auth atiende /api/auth/*. El registro y el inicio de sesión por correo aceptan contraseñas de 12 a 128 caracteres. Una identidad registrada con contraseña debe verificar su correo antes de obtener una sesión; el enlace vence en una hora y no inicia sesión automáticamente.

La verificación puede reenviarse sin revelar si la identidad existe. La recuperación de contraseña usa enlaces de un solo uso válidos durante 30 minutos. Al completar el cambio se revocan todas las sesiones y los demás enlaces de recuperación pendientes de la identidad.

Academy y Admin proporcionan callbackURL o redirectTo absolutos; únicamente se aceptan destinos bajo TRUSTED_ORIGINS. Los correos se envían en segundo plano y contienen versiones HTML y texto.

Academy y Admin deben enviar credenciales en sus solicitudes. La cookie de sesión pertenece al host de la API, es httpOnly, usa SameSite=Lax y añade Secure en producción. No se comparte una cookie global entre subdominios.

• La referencia interactiva está en /api/auth/reference.
• El documento OpenAPI 3.1 está en /api/auth/open-api/generate-schema.

Operación

La API requiere DATABASE_URL, BETTER_AUTH_URL, BETTER_AUTH_SECRET, TRUSTED_ORIGINS y al menos un proveedor de correo. Cloudflare usa CLOUDFLARE_ACCOUNT_ID junto con CLOUDFLARE_EMAIL_API_TOKEN; ZeptoMail usa ZEPTOMAIL_API_TOKEN. En producción, la URL pública es https://api.mileniumacademy.com; los orígenes confiables son https://mileniumacademy.com y https://admin.mileniumacademy.com.

Cuando ambos proveedores están configurados, Cloudflare es el principal. ZeptoMail actúa como respaldo solo ante un rechazo explícito, incluida cuota o rate limit. Un timeout de 10 segundos, una desconexión o una respuesta ilegible se considera ambiguo y no activa un segundo envío. Los eventos de fallo no incluyen direcciones, tokens, cookies, secretos ni URLs completas.

Los cambios de esquema se generan y aplican con migraciones versionadas:

pnpm --filter @millennium/api auth:schema
pnpm --filter @millennium/api db:generate
pnpm --filter @millennium/api db:migrate

Producción no debe usar drizzle-kit push. Los secretos y las credenciales de PlanetScale se administran fuera del repositorio. Consulte apps/api/README.md para la lista completa de variables y el procedimiento de pruebas.