Breadstick-Crumbs/add-auth

¿Qué hace add-auth?

Copia las plantillas de autenticación probadas de este plugin en el proyecto del usuario y conéctalas. No escribas autenticación desde cero ni cambies la lógica de seguridad en las plantillas; adapta solo los bordes (acceso a base de datos, importaciones, IU).

Las plantillas se encuentran en <skill-dir>/../../templates/, donde <skill-dir> es el directorio base de este skill:

• templates/fastapi/auth/ – Paquete FastAPI: config.py, security.py, models.py, db.py, deps.py, routes.py, email.py; pruebas en templates/fastapi/tests/test_auth.py.
• templates/node/lib/auth/core.ts – Núcleo sin framework (hashing, tokens de acceso y restablecimiento, opciones de cookies) con core.test.ts.
• templates/nextjs/ – Capa de Next.js App Router sobre el núcleo: lib/auth/{schema,users,session,email}.ts, app/(auth)/actions.ts, proxy.ts.

1. Revisar antes de copiar

Averigua e informa al usuario en una o dos líneas:

• Stack: FastAPI (busca fastapi en pyproject/requirements), Next.js (next en package.json) u otro servidor Node (Express, Hono, Fastify, http plano).
• Capa de base de datos: SQLModel/SQLAlchemy, Drizzle, Prisma o SQL puro, y dónde reside la sesión o el objeto db.
• Autenticación existente: una tabla users, una ruta de login, una librería JWT, un proveedor de autenticación (Clerk, Supabase, Auth.js). Si ya existe autenticación, detente y pregunta si reemplazarla o extenderla.
• Si el proyecto ya tiene una tabla users con datos. Si es así, mapea las columnas de la plantilla sobre ella con una migración en lugar de crear una segunda tabla.

2. Copiar y conectar

Copia con el script del plugin, no leyendo y reescribiendo los archivos: los copia exactamente y no cuesta tokens. Es scripts/install.mjs dos niveles arriba del directorio base de este skill (<skill-dir>/../../scripts/install.mjs). Ejecútalo desde la raíz del proyecto con --dry-run primero, luego de verdad:

node <skill-dir>/../../scripts/install.mjs fastapi app --tests tests   # app/auth/*.py, tests/test_auth.py
node <skill-dir>/../../scripts/install.mjs nextjs .                     # o src/ si el alias @/ apunta allí
node <skill-dir>/../../scripts/install.mjs node src/auth                # solo núcleo, para otros servidores Node

Se niega a sobrescribir y no copia nada si algún archivo destino existe. Cuando el conflicto es un archivo a fusionar (un proxy.ts o middleware.ts existente), vuélvelo a ejecutar con --keep-existing, que copia el resto, luego fusiona manualmente. Usa --force solo una vez que el usuario acepte perder el archivo. Si node no está disponible, copia los mismos archivos manualmente (cp), y aún así no los reescribas.

Después de copiar, cambia solo lo que nombran los pasos siguientes. Deja intacta la lógica en security.py, core.ts y las rutas.

FastAPI

1. Copia con install.mjs fastapi <directorio-paquete> --tests <directorio-pruebas> (por ejemplo app/auth/).
2. Edita auth/db.py para que get_session sea la dependencia de sesión existente del proyecto. Ese es el único lugar donde la autenticación toca la configuración de la base de datos.
3. Si el proyecto usa SQLAlchemy puro, no SQLModel, reescribe models.py's User como un modelo de SQLAlchemy con las mismas columnas y conserva los esquemas Pydantic.
4. app.include_router(auth_router) en el archivo principal de la aplicación.
5. Protege rutas con user: CurrentUser o dependencies=[Depends(require_role("admin"))].
6. Añade dependencias: pyjwt, pwdlib[argon2,bcrypt], email-validator, python-multipart, sqlmodel (si aún no está presente).
7. Crea la tabla users a través de las migraciones del proyecto (autogeneración de Alembic si tiene Alembic).
8. Arregla las importaciones en el test_auth.py copiado a la ruta del paquete (from auth se convierte en, por ejemplo, from app.auth), y ejecútalo.

Next.js (App Router)

1. Copia con install.mjs nextjs <raíz-app>: el núcleo con su prueba, lib/auth/*, app/(auth)/actions.ts y proxy.ts.
2. Next.js 15 o anterior: renombra proxy.ts a middleware.ts y su exportación a middleware. Si el proyecto ya tiene un archivo middleware/proxy, fusiona la comprobación de autenticación en él.
3. Apunta lib/auth/users.ts a la base de datos del proyecto: cambia la importación de db, o reescribe sus cinco funciones para Prisma/SQL puro. Fusiona schema.ts con el esquema Drizzle existente y genera una migración.
4. Establece PROTECTED en el proxy a las rutas privadas de la aplicación.
5. Construye las páginas /sign-in, /sign-up, /forgot-password y /reset-password usando los propios componentes y estilos del proyecto. Cada una es un formulario que publica en la acción de servidor correspondiente a través de useActionState; pasa next como un campo oculto en el inicio de sesión, y el parámetro de búsqueda token en el restablecimiento.
6. En componentes y acciones de servidor, usa getUser() o requireUser("admin") de lib/auth/session.ts.
7. Dependencias: jose, bcryptjs, zod, server-only (y drizzle-orm si se usa el archivo Drizzle tal cual).

Otros servidores Node (Express, Hono, Fastify, http plano)

Copia solo el núcleo con install.mjs node <directorio>. Escribe las rutas en el estilo del proyecto, manteniendo el mismo comportamiento que templates/nextjs/app/(auth)/actions.ts: registro, inicio de sesión (mismo error para correo desconocido y contraseña incorrecta; llama a verifyPassword incluso cuando el usuario no se encuentra), cierre de sesión, yo, cambio de contraseña, olvidé contraseña (misma respuesta exista o no la cuenta), restablecer contraseña (readResetToken con el hash actual del usuario). Lee el token de la cookie session (establecida con cookieOptions()) o un encabezado Authorization: Bearer. Añade un middleware requireUser/requireRole.

3. Entorno

Añade a .env.example (nunca a un .env confirmado):

• AUTH_SECRET – al menos 32 caracteres aleatorios. Genera uno para el .env local del usuario con node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"; nunca lo imprimas en el chat.
• AUTH_ACCESS_TOKEN_MINUTES (por defecto 7 días), AUTH_RESET_TOKEN_MINUTES (por defecto 60).
• FastAPI: FRONTEND_URL, y SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM para correos de restablecimiento. Next.js: APP_URL, luego reemplaza el cuerpo de lib/auth/email.ts con el proveedor de correo del proyecto. Sin correo configurado, los enlaces de restablecimiento se registran, lo cual está bien para desarrollo local.

4. Verificar que funciona

Ejecuta las pruebas copiadas y las propias verificaciones del proyecto (pruebas, verificación de tipos, lint, compilación). Reporta fallos con su salida. Luego di lo que el usuario aún tiene que hacer por sí mismo, usualmente: establecer AUTH_SECRET en producción, configurar el correo, ejecutar la migración en su base de datos real.

Reglas

• Mantener: hashing Argon2/bcrypt, la comprobación de hash ficticio en correos desconocidos, mismas respuestas para cuentas desconocidas, tokens de restablecimiento vinculados al hash de la contraseña, comprobaciones de purpose en tokens, cookies httpOnly SameSite=Lax, safeNext en redirecciones.
• No pongas tokens en localStorage, no registres contraseñas o tokens, no amplíes CORS para rutas de autenticación.
• La limitación de tasa de inicio de sesión no está en las plantillas. Si el proyecto tiene un limitador de tasa, pon las rutas de inicio de sesión y olvidé contraseña detrás de él; si no, menciónalo.
• Las sesiones son tokens firmados, por lo que cerrar sesión termina la sesión en ese navegador pero un token copiado sigue siendo válido hasta que expire. Si el usuario necesita "cerrar sesión en todos lados", añade una columna token_version y compruébala en el lector de tokens.