Breadstick-Crumbs/add-auth

Was macht add-auth?

Kopiere die getesteten Auth-Vorlagen in diesem Plugin in das Projekt des Benutzers und binde sie ein. Schreibe Auth nicht von Grund auf neu und ändere die Sicherheitslogik in den Vorlagen nicht; passe nur die Kanten an (Datenbankzugriff, Imports, UI).

Die Vorlagen befinden sich unter <skill-dir>/../../templates/, wobei <skill-dir> das Basisverzeichnis dieses Skills ist:

• templates/fastapi/auth/ – FastAPI-Paket: config.py, security.py, models.py, db.py, deps.py, routes.py, email.py; Tests in templates/fastapi/tests/test_auth.py.
• templates/node/lib/auth/core.ts – Framework-freier Kern (Hashing, Zugriffs- und Reset-Tokens, Cookie-Optionen) mit core.test.ts.
• templates/nextjs/ – Next.js App Router-Schicht auf dem Kern: lib/auth/{schema,users,session,email}.ts, app/(auth)/actions.ts, proxy.ts.

1. Vor dem Kopieren prüfen

Finde heraus und teile dem Benutzer in ein oder zwei Zeilen mit:

• Stack: FastAPI (suche nach fastapi in pyproject/requirements), Next.js (next in package.json), oder ein anderer Node-Server (Express, Hono, Fastify, einfaches http).
• Datenbankschicht: SQLModel/SQLAlchemy, Drizzle, Prisma oder rohes SQL, und wo das Session- oder db-Objekt lebt.
• Vorhandene Auth: eine users-Tabelle, eine Login-Route, eine JWT-Bibliothek, ein Auth-Provider (Clerk, Supabase, Auth.js). Wenn Auth bereits existiert, stoppe und frage, ob es ersetzt oder erweitert werden soll.
• Ob das Projekt bereits eine users-Tabelle mit Daten hat. Falls ja, bilde die Spalten der Vorlage darauf mit einer Migration ab, anstatt eine zweite Tabelle zu erstellen.

2. Kopieren und einbinden

Kopiere mit dem Skript des Plugins, nicht durch Lesen und Neuschreiben der Dateien: Es kopiert sie exakt und kostet keine Tokens. Es ist scripts/install.mjs zwei Ebenen über dem Basisverzeichnis dieses Skills (<skill-dir>/../../scripts/install.mjs). Führe es zuerst mit --dry-run vom Projektstamm aus, dann wirklich:

node <skill-dir>/../../scripts/install.mjs fastapi app --tests tests   # app/auth/*.py, tests/test_auth.py
node <skill-dir>/../../scripts/install.mjs nextjs .                     # oder src/ wenn der @/-Alias dorthin zeigt
node <skill-dir>/../../scripts/install.mjs node src/auth                # nur Kern, für andere Node-Server

Es verweigert das Überschreiben und kopiert nichts, wenn eine Zieldatei existiert. Wenn der Konflikt eine Datei ist, in die hinein gemergt werden soll (eine vorhandene proxy.ts oder middleware.ts), führe erneut mit --keep-existing aus, was den Rest kopiert, und merge dann von Hand. Verwende --force nur, nachdem der Benutzer zugestimmt hat, die Datei zu verlieren. Wenn node nicht verfügbar ist, kopiere dieselben Dateien von Hand (cp), und tippe sie trotzdem nicht neu ab.

Ändere nach dem Kopieren nur das, was die folgenden Schritte benennen. Lasse die Logik in security.py, core.ts und den Routen in Ruhe.

FastAPI

1. Kopiere mit install.mjs fastapi <package-dir> --tests <tests-dir> (z. B. app/auth/).
2. Bearbeite auth/db.py, sodass get_session die vorhandene Session-Abhängigkeit des Projekts ist. Das ist die einzige Stelle, an der Auth die Datenbankeinrichtung berührt.
3. Wenn das Projekt reines SQLAlchemy verwendet, nicht SQLModel, schreibe models.py's User als SQLAlchemy-Modell mit denselben Spalten um und behalte die Pydantic-Schemas.
4. app.include_router(auth_router) in der Hauptdatei der App.
5. Schütze Routen mit user: CurrentUser oder dependencies=[Depends(require_role("admin"))].
6. Füge Abhängigkeiten hinzu: pyjwt, pwdlib[argon2,bcrypt], email-validator, python-multipart, sqlmodel (falls nicht bereits vorhanden).
7. Erstelle die users-Tabelle über die Migrationen des Projekts (Alembic autogenerate, wenn es Alembic hat).
8. Korrigiere die Imports in der kopierten test_auth.py auf den Paketpfad (from auth wird z. B. zu from app.auth), und führe sie aus.

Next.js (App Router)

1. Kopiere mit install.mjs nextjs <app-root>: den Kern mit seinem Test, lib/auth/*, app/(auth)/actions.ts und proxy.ts.
2. Next.js 15 oder älter: benenne proxy.ts in middleware.ts um und seinen Export in middleware. Wenn das Projekt bereits eine Middleware/Proxy-Datei hat, merge den Auth-Check hinein.
3. Weise lib/auth/users.ts auf die Datenbank des Projekts: ändere den db-Import oder schreibe seine fünf Funktionen für Prisma/rohes SQL um. Merge schema.ts in das vorhandene Drizzle-Schema und generiere eine Migration.
4. Setze PROTECTED im Proxy auf die privaten Pfade der App.
5. Erstelle Seiten für /sign-in, /sign-up, /forgot-password und /reset-password mit den eigenen Komponenten und dem Styling des Projekts. Jede ist ein Formular, das die passende Server-Aktion über useActionState aufruft; übergib next als verstecktes Feld bei der Anmeldung und den token-Suchparameter beim Zurücksetzen.
6. Verwende in Server-Komponenten und -Aktionen getUser() oder requireUser("admin") aus lib/auth/session.ts.
7. Abhängigkeiten: jose, bcryptjs, zod, server-only (und drizzle-orm, wenn die Drizzle-Datei unverändert verwendet wird).

Andere Node-Server (Express, Hono, Fastify, einfaches http)

Kopiere nur den Kern mit install.mjs node <dir>. Schreibe die Routen im Stil des Projekts, wobei das gleiche Verhalten wie in templates/nextjs/app/(auth)/actions.ts beibehalten wird: registrieren, anmelden (gleicher Fehler für unbekannte E-Mail und falsches Passwort; rufe verifyPassword auf, auch wenn der Benutzer nicht gefunden wird), abmelden, ich, Passwort ändern, Passwort vergessen (gleiche Antwort, ob das Konto existiert oder nicht), Passwort zurücksetzen (readResetToken mit dem aktuellen Hash des Benutzers). Lese das Token aus dem session-Cookie (gesetzt mit cookieOptions()) oder einem Authorization: Bearer-Header. Füge eine requireUser/requireRole-Middleware hinzu.

3. Umgebung

Füge zu .env.example hinzu (niemals zu einem committeten .env):

• AUTH_SECRET – mindestens 32 zufällige Zeichen. Generiere einen für das lokale .env des Benutzers mit node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"; gib ihn niemals im Chat aus.
• AUTH_ACCESS_TOKEN_MINUTES (Standard 7 Tage), AUTH_RESET_TOKEN_MINUTES (Standard 60).
• FastAPI: FRONTEND_URL, und SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM für Reset-E-Mails. Next.js: APP_URL, ersetze dann den Inhalt von lib/auth/email.ts mit dem E-Mail-Provider des Projekts. Ohne konfigurierte E-Mail werden Reset-Links protokolliert, was für die lokale Entwicklung in Ordnung ist.

4. Prüfen, ob es funktioniert

Führe die kopierten Tests und die eigenen Prüfungen des Projekts aus (Tests, Typprüfung, Linting, Build). Melde Fehler mit ihrer Ausgabe. Sage dann, was der Benutzer noch selbst erledigen muss, normalerweise: AUTH_SECRET in der Produktion setzen, E-Mail konfigurieren, die Migration auf der echten Datenbank ausführen.

Regeln

• Behalte: Argon2/bcrypt-Hashing, den Dummy-Hash-Check bei unbekannten E-Mails, gleiche Antworten für unbekannte Konten, Reset-Tokens gebunden an den Passwort-Hash, purpose-Prüfungen auf Tokens, httpOnly SameSite=Lax-Cookies, safeNext bei Weiterleitungen.
• Lege Tokens nicht in localStorage ab, protokolliere keine Passwörter oder Tokens, erweitere CORS nicht für Auth-Routen.
• Login-Ratenbegrenzung ist nicht in den Vorlagen enthalten. Wenn das Projekt einen Ratenbegrenzer hat, setze die Login- und Passwort-vergessen-Routen dahinter; wenn nicht, erwähne es.
• Sitzungen sind signierte Tokens, daher beendet das Abmelden die Sitzung in diesem Browser, aber ein kopiertes Token bleibt gültig, bis es abläuft. Wenn der Benutzer "überall abmelden" benötigt, füge eine token_version-Spalte hinzu und prüfe sie im Token-Leser.