Breadstick-Crumbs/add-auth

add-auth은(는) 무엇을 하나요?

이 플러그인에 포함된 테스트된 인증 템플릿을 사용자의 프로젝트로 복사하고 연결합니다. 인증을 처음부터 작성하지 말고, 템플릿의 보안 로직은 변경하지 마세요. 오직 가장자리(데이터베이스 접근, 임포트, UI)만 조정하세요.

템플릿은 <skill-dir>/../../templates/에 위치하며, <skill-dir>은 이 스킬의 기본 디렉토리입니다.

• templates/fastapi/auth/ – FastAPI 패키지: config.py, security.py, models.py, db.py, deps.py, routes.py, email.py; 테스트는 templates/fastapi/tests/test_auth.py.
• templates/node/lib/auth/core.ts – 프레임워크에 독립적인 코어 (해싱, 액세스 및 재설정 토큰, 쿠키 옵션) 와 core.test.ts.
• templates/nextjs/ – Next.js App Router 레이어 (코어 위에): lib/auth/{schema,users,session,email}.ts, app/(auth)/actions.ts, proxy.ts.

1. 복사 전 확인

다음을 확인하고 한두 줄로 사용자에게 알리세요:

• 스택: FastAPI (pyproject나 requirements에서 fastapi 확인), Next.js (package.json의 next), 또는 다른 Node 서버 (Express, Hono, Fastify, 일반 http).
• 데이터베이스 계층: SQLModel/SQLAlchemy, Drizzle, Prisma 또는 raw SQL, 그리고 세션이나 db 객체가 있는 위치.
• 기존 인증: users 테이블, 로그인 라우트, JWT 라이브러리, 인증 제공자 (Clerk, Supabase, Auth.js). 인증이 이미 있으면 중단하고 교체할지 확장할지 물어보세요.
• 프로젝트에 이미 데이터가 있는 users 테이블이 있는지. 그렇다면 템플릿의 컬럼을 마이그레이션으로 매핑하고 두 번째 테이블을 만들지 마세요.

2. 복사 및 연결

파일을 읽고 다시 쓰지 말고 플러그인의 스크립트를 사용하여 복사하세요. 스크립트는 파일을 정확히 복사하며 토큰을 소모하지 않습니다. 스크립트는 이 스킬의 기본 디렉토리에서 두 단계 위에 있는 scripts/install.mjs (<skill-dir>/../../scripts/install.mjs)입니다. 프로젝트 루트에서 --dry-run으로 먼저 실행한 다음 실제로 실행하세요:

node <skill-dir>/../../scripts/install.mjs fastapi app --tests tests   # app/auth/*.py, tests/test_auth.py
node <skill-dir>/../../scripts/install.mjs nextjs .                     # 또는 @/ 별칭이 가리키는 경우 src/
node <skill-dir>/../../scripts/install.mjs node src/auth                # 다른 Node 서버용 코어만

대상 파일이 이미 존재하면 덮어쓰지 않고 아무것도 복사하지 않습니다. 충돌이 발생한 파일을 병합해야 하는 경우 (예: 기존 proxy.ts 또는 middleware.ts), --keep-existing으로 다시 실행하여 나머지를 복사한 다음 수동으로 병합하세요. --force는 사용자가 파일 손실에 동의한 경우에만 사용하세요. node를 사용할 수 없으면 동일한 파일을 수동으로 (cp) 복사하고 다시 입력하지 마세요.

복사 후에는 아래 단계에서 명명한 부분만 변경하세요. security.py, core.ts 및 라우트의 로직은 그대로 두세요.

FastAPI

1. install.mjs fastapi <package-dir> --tests <tests-dir> (예: app/auth/)로 복사합니다.
2. auth/db.py를 편집하여 get_session이 프로젝트의 기존 세션 의존성이 되도록 합니다. 이것이 auth가 데이터베이스 설정을 건드리는 유일한 부분입니다.
3. 프로젝트가 SQLModel이 아닌 일반 SQLAlchemy를 사용하는 경우, models.py의 User를 동일한 컬럼을 가진 SQLAlchemy 모델로 다시 작성하고 Pydantic 스키마는 유지합니다.
4. 앱의 메인 파일에서 app.include_router(auth_router)를 호출합니다.
5. user: CurrentUser 또는 dependencies=[Depends(require_role("admin"))]로 라우트를 보호합니다.
6. 의존성 추가: pyjwt, pwdlib[argon2,bcrypt], email-validator, python-multipart, sqlmodel (아직 없는 경우).
7. 프로젝트의 마이그레이션을 통해 users 테이블을 생성합니다 (Alembic이 있으면 Alembic 자동 생성 사용).
8. 복사된 test_auth.py의 임포트를 패키지 경로에 맞게 수정 (from auth를 from app.auth로) 하고 실행합니다.

Next.js (App Router)

1. install.mjs nextjs <app-root>로 복사: 코어와 테스트, lib/auth/*, app/(auth)/actions.ts, proxy.ts.
2. Next.js 15 이하: proxy.ts를 middleware.ts로 이름을 바꾸고 내보내기를 middleware로 변경합니다. 프로젝트에 이미 미들웨어/프록시 파일이 있으면 인증 검사를 해당 파일에 병합합니다.
3. lib/auth/users.ts를 프로젝트의 데이터베이스에 연결: db 임포트를 변경하거나 Prisma/raw SQL에 맞게 다섯 가지 함수를 다시 작성합니다. schema.ts를 기존 Drizzle 스키마에 병합하고 마이그레이션을 생성합니다.
4. 프록시의 PROTECTED를 앱의 비공개 경로로 설정합니다.
5. /sign-in, /sign-up, /forgot-password 및 /reset-password 페이지를 프로젝트 자체 컴포넌트와 스타일링을 사용하여 구축합니다. 각 페이지는 useActionState를 통해 해당 서버 액션에 POST하는 폼입니다. 로그인 시 next를 숨김 필드로 전달하고 재설정 시 token 검색 매개변수를 전달합니다.
6. 서버 컴포넌트와 액션에서 lib/auth/session.ts의 getUser() 또는 requireUser("admin")을 사용합니다.
7. 의존성: jose, bcryptjs, zod, server-only (Drizzle 파일을 그대로 사용하는 경우 drizzle-orm).

기타 Node 서버 (Express, Hono, Fastify, 일반 http)

install.mjs node <dir>로 코어만 복사합니다. 라우트는 프로젝트 스타일로 작성하되, templates/nextjs/app/(auth)/actions.ts와 동일한 동작을 유지하세요: 등록, 로그인 (알 수 없는 이메일과 잘못된 비밀번호에 대해 동일한 오류; 사용자를 찾을 수 없는 경우에도 verifyPassword 호출), 로그아웃, 나의 정보, 비밀번호 변경, 비밀번호 찾기 (계정 존재 여부에 관계없이 동일한 응답), 비밀번호 재설정 (readResetToken을 사용자의 현재 해시와 함께 사용). session 쿠키 (cookieOptions()로 설정) 또는 Authorization: Bearer 헤더에서 토큰을 읽습니다. requireUser/requireRole 미들웨어를 추가합니다.

3. 환경 변수

.env.example에 추가하세요 (커밋된 .env에는 절대 추가하지 마세요):

• AUTH_SECRET – 최소 32자의 임의 문자. 사용자의 로컬 .env에 대해 node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"로 생성하세요. 채팅에 절대 출력하지 마세요.
• AUTH_ACCESS_TOKEN_MINUTES (기본값 7일), AUTH_RESET_TOKEN_MINUTES (기본값 60).
• FastAPI: FRONTEND_URL, 그리고 재설정 이메일용 SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM. Next.js: APP_URL, 그런 다음 lib/auth/email.ts의 본문을 프로젝트의 이메일 제공자로 교체하세요. 이메일이 설정되지 않은 경우 재설정 링크는 로그에 기록되며, 이는 로컬 개발에 적합합니다.

4. 작동 확인

복사된 테스트와 프로젝트 자체 검사(테스트, 타입 검사, 린트, 빌드)를 실행하세요. 실패 시 출력과 함께 보고하세요. 그런 다음 사용자가 직접 수행해야 할 작업, 일반적으로 프로덕션에서 AUTH_SECRET 설정, 이메일 구성, 실제 데이터베이스에서 마이그레이션 실행을 알려주세요.

규칙

• 유지할 것: Argon2/bcrypt 해싱, 알 수 없는 이메일에 대한 더미 해시 검사, 알 수 없는 계정에 대한 동일한 응답, 비밀번호 해시에 연결된 재설정 토큰, 토큰의 purpose 검사, httpOnly SameSite=Lax 쿠키, 리디렉션 시 safeNext.
• localStorage에 토큰을 저장하지 말고, 비밀번호나 토큰을 로그에 기록하지 말고, 인증 라우트에 대해 CORS를 확장하지 마세요.
• 로그인 속도 제한은 템플릿에 포함되어 있지 않습니다. 프로젝트에 속도 제한기가 있으면 로그인 및 비밀번호 찾기 라우트를 그 뒤에 배치하고, 그렇지 않으면 언급하세요.
• 세션은 서명된 토큰이므로 로그아웃하면 해당 브라우저에서 세션이 종료되지만 복사된 토큰은 만료될 때까지 유효합니다. "모든 기기에서 로그아웃"이 필요한 경우 token_version 컬럼을 추가하고 토큰 판독기에서 이를 확인하세요.