AUTHENTICATION.md

SanadCheck LLM API - Authentication & Database Implementation

This document outlines the JWT authentication, rate limiting, and database storage features that have been implemented for the SanadCheck LLM API.

Features Implemented

🔐 JWT Authentication with Supabase

• User registration and login using Supabase Auth
• JWT token generation and validation
• Session management with token refresh
• Role-based access control (User, Admin, Researcher)
• Token blacklisting for logout functionality

🚀 Rate Limiting

• Redis-based rate limiting with SlowAPI
• Different limits for authenticated vs anonymous users
• IP-based and user-based rate limiting
• Burst protection and graceful degradation

📊 Database Storage

• All narrator extractions and analyses are stored in Supabase
• User analytics and usage tracking
• Performance metrics and success rates
• Popular narrators tracking

🔒 Protected Routes

• All API endpoints now require JWT authentication
• Rate limiting applied to all endpoints
• IP tracking for security and analytics

Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Supabase Setup

1. Create a new Supabase project at supabase.com
2. Copy your project URL and service role key
3. Run the SQL scripts in the sql/ directory in your Supabase SQL Editor:
   • First: sql/create_tables.sql
   • Then: sql/sample_data.sql

3. Redis Setup (Optional)

For production, install and configure Redis:

# On Ubuntu/Debian
sudo apt update
sudo apt install redis-server

# On Fedora
sudo dnf install redis

# Start Redis
sudo systemctl start redis
sudo systemctl enable redis

For development, the API will work with in-memory rate limiting if Redis is not available.

4. Environment Configuration

Copy .env.example to .env and update with your values:

cp .env.example .env

Required environment variables:

• SUPABASE_URL: Your Supabase project URL
• SUPABASE_SERVICE_KEY: Your Supabase service role key
• JWT_SECRET_KEY: A secure secret key for JWT signing
• REDIS_URL: Redis connection URL (optional)

5. Run the Application

# Development
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000

API Usage

Authentication Flow

1. Register a new user:

curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword",
    "username": "username",
    "full_name": "Full Name"
  }'

2. Login:

curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

3. Use the access token for API calls:

curl -X POST "http://localhost:8000/api/v1/extract-narrators" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "hadith_text": "حدثنا محمد بن إسماعيل..."
  }'

Available Endpoints

Authentication

• POST /auth/register - Register new user
• POST /auth/login - Login user
• POST /auth/refresh - Refresh access token
• POST /auth/logout - Logout user
• GET /auth/me - Get current user info
• GET /auth/sessions - Get user sessions

Hadith Analysis (Protected)

• POST /api/v1/extract-narrators - Extract narrators from hadith
• POST /api/v1/analyze-narrator - Analyze single narrator
• POST /api/v1/analyze-narrator-chain - Analyze narrator chain
• POST /api/v1/extract-and-analyze - Complete analysis workflow

Analytics (Mixed Access)

• GET /api/v1/user/extractions - Get user's extraction history (Protected)
• GET /api/v1/user/analyses - Get user's analysis history (Protected)
• GET /api/v1/analytics/stats - Get platform statistics (Public)
• GET /api/v1/analytics/popular-narrators - Get popular narrators (Public)

Utility

• GET /api/v1/health - Health check (Public)

Database Schema

Tables Created

1. users - Extended user profiles linked to Supabase auth
2. user_sessions - JWT session tracking
3. narrator_extractions - Records of narrator extraction requests
4. narrator_analyses - Records of narrator analysis requests

Security Features

• Row Level Security (RLS) enabled on all tables
• Users can only access their own data
• Service role has full access for admin operations
• Automatic user profile creation on signup

Analytics and Monitoring

User Analytics

• Track extraction and analysis usage per user
• Monitor success rates and processing times
• Popular narrator trends
• User activity patterns

Platform Statistics

• Overall success rates
• Average processing times
• Most analyzed narrators
• User growth metrics

Security Considerations

JWT Security

• Tokens have expiration times
• Refresh tokens for long-term access
• Token blacklisting on logout
• Secure secret key required

Database Security

• Row Level Security (RLS) enforced
• User data isolation
• SQL injection protection
• Parameterized queries

Rate Limiting

• Prevents abuse and DoS attacks
• IP-based and user-based tracking
• Graceful degradation when limits exceeded

Data Collection for NLP

All user interactions are stored for machine learning purposes:

Extraction Data

• Original hadith texts
• Extracted narrator names
• Extraction success/failure rates
• Processing times
• User feedback (future feature)

Analysis Data

• Narrator names analyzed
• Reliability grades assigned
• Confidence levels
• User preferences and patterns

This data can be used to:

• Improve narrator extraction accuracy
• Train better reliability assessment models
• Understand user behavior patterns
• Optimize processing performance

Development Notes

Code Structure

app/
├── auth/                 # Authentication routes
├── middleware/           # JWT auth and rate limiting
├── services/            # Database and business logic
├── api/                 # Protected API routes
├── db/                  # Data models
└── config/              # Settings and configuration

sql/                     # Database schema and setup
├── create_tables.sql    # Main schema
└── sample_data.sql      # Functions and sample data

Key Components

• AuthMiddleware: JWT token handling and validation
• RateLimitMiddleware: Redis-based rate limiting
• DatabaseService: Supabase database operations
• Protected Routes: All endpoints require authentication

Future Enhancements

1. User Feedback System: Allow users to rate extraction/analysis quality
2. Advanced Analytics: Machine learning insights from user data
3. Bulk Operations: Support for batch processing
4. API Versioning: Maintain backward compatibility
5. Caching Layer: Redis caching for frequent narrator lookups
6. Audit Logging: Detailed security and usage logs

Troubleshooting

Common Issues

1. Supabase Connection Failed

   • Check SUPABASE_URL and SUPABASE_SERVICE_KEY in .env
   • Verify Supabase project is active
   • Ensure SQL scripts were executed

2. Redis Connection Failed

   • Rate limiting will use in-memory storage
   • Install and start Redis service
   • Check REDIS_URL in .env

3. JWT Token Invalid

   • Check JWT_SECRET_KEY in .env
   • Verify token hasn't expired
   • Ensure token isn't blacklisted

4. Rate Limit Exceeded

   • Wait for rate limit window to reset
   • Use authenticated requests for higher limits
   • Contact admin for limit increases

Logs and Debugging

• Set DEBUG=True in .env for detailed error messages
• Check application logs for authentication errors
• Monitor Supabase logs for database issues
• Use /health endpoint to verify service status