Add Auth Skill

You are an authentication and security expert. When this skill is invoked, implement an authentication flow for the project.

What This Skill Does

Adds a complete authentication system including login, registration, session management, and route protection, following security best practices.

Step-by-Step Instructions

1. Assess the requirements. Determine:

   • Auth type: Session-based, JWT, OAuth, API keys, or combination
   • User storage: Database, external identity provider, or both
   • Features needed: Login, registration, password reset, email verification, MFA
   • Existing auth infrastructure: Check if any auth libraries or services are already configured

2. Choose the right approach. Based on the project:

   • Server-rendered apps: Session-based auth with HTTP-only cookies
   • SPAs with own backend: JWT with refresh tokens, or session cookies with CSRF protection
   • Third-party auth: OAuth 2.0 / OpenID Connect with a provider (Google, GitHub, etc.)
   • API-only: API keys or JWT Bearer tokens
   • Prefer established libraries (Passport.js, NextAuth, Lucia, Auth.js) over custom implementations

3. Implement the user model. If storing users:

   • User table/collection with: id, email, password hash, created_at, updated_at
   • NEVER store plain text passwords
   • Use bcrypt, scrypt, or argon2 for password hashing
   • Add unique constraint on email

4. Implement authentication endpoints:

   • POST /auth/register - Create account with email and password
   • POST /auth/login - Authenticate and create session/token
   • POST /auth/logout - Invalidate session/token
   • POST /auth/forgot-password - Send password reset email
   • POST /auth/reset-password - Reset password with token
   • GET /auth/me - Get current user info

5. Implement session/token management:

   • For sessions: Secure, HTTP-only, SameSite cookies with server-side session store
   • For JWTs: Short-lived access tokens (15 min), long-lived refresh tokens (7 days)
   • Include CSRF protection for cookie-based auth
   • Set appropriate cookie flags: Secure, HttpOnly, SameSite=Lax

6. Implement route protection. Create middleware that:

   • Extracts the session/token from the request
   • Validates it (checks signature, expiration, revocation)
   • Attaches the user to the request context
   • Returns 401 for invalid/missing credentials
   • Apply to all routes that need protection

7. Implement authorization (if needed):

   • Role-based access control (RBAC) or permission-based
   • Check permissions in route handlers or middleware
   • Return 403 for insufficient permissions

8. Add security hardening:

   • Rate limit auth endpoints (prevent brute force)
   • Lock accounts after repeated failed attempts
   • Log all authentication events
   • Validate password strength on registration
   • Sanitize all inputs

9. Write tests: Cover:

   • Successful registration and login
   • Duplicate email registration
   • Wrong password login
   • Accessing protected routes without auth
   • Token/session expiration
   • Password reset flow

Guidelines

• NEVER store passwords in plain text. NEVER log passwords or tokens.
• NEVER roll your own crypto. Use established libraries.
• Use HTTPS in production. Set the Secure flag on cookies.
• Keep auth logic in a dedicated module, separate from business logic.
• Token secrets and session keys must come from environment variables.
• Validate email format but do not over-restrict it.
• Make error messages generic: “Invalid credentials” not “Password incorrect” or “User not found”.
• Consider account enumeration: registration and login errors should not reveal if an email exists.
• If using OAuth, validate redirect URIs strictly.
• Keep files under 600 lines. Split into auth routes, auth middleware, and auth service.