@paons/auth-system v1.0.2

FastAPI-React Authentication Package

A robust, type-safe authentication system for FastAPI backend and React/TypeScript frontend applications.

Features

• User registration with email verification
• JWT-based authentication
• OAuth2 password flow
• TypeScript types for all responses
• Error handling for all edge cases
• Email verification system
• Password reset functionality

Backend Setup

1. Install dependencies:

pip install fastapi[all] sqlalchemy passlib[bcrypt] python-jose[cryptography] python-multipart

2. Copy the backend module:

from auth_system import setup_auth

# In your FastAPI app
app = FastAPI()
auth_router = setup_auth(
    database_url="your_database_url",
    secret_key="your_secret_key",
    email_config={
        "smtp_host": "smtp.gmail.com",
        "smtp_port": 587,
        "smtp_user": "your_email",
        "smtp_password": "your_app_password"
    }
)
app.include_router(auth_router, prefix="/api/v1/auth")

Frontend Setup

1. Install dependencies:

npm install axios @types/axios

2. Import and use the auth client:

import { createAuthClient } from 'auth-system'

const auth = createAuthClient({
    baseUrl: 'http://localhost:8000/api/v1',
    onTokenChange: (token) => {
        // Handle token storage
        localStorage.setItem('token', token)
    }
})

// Use the auth client
await auth.register(email, password, fullName)
await auth.login(email, password)
await auth.verifyEmail(token, email)

Security Features

• Password hashing with bcrypt
• JWT token with configurable expiration
• CSRF protection
• Rate limiting
• Email verification required before login
• Secure password reset flow

Error Handling

All errors are properly typed and handled:

• Network errors
• Validation errors
• Authentication errors
• Server errors

Configuration Options

Backend

• Database configuration
• JWT settings
• Email settings
• Password requirements
• Rate limiting options

Frontend

• Base URL
• Token storage
• Request timeouts
• Custom error handling

Environment Variables

The authentication package requires certain environment variables to be set. Create a .env file in your project root with the following variables:

Email Configuration

# Email Configuration (Gmail SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-app-specific-password
SMTP_FROM_NAME=Your App Name Support

Note: For Gmail, you'll need to use an App Password instead of your regular password. You can generate one in your Google Account settings under Security > 2-Step Verification > App passwords.

Security Settings

SECRET_KEY=your-super-secret-key-replace-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

Frontend Configuration

FRONTEND_URL=http://localhost:3000

Best Practices

1. Always store sensitive information in environment variables
2. Use HTTPS in production
3. Implement rate limiting
4. Set appropriate token expiration times
5. Use secure password requirements
6. Implement proper logging

Common Issues and Solutions

1. CORS issues:

   • Ensure CORS settings match your frontend URL
   • Add all necessary CORS headers

2. Email verification:

   • Test email configuration thoroughly
   • Handle email sending failures gracefully

3. Token handling:

   • Store tokens securely
   • Implement proper token refresh
   • Clear tokens on logout

4. Form data:

   • Use proper content types
   • Handle validation errors correctly

Testing

Includes comprehensive tests for:

• User registration
• Login/logout
• Email verification
• Password reset
• Error cases
• Token handling