Breadstick-Crumbs/add-auth

Que fait add-auth ?

Copiez les modèles d'authentification testés de ce plugin dans le projet de l'utilisateur et intégrez-les. N'écrivez pas l'authentification de zéro et ne modifiez pas la logique de sécurité dans les modèles ; adaptez uniquement les contours (accès à la base de données, importations, interface utilisateur).

Les modèles se trouvent sous <skill-dir>/../../templates/, où <skill-dir> est le répertoire de base de cette compétence :

• templates/fastapi/auth/ – Package FastAPI : config.py, security.py, models.py, db.py, deps.py, routes.py, email.py ; tests dans templates/fastapi/tests/test_auth.py.
• templates/node/lib/auth/core.ts – Noyau sans framework (hachage, tokens d'accès et de réinitialisation, options de cookie) avec core.test.ts.
• templates/nextjs/ – Couche Next.js App Router par-dessus le noyau : lib/auth/{schema,users,session,email}.ts, app/(auth)/actions.ts, proxy.ts.

1. Regarder avant de copier

Identifiez et dites à l'utilisateur en une ou deux lignes :

• Pile : FastAPI (cherchez fastapi dans pyproject/requirements), Next.js (next dans package.json), ou un autre serveur Node (Express, Hono, Fastify, http simple).
• Couche de base de données : SQLModel/SQLAlchemy, Drizzle, Prisma ou SQL brut, et où se trouve l'objet session ou db.
• Authentification existante : une table users, une route de connexion, une bibliothèque JWT, un fournisseur d'authentification (Clerk, Supabase, Auth.js). Si l'authentification existe déjà, arrêtez-vous et demandez s'il faut la remplacer ou l'étendre.
• Si le projet possède déjà une table users avec des données. Si c'est le cas, mappez les colonnes du modèle sur celles-ci avec une migration au lieu de créer une deuxième table.

2. Copier et intégrer

Copiez avec le script du plugin, pas en lisant et réécrivant les fichiers : il les copie exactement et ne coûte aucun token. Il s'agit de scripts/install.mjs deux niveaux au-dessus du répertoire de base de cette compétence (<skill-dir>/../../scripts/install.mjs). Exécutez-le depuis la racine du projet d'abord avec --dry-run, puis pour de vrai :

node <skill-dir>/../../scripts/install.mjs fastapi app --tests tests   # app/auth/*.py, tests/test_auth.py
node <skill-dir>/../../scripts/install.mjs nextjs .                     # ou src/ si l'alias @/ pointe là
node <skill-dir>/../../scripts/install.mjs node src/auth                # noyau uniquement, pour les autres serveurs Node

Il refuse d'écraser et ne copie rien si un fichier cible existe. Lorsque le conflit est un fichier à fusionner (un proxy.ts ou middleware.ts existant), relancez avec --keep-existing, qui copie le reste, puis fusionnez manuellement. Utilisez --force seulement une fois que l'utilisateur a accepté de perdre le fichier. Si node n'est pas disponible, copiez les mêmes fichiers à la main (cp), et ne les retapez toujours pas.

Après la copie, modifiez uniquement ce que les étapes ci-dessous nomment. Laissez la logique dans security.py, core.ts et les routes tranquille.

FastAPI

1. Copiez avec install.mjs fastapi <package-dir> --tests <tests-dir> (par exemple app/auth/).
2. Modifiez auth/db.py pour que get_session soit la dépendance de session existante du projet. C'est le seul endroit où l'authentification touche à la configuration de la base de données.
3. Si le projet utilise du SQLAlchemy pur, pas SQLModel, réécrivez le modèle User de models.py en tant que modèle SQLAlchemy avec les mêmes colonnes et conservez les schémas Pydantic.
4. app.include_router(auth_router) dans le fichier principal de l'application.
5. Protégez les routes avec user: CurrentUser ou dependencies=[Depends(require_role("admin"))].
6. Ajoutez les dépendances : pyjwt, pwdlib[argon2,bcrypt], email-validator, python-multipart, sqlmodel (si pas déjà présent).
7. Créez la table users via les migrations du projet (Alembic autogenerate s'il a Alembic).
8. Corrigez les importations dans le test_auth.py copié vers le chemin du package (from auth devient, disons, from app.auth), et exécutez-le.

Next.js (App Router)

1. Copiez avec install.mjs nextjs <app-root> : le noyau avec son test, lib/auth/*, app/(auth)/actions.ts et proxy.ts.
2. Next.js 15 ou antérieur : renommez proxy.ts en middleware.ts et son export en middleware. Si le projet a déjà un fichier middleware/proxy, fusionnez la vérification d'authentification dedans.
3. Pointez lib/auth/users.ts vers la base de données du projet : changez l'import de db, ou réécrivez ses cinq fonctions pour Prisma/SQL brut. Fusionnez schema.ts dans le schéma Drizzle existant et générez une migration.
4. Définissez PROTECTED dans le proxy vers les chemins privés de l'application.
5. Construisez les pages /sign-in, /sign-up, /forgot-password et /reset-password en utilisant les propres composants et styles du projet. Chacune est un formulaire envoyant vers l'action serveur correspondante via useActionState ; passez next comme champ caché sur la connexion, et le paramètre de recherche token sur la réinitialisation.
6. Dans les composants serveur et les actions, utilisez getUser() ou requireUser("admin") de lib/auth/session.ts.
7. Dépendances : jose, bcryptjs, zod, server-only (et drizzle-orm si vous utilisez le fichier Drizzle tel quel).

Autres serveurs Node (Express, Hono, Fastify, http simple)

Copiez uniquement le noyau avec install.mjs node <dir>. Écrivez les routes dans le style du projet, en conservant le même comportement que templates/nextjs/app/(auth)/actions.ts : enregistrement, connexion (même erreur pour email inconnu et mot de passe incorrect ; appelez verifyPassword même lorsque l'utilisateur n'est pas trouvé), déconnexion, moi, changement de mot de passe, mot de passe oublié (même réponse que le compte existe ou non), réinitialisation du mot de passe (readResetToken avec le hachage actuel de l'utilisateur). Lisez le token depuis le cookie session (défini avec cookieOptions()) ou un en-tête Authorization: Bearer. Ajoutez un middleware requireUser/requireRole.

3. Environnement

Ajoutez à .env.example (jamais dans un .env commité) :

• AUTH_SECRET – au moins 32 caractères aléatoires. Générez-en un pour le .env local de l'utilisateur avec node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))" ; ne l'imprimez jamais dans le chat.
• AUTH_ACCESS_TOKEN_MINUTES (par défaut 7 jours), AUTH_RESET_TOKEN_MINUTES (par défaut 60).
• FastAPI : FRONTEND_URL, et SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM pour les e-mails de réinitialisation. Next.js : APP_URL, puis remplacez le corps de lib/auth/email.ts par le fournisseur d'e-mail du projet. Sans e-mail configuré, les liens de réinitialisation sont journalisés, ce qui est acceptable pour le développement local.

4. Vérifier que ça fonctionne

Exécutez les tests copiés et les propres vérifications du projet (tests, vérification de type, lint, build). Signalez les échecs avec leur sortie. Dites ensuite ce que l'utilisateur doit encore faire lui-même, généralement : définir AUTH_SECRET en production, configurer l'e-mail, exécuter la migration sur sa base de données réelle.

Règles

• Conservez : le hachage Argon2/bcrypt, la vérification par hachage factice sur les e-mails inconnus, les mêmes réponses pour les comptes inconnus, les tokens de réinitialisation liés au hachage du mot de passe, les vérifications de purpose sur les tokens, les cookies httpOnly SameSite=Lax, safeNext sur les redirections.
• Ne mettez pas les tokens dans localStorage, ne journalisez pas les mots de passe ou les tokens, n'élargissez pas CORS pour les routes d'authentification.
• La limitation de débit de connexion n'est pas dans les modèles. Si le projet a un limiteur de débit, placez les routes de connexion et de mot de passe oublié derrière lui ; sinon, mentionnez-le.
• Les sessions sont des tokens signés, donc la déconnexion termine la session dans ce navigateur mais un token copié reste valide jusqu'à son expiration. Si l'utilisateur a besoin de "déconnexion partout", ajoutez une colonne token_version et vérifiez-la dans le lecteur de token.