Add Authentication System Action

Implement a complete, production-ready authentication system with user management, session handling, RBAC authorization, and security hardening tailored to your detected framework.

When to Use This Command

Run this command when...

• You are building a new application that needs user registration, login, and session management from scratch
• You need to add OAuth 2.0, JWT, SAML, or passwordless authentication to an existing project
• You want a complete authentication stack including password hashing, CSRF protection, rate limiting, and secure cookies
• You need role-based access control (RBAC) with route protection and API endpoint authorization
• You are implementing multi-factor authentication (MFA) and need secure token handling and verification flows

Quick Start

Copy
# .claude/commands/add-authentication-system-action.yaml
name: Add Authentication System Action
description: Implement secure authentication with RBAC and session management
inputs:
  - name: method
    description: "Auth method: jwt, oauth, session, passwordless"
    default: "jwt"

Copy
# Add JWT authentication to a Node.js project
claude "add-authentication-system --method jwt"

# Add OAuth with Google and GitHub providers
claude "add-authentication-system --method oauth --providers google,github"

Output:
  [detect] Framework: Express.js (Node.js)
  [setup] Installing dependencies: bcrypt, jsonwebtoken, passport...
  [create] User model with password hashing
  [create] Auth middleware with JWT verification
  [create] Login/Register/Logout endpoints
  [create] RBAC middleware with role definitions
  [harden] Added rate limiting, CSRF, secure cookies
  Done. Authentication system ready. 8 files created.

Core Concepts

Concept	Description
Framework Detection	Auto-detects your tech stack from package.json, requirements.txt, or Cargo.toml to generate appropriate code
User Management	Registration, profile management, password policies, email verification, and account recovery
Session Handling	JWT tokens, refresh tokens, session storage, or cookie-based sessions depending on chosen method
RBAC Authorization	Role definitions, permission matrices, route guards, and API endpoint protection
Security Hardening	OWASP-compliant password hashing, rate limiting, CSRF tokens, secure headers, and input validation

Authentication Architecture:
  Client Request
       │
  ┌────▼────┐    ┌──────────┐    ┌──────────┐
  │  Rate   │───>│   Auth   │───>│   RBAC   │
  │ Limiter │    │Middleware │    │  Guard   │
  └─────────┘    └────┬─────┘    └────┬─────┘
                      │               │
                 ┌────▼─────┐    ┌────▼─────┐
                 │  Token   │    │  Route   │
                 │ Verify   │    │ Handler  │
                 └──────────┘    └──────────┘

Configuration

Parameter	Type	Default	Description
method	string	"jwt"	Authentication method: jwt, oauth, session, passwordless, or saml
providers	string	""	OAuth providers: google, github, facebook (comma-separated)
mfa	boolean	false	Enable multi-factor authentication with TOTP
roles	string	"user,admin"	Comma-separated role names for RBAC setup
database	string	auto-detected	Database for user storage: postgres, mongodb, sqlite

Best Practices

1. Never store passwords in plaintext -- The command uses bcrypt or argon2 by default. Verify the generated code uses a proper hashing algorithm with salt rounds of at least 10.
2. Implement refresh token rotation -- For JWT-based auth, ensure the generated code rotates refresh tokens on every use to prevent token theft from providing permanent access.
3. Set appropriate token expiry -- Access tokens should expire in 15-30 minutes, refresh tokens in 7-30 days. Adjust the generated constants based on your security requirements.
4. Review RBAC permissions after generation -- The default roles (user, admin) are a starting point. Map your actual business roles and permissions before deploying to production.
5. Test authentication flows end-to-end -- After generation, test registration, login, token refresh, password reset, and role-based access with both valid and invalid credentials.

Common Issues

1. Database connection not configured -- The auth system needs a database for user storage. Ensure your database connection is configured in environment variables before running the generated code.
2. Missing environment variables -- JWT secrets, OAuth client IDs, and session keys must be set in .env. The command generates a .env.example with required variables but does not populate actual secrets.
3. CORS blocking OAuth callbacks -- OAuth flows require proper CORS configuration and redirect URIs. Add your callback URLs to both the OAuth provider dashboard and your application's CORS whitelist.