Add README.md for Authentication API documentation

- Introduced a comprehensive README.md detailing the features, setup instructions, and API endpoints for the FastAPI-based authentication system with Firebase integration.
- Added project structure overview, environment variable configuration, and security considerations.
- Included examples for user registration, login, and protected routes.
- Updated requirements.txt to include firebase-admin and PyJWT for authentication functionality.
- Created example protected routes in app/example_protected_routes.py to demonstrate role-based access control and user authentication.
- Added test_auth.py as a placeholder for future tests.

Author: arvi18

README.md

@@ -0,0 +1,269 @@
+# Authentication API with Firebase
+
+A FastAPI-based authentication system with Firebase integration, providing user registration, login, and token-based authentication.
+
+## Features
+
+- 🔐 Firebase Authentication integration
+- 📝 User registration and login
+- 🔑 JWT token-based authentication
+- 🔄 Token refresh functionality
+- 🛡️ Role-based access control
+- 📚 Auto-generated API documentation
+- 🌐 CORS support
+
+## Project Structure
+
+```
+├── app/
+│   ├── __init__.py
+│   ├── main.py                 # FastAPI application
+│   └── auth/
+│       ├── __init__.py
+│       ├── models.py           # Pydantic models
+│       ├── firebase_auth.py    # Firebase authentication service
+│       ├── dependencies.py     # Authentication dependencies
+│       └── routes.py           # API routes
+├── run.py                      # Application entry point
+├── requirements.txt            # Python dependencies
+├── env.example                 # Environment variables template
+└── README.md                   # This file
+```
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Firebase Configuration
+
+1. Create a Firebase project at [Firebase Console](https://console.firebase.google.com/)
+2. Enable Authentication in your Firebase project
+3. Create a service account:
+   - Go to Project Settings > Service Accounts
+   - Click "Generate new private key"
+   - Download the JSON file
+
+### 3. Environment Variables
+
+Copy `env.example` to `.env` and configure the variables:
+
+```bash
+cp env.example .env
+```
+
+Required environment variables:
+
+```env
+# Firebase Configuration (choose one option)
+# Option 1: Firebase credentials as JSON string
+FIREBASE_CREDENTIALS={"type":"service_account","project_id":"your-project-id",...}
+
+# Option 2: Path to Firebase service account JSON file
+FIREBASE_SERVICE_ACCOUNT_PATH=./firebase-service-account.json
+
+# JWT Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+
+# Application Configuration
+ENVIRONMENT=development
+DEBUG=true
+LOG_LEVEL=info
+
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+
+# CORS Configuration
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080
+```
+
+### 4. Run the Application
+
+```bash
+python run.py
+```
+
+The API will be available at:
+- API: http://localhost:8000
+- Documentation: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## API Endpoints
+
+### Authentication Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/auth/signup` | Register a new user |
+| POST | `/auth/login` | Login user |
+| POST | `/auth/refresh` | Refresh access token |
+| GET | `/auth/me` | Get current user info |
+| POST | `/auth/logout` | Logout user |
+| GET | `/auth/verify` | Verify token validity |
+
+### Request/Response Examples
+
+#### User Registration
+
+```bash
+POST /auth/signup
+Content-Type: application/json
+
+{
+  "email": "[email protected]",
+  "password": "securepassword123",
+  "first_name": "John",
+  "last_name": "Doe"
+}
+```
+
+Response:
+```json
+{
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+  "token_type": "bearer",
+  "user": {
+    "id": "firebase-user-id",
+    "email": "[email protected]",
+    "first_name": "John",
+    "last_name": "Doe",
+    "is_active": true,
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### User Login
+
+```bash
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "[email protected]",
+  "password": "securepassword123"
+}
+```
+
+#### Token Refresh
+
+```bash
+POST /auth/refresh
+Content-Type: application/json
+
+{
+  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+#### Protected Endpoint Example
+
+```bash
+GET /auth/me
+Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
+```
+
+## Authentication Dependencies
+
+The authentication system provides several dependency functions for protecting routes:
+
+### Basic Authentication
+
+```python
+from app.auth.dependencies import get_current_user
+
+@app.get("/protected")
+async def protected_route(current_user = Depends(get_current_user)):
+    return {"message": f"Hello {current_user['email']}"}
+```
+
+### Active User Check
+
+```python
+from app.auth.dependencies import get_current_active_user
+
+@app.get("/active-only")
+async def active_user_route(current_user = Depends(get_current_active_user)):
+    return {"message": "Active user only"}
+```
+
+### Role-Based Access
+
+```python
+from app.auth.dependencies import require_admin, require_user
+
+@app.get("/admin-only")
+async def admin_route(current_user = Depends(require_admin)):
+    return {"message": "Admin only"}
+
+@app.get("/user-route")
+async def user_route(current_user = Depends(require_user)):
+    return {"message": "User or admin"}
+```
+
+## Error Handling
+
+The API returns appropriate HTTP status codes and error messages:
+
+- `400 Bad Request`: Invalid request data
+- `401 Unauthorized`: Invalid or missing authentication
+- `403 Forbidden`: Insufficient permissions
+- `500 Internal Server Error`: Server-side errors
+
+## Security Considerations
+
+1. **JWT Secret**: Use a strong, unique secret key in production
+2. **Firebase Credentials**: Keep service account credentials secure
+3. **CORS**: Configure allowed origins properly for production
+4. **Password Policy**: Implement strong password requirements
+5. **Rate Limiting**: Consider adding rate limiting for auth endpoints
+6. **HTTPS**: Always use HTTPS in production
+
+## Development
+
+### Running in Development Mode
+
+```bash
+python run.py
+```
+
+The server will run with auto-reload enabled.
+
+### Testing
+
+You can test the API using the interactive documentation at http://localhost:8000/docs
+
+### Environment Variables for Development
+
+For development, you can use the default values in `env.example`. Make sure to:
+
+1. Set up a Firebase project
+2. Configure the Firebase credentials
+3. Generate a secure JWT secret
+
+## Production Deployment
+
+1. Set `ENVIRONMENT=production`
+2. Configure proper CORS origins
+3. Use environment-specific Firebase credentials
+4. Set up proper logging
+5. Use a production WSGI server like Gunicorn
+6. Configure reverse proxy (nginx)
+7. Set up SSL/TLS certificates
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License. 

app/example_protected_routes.py

@@ -0,0 +1,86 @@
+from fastapi import APIRouter, Depends
+from app.auth.dependencies import get_current_user, get_current_active_user, require_admin, require_user
+from typing import Dict, Any
+
+router = APIRouter(prefix="/protected", tags=["protected"])
+
+
+@router.get("/user-info")
+async def get_user_info(current_user: Dict[str, Any] = Depends(get_current_user)):
+    """
+    Get information about the currently authenticated user
+    """
+    return {
+        "message": "User information retrieved successfully",
+        "user": {
+            "id": current_user["uid"],
+            "email": current_user["email"],
+            "first_name": current_user["first_name"],
+            "last_name": current_user["last_name"],
+            "role": current_user["role"]
+        }
+    }
+
+
+@router.get("/active-only")
+async def active_users_only(current_user: Dict[str, Any] = Depends(get_current_active_user)):
+    """
+    Endpoint that only allows active users
+    """
+    return {
+        "message": "This endpoint is only accessible to active users",
+        "user_email": current_user["email"]
+    }
+
+
+@router.get("/admin-only")
+async def admin_only(current_user: Dict[str, Any] = Depends(require_admin)):
+    """
+    Endpoint that only allows admin users
+    """
+    return {
+        "message": "This endpoint is only accessible to admin users",
+        "admin_email": current_user["email"]
+    }
+
+
+@router.get("/user-or-admin")
+async def user_or_admin(current_user: Dict[str, Any] = Depends(require_user)):
+    """
+    Endpoint that allows both regular users and admins
+    """
+    return {
+        "message": "This endpoint is accessible to users and admins",
+        "user_email": current_user["email"],
+        "user_role": current_user["role"]
+    }
+
+
+@router.post("/create-resource")
+async def create_resource(
+    resource_data: dict,
+    current_user: Dict[str, Any] = Depends(get_current_active_user)
+):
+    """
+    Example of creating a resource with user authentication
+    """
+    return {
+        "message": "Resource created successfully",
+        "resource": resource_data,
+        "created_by": current_user["email"],
+        "user_id": current_user["uid"]
+    }
+
+
+@router.delete("/delete-resource/{resource_id}")
+async def delete_resource(
+    resource_id: str,
+    current_user: Dict[str, Any] = Depends(require_admin)
+):
+    """
+    Example of deleting a resource (admin only)
+    """
+    return {
+        "message": f"Resource {resource_id} deleted successfully",
+        "deleted_by": current_user["email"]
+    } 

app/main.py

@@ -2,6 +2,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from .auth.routes import router as auth_router
+from .example_protected_routes import router as protected_router
 import os
 
 # Create FastAPI app
@@ -23,6 +24,9 @@
 # Include authentication routes
 app.include_router(auth_router)
 
+# Include protected routes (examples)
+app.include_router(protected_router)
+
 # Global exception handler
 @app.exception_handler(Exception)
 async def global_exception_handler(request, exc):
@@ -42,5 +46,9 @@ async def root():
     return {
         "message": "Welcome to Authentication API",
         "docs": "/docs",
-        "redoc": "/redoc"
+        "redoc": "/redoc",
+        "endpoints": {
+            "auth": "/auth",
+            "protected": "/protected"
+        }
     }