Breadstick-Crumbs/add-auth

O que add-auth faz?

Copie os templates de autenticação testados neste plugin para o projeto do usuário e conecte-os. Não escreva autenticação do zero e não altere a lógica de segurança nos templates; adapte apenas as bordas (acesso ao banco de dados, importações, interface de usuário).

Os templates estão em <skill-dir>/../../templates/, onde <skill-dir> é o diretório base desta skill:

• templates/fastapi/auth/ – Pacote FastAPI: config.py, security.py, models.py, db.py, deps.py, routes.py, email.py; testes em templates/fastapi/tests/test_auth.py.
• templates/node/lib/auth/core.ts – Núcleo independente de framework (hashing, tokens de acesso e redefinição, opções de cookie) com core.test.ts.
• templates/nextjs/ – Camada Next.js App Router sobre o núcleo: lib/auth/{schema,users,session,email}.ts, app/(auth)/actions.ts, proxy.ts.

1. Verifique antes de copiar

Descubra e informe ao usuário em uma ou duas linhas:

• Stack: FastAPI (procure por fastapi em pyproject/requirements), Next.js (next em package.json), ou outro servidor Node (Express, Hono, Fastify, http puro).
• Camada de banco de dados: SQLModel/SQLAlchemy, Drizzle, Prisma ou SQL puro, e onde a sessão ou o objeto db reside.
• Autenticação existente: uma tabela users, uma rota de login, uma biblioteca JWT, um provedor de autenticação (Clerk, Supabase, Auth.js). Se a autenticação já existir, pare e pergunte se deve substituí-la ou estendê-la.
• Se o projeto já possui uma tabela users com dados. Nesse caso, mapeie as colunas do template para ela com uma migração, em vez de criar uma segunda tabela.

2. Copie e conecte

Copie com o script do plugin, não lendo e reescrevendo os arquivos: ele os copia exatamente e não custa tokens. É scripts/install.mjs dois níveis acima do diretório base desta skill (<skill-dir>/../../scripts/install.mjs). Execute a partir da raiz do projeto com --dry-run primeiro, depois para valer:

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/ se o alias @/ apontar para lá
node <skill-dir>/../../scripts/install.mjs node src/auth                # apenas o núcleo, para outros servidores Node

Ele se recusa a sobrescrever e não copia nada se algum arquivo de destino existir. Quando a colisão for um arquivo para mesclar (um proxy.ts ou middleware.ts existente), execute novamente com --keep-existing, que copia o restante, depois mescle manualmente. Use --force apenas quando o usuário concordar em perder o arquivo. Se node não estiver disponível, copie os mesmos arquivos manualmente (cp) e ainda assim não os redigite.

Após copiar, altere apenas o que as etapas abaixo nomeiam. Deixe a lógica em security.py, core.ts e as rotas intocadas.

FastAPI

1. Copie com install.mjs fastapi <package-dir> --tests <tests-dir> (por exemplo app/auth/).
2. Edite auth/db.py para que get_session seja a dependência de sessão existente no projeto. Esse é o único lugar onde a autenticação toca a configuração do banco de dados.
3. Se o projeto usar SQLAlchemy puro, não SQLModel, reescreva o modelo User de models.py como um modelo SQLAlchemy com as mesmas colunas e mantenha os esquemas Pydantic.
4. app.include_router(auth_router) no arquivo principal do app.
5. Proteja rotas com user: CurrentUser ou dependencies=[Depends(require_role("admin"))].
6. Adicione dependências: pyjwt, pwdlib[argon2,bcrypt], email-validator, python-multipart, sqlmodel (se ainda não estiver presente).
7. Crie a tabela users através das migrações do projeto (Alembic autogenerate se tiver Alembic).
8. Corrija as importações no test_auth.py copiado para o caminho do pacote (from auth vira, por exemplo, from app.auth) e execute-o.

Next.js (App Router)

1. Copie com install.mjs nextjs <app-root>: o núcleo com seu teste, lib/auth/*, app/(auth)/actions.ts e proxy.ts.
2. Next.js 15 ou anterior: renomeie proxy.ts para middleware.ts e sua exportação para middleware. Se o projeto já tiver um arquivo middleware/proxy, mescle a verificação de autenticação nele.
3. Aponte lib/auth/users.ts para o banco de dados do projeto: altere a importação de db, ou reescreva suas cinco funções para Prisma/SQL puro. Mescle schema.ts no esquema Drizzle existente e gere uma migração.
4. Defina PROTECTED no proxy para os caminhos privados do app.
5. Construa as páginas /sign-in, /sign-up, /forgot-password e /reset-password usando os próprios componentes e estilos do projeto. Cada uma é um formulário que envia para a server action correspondente através de useActionState; passe next como um campo oculto no login e o parâmetro de busca token na redefinição.
6. Em componentes e actions do servidor, use getUser() ou requireUser("admin") de lib/auth/session.ts.
7. Dependências: jose, bcryptjs, zod, server-only (e drizzle-orm se estiver usando o arquivo Drizzle como está).

Outros servidores Node (Express, Hono, Fastify, http puro)

Copie apenas o núcleo com install.mjs node <dir>. Escreva as rotas no estilo do projeto, mantendo o mesmo comportamento de templates/nextjs/app/(auth)/actions.ts: register, login (mesmo erro para email desconhecido e senha errada; chame verifyPassword mesmo quando o usuário não for encontrado), logout, me, alterar senha, esqueci a senha (mesma resposta, existindo ou não a conta), redefinir senha (readResetToken com o hash atual do usuário). Leia o token do cookie session (definido com cookieOptions()) ou de um cabeçalho Authorization: Bearer. Adicione um middleware requireUser/requireRole.

3. Ambiente

Adicione ao .env.example (nunca a um .env commitado):

• AUTH_SECRET – pelo menos 32 caracteres aleatórios. Gere um para o .env local do usuário com node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"; nunca imprima no chat.
• AUTH_ACCESS_TOKEN_MINUTES (padrão 7 dias), AUTH_RESET_TOKEN_MINUTES (padrão 60).
• FastAPI: FRONTEND_URL, e SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM para emails de redefinição. Next.js: APP_URL, depois substitua o corpo de lib/auth/email.ts pelo provedor de email do projeto. Sem email configurado, os links de redefinição são registrados no log, o que é aceitável para desenvolvimento local.

4. Verifique se funciona

Execute os testes copiados e as próprias verificações do projeto (testes, type-check, lint, build). Relate falhas com sua saída. Depois diga o que o usuário ainda precisa fazer manualmente, geralmente: definir AUTH_SECRET em produção, configurar email, executar a migração no banco de dados real.

Regras

• Manter: hashing Argon2/bcrypt, a verificação de hash dummy para emails desconhecidos, mesmas respostas para contas desconhecidas, tokens de redefinição vinculados ao hash da senha, verificações de purpose nos tokens, cookies httpOnly SameSite=Lax, safeNext em redirecionamentos.
• Não colocar tokens em localStorage, não registrar senhas ou tokens, não ampliar CORS para rotas de autenticação.
• Limitação de taxa de login não está nos templates. Se o projeto tiver um limitador de taxa, coloque as rotas de login e esqueci a senha atrás dele; caso contrário, mencione isso.
• Sessões são tokens assinados, portanto, fazer logout encerra a sessão naquele navegador, mas um token copiado permanece válido até expirar. Se o usuário precisar de "deslogar de todos os lugares", adicione uma coluna token_version e verifique-a no leitor de tokens.