implemented auth

AUTHENTICATION.md

@@ -0,0 +1,201 @@
+# 🔐 Authentication Guide
+
+This guide explains how to use the authentication system in the Student Success Predictor application.
+
+## 🚀 Quick Start
+
+### Default Credentials
+
+The application comes with two pre-configured demo accounts:
+
+**Administrator Account:**
+- Username: `admin`
+- Password: `admin123`
+- Role: Admin (full access + user management)
+
+**Educator Account:**
+- Username: `educator` 
+- Password: `hello123`
+- Role: Educator (prediction access + export features)
+
+### First Login
+
+1. Run the application: `streamlit run app.py`
+2. You'll see the login screen with demo credentials displayed
+3. Use either account above to log in
+4. **Important:** Change default passwords in production!
+
+## 👥 User Roles & Permissions
+
+### 🏷️ Role Hierarchy
+
+1. **Admin** - Full access to everything
+   - Use prediction features
+   - Export prediction reports
+   - Manage users (add/delete)
+   - Access admin panel
+
+2. **Educator** - Educational staff access
+   - Use prediction features
+   - Export prediction reports
+   - Cannot manage users
+
+3. **User** - Basic access (for future use)
+   - Use prediction features only
+   - No export capabilities
+   - No admin functions
+
+## 🛠️ User Management (Admin Only)
+
+### Adding New Users
+
+1. Login as admin
+2. In the sidebar, expand "👨‍💼 Admin Panel"
+3. Fill out the "Add New User" form:
+   - Username (unique identifier)
+   - Password (secure password)
+   - Full Name (display name)
+   - Role (user/educator/admin)
+4. Click "➕ Add User"
+
+### Managing Existing Users
+
+- View all users in the "Existing Users" section
+- Delete users with the 🗑️ button (except yourself)
+- Users are stored in `users.json` file
+
+## 🔒 Security Features
+
+### Password Hashing
+- All passwords are hashed using SHA-256
+- Plain text passwords are never stored
+- Secure credential verification
+
+### Session Management
+- Automatic session timeout (30 minutes of inactivity)
+- Secure session state management
+- Proper logout functionality
+
+### Role-Based Access Control
+- Different features available based on user role
+- Hierarchical permission system
+- Secure admin-only functions
+
+## 📁 Data Storage
+
+### User Data File
+- Users stored in: `users.json`
+- Contains hashed passwords only
+- Includes user roles and names
+- Automatically created on first run
+
+### Session Storage
+- Uses Streamlit's built-in session state
+- No persistent session storage
+- Secure temporary authentication
+
+## 🔧 Customization
+
+### Adding New Roles
+
+Edit `src/utils/auth.py` and modify:
+
+```python
+role_hierarchy = {
+    "admin": 3,
+    "educator": 2,
+    "student": 1,  # Add new role here
+    "user": 0
+}
+```
+
+### Changing Session Timeout
+
+In `app.py`, modify the timeout value:
+
+```python
+check_session_timeout(60)  # 60 minutes instead of 30
+```
+
+### Custom Password Requirements
+
+Add validation in `src/utils/auth.py`:
+
+```python
+def validate_password(password: str) -> bool:
+    # Add your password requirements here
+    return len(password) >= 8 and any(c.isdigit() for c in password)
+```
+
+## 🚨 Production Security
+
+### Important Security Steps for Production:
+
+1. **Change Default Passwords**
+   ```python
+   # Delete users.json and create new admin account
+   ```
+
+2. **Use Environment Variables**
+   ```python
+   import os
+   ADMIN_PASSWORD = os.getenv('ADMIN_PASSWORD', 'secure_password')
+   ```
+
+3. **Implement Database Storage**
+   - Replace JSON file with proper database
+   - Use encrypted connection strings
+   - Implement proper backup procedures
+
+4. **Add Password Complexity Requirements**
+   - Minimum length requirements
+   - Special character requirements
+   - Password expiration policies
+
+5. **Implement Rate Limiting**
+   - Prevent brute force attacks
+   - Temporary account lockouts
+   - Login attempt logging
+
+6. **Enable HTTPS**
+   - Secure data transmission
+   - SSL/TLS certificates
+   - Secure cookie settings
+
+## 🐛 Troubleshooting
+
+### Login Issues
+
+**Problem:** "Invalid username or password"
+- **Solution:** Check credentials carefully, case-sensitive
+
+**Problem:** Session expired message
+- **Solution:** Normal after 30 minutes, just log in again
+
+**Problem:** Cannot access admin features
+- **Solution:** Ensure you're logged in with admin role
+
+### File Permission Issues
+
+**Problem:** Cannot create users.json
+- **Solution:** Check write permissions in app directory
+
+**Problem:** Cannot save new users
+- **Solution:** Ensure sufficient disk space and permissions
+
+## 📝 Development Notes
+
+### File Structure
+```
+src/utils/auth.py          # Main authentication module
+users.json                 # User credentials storage (auto-created)
+app.py                     # Main app with auth integration
+```
+
+### Key Functions
+- `require_auth()` - Decorator for protected functions
+- `check_role_permission()` - Role-based access control
+- `render_admin_panel()` - User management interface
+- `check_session_timeout()` - Session timeout handling
+
+This authentication system provides a secure, user-friendly way to control access to your Student Success Predictor application!