django-cfg 1.4.46__py3-none-any.whl → 1.5.181__py3-none-any.whl

django_cfg/management/utils/postgresql.py

@@ -0,0 +1,228 @@
+"""
+PostgreSQL Extension Management Utilities
+
+Provides utilities for managing PostgreSQL extensions during migrations,
+including automatic detection and installation of required extensions like pgvector.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from django.apps import apps
+from django.db import connections
+
+
+class PostgreSQLExtensionManager:
+    """
+    Manager for PostgreSQL extensions with automatic detection and installation.
+    
+    Handles:
+    - Detection of required extensions by scanning migrations
+    - Installation of extensions (pgvector, pg_trgm, etc.)
+    - Helpful error messages when extensions are not available
+    
+    Usage:
+        manager = PostgreSQLExtensionManager(stdout, style, logger)
+        manager.ensure_extensions(db_name='default')
+    """
+    
+    def __init__(self, stdout=None, style=None, logger=None):
+        """
+        Initialize extension manager.
+        
+        Args:
+            stdout: Django command stdout for output
+            style: Django command style for colored output
+            logger: Logger instance for logging
+        """
+        self.stdout = stdout
+        self.style = style
+        self.logger = logger
+    
+    def ensure_extensions(self, db_name: str):
+        """
+        Ensure required PostgreSQL extensions are installed.
+        
+        Automatically detects database type from Django connection settings.
+        Works with any Django configuration (django-cfg, settings.py, etc.)
+        as connection.settings_dict contains the full database configuration
+        from settings.DATABASES[db_name].
+        
+        Args:
+            db_name: Database alias name
+            
+        Raises:
+            SystemExit: If required extension is not available
+        """
+        try:
+            # Get database connection and engine type from Django settings
+            # This works because Django has already processed the configuration
+            # (whether from django-cfg or settings.py) into connections
+            connection = connections[db_name]
+            db_engine = connection.settings_dict.get("ENGINE", "")
+            
+            # Only process PostgreSQL databases
+            if "postgresql" not in db_engine.lower():
+                return
+            
+            self._log_info(f"🔌 Checking PostgreSQL extensions for {db_name}...")
+            
+            # Check if we need pgvector by inspecting migrations
+            needs_pgvector = self.check_if_pgvector_needed()
+            
+            if not needs_pgvector:
+                self._log_info("✓ No vector extensions needed")
+                return
+            
+            # Install pgvector extension
+            self._install_pgvector(connection)
+            
+        except Exception as e:
+            if "postgresql" in str(e).lower() or "vector" in str(e).lower():
+                self._raise_error(f"Failed to setup PostgreSQL extensions: {e}")
+            # Silently ignore errors for non-PostgreSQL databases
+    
+    def _install_pgvector(self, connection):
+        """Install pgvector extension on PostgreSQL database."""
+        try:
+            with connection.cursor() as cursor:
+                cursor.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+                self._log_success("✅ pgvector extension enabled")
+        except Exception as e:
+            # Try to provide helpful error message
+            error_msg = str(e)
+            if "does not exist" in error_msg.lower():
+                pg_version = self._get_pg_version(connection)
+                self._log_warning(
+                    f"⚠️  pgvector extension not available. "
+                    f"Install it with: apt-get install postgresql-{pg_version}-pgvector"
+                )
+                self._raise_error(f"pgvector extension required but not installed: {e}")
+            else:
+                raise
+    
+    def check_if_pgvector_needed(self) -> bool:
+        """
+        Check if any migrations require pgvector by scanning for vector field usage.
+        
+        Returns:
+            True if pgvector is needed, False otherwise
+        """
+        try:
+            # Check if pgvector is imported anywhere in the project
+            for app_config in apps.get_app_configs():
+                migrations_dir = Path(app_config.path) / "migrations"
+                if not migrations_dir.exists():
+                    continue
+                
+                # Scan migration files for pgvector usage
+                for migration_file in migrations_dir.glob("*.py"):
+                    if migration_file.name == "__init__.py":
+                        continue
+                    
+                    try:
+                        content = migration_file.read_text()
+                        if self._has_vector_field(content):
+                            return True
+                    except Exception:
+                        continue
+            
+            return False
+        except Exception:
+            # If we can't check, assume it's not needed
+            return False
+    
+    def _has_vector_field(self, content: str) -> bool:
+        """
+        Check if migration content contains vector field references.
+        
+        Args:
+            content: Migration file content
+            
+        Returns:
+            True if vector fields are found
+        """
+        indicators = [
+            "pgvector",
+            "VectorField",
+            "vector(",
+            "vector.VectorField",
+        ]
+        
+        content_lower = content.lower()
+        return any(indicator.lower() in content_lower for indicator in indicators)
+    
+    def _get_pg_version(self, connection) -> str:
+        """
+        Get PostgreSQL major version number.
+        
+        Args:
+            connection: Django database connection
+            
+        Returns:
+            Major version string (e.g., "15")
+        """
+        try:
+            with connection.cursor() as cursor:
+                cursor.execute("SHOW server_version;")
+                version = cursor.fetchone()[0]
+                # Extract major version (e.g., "15.3" -> "15")
+                major_version = version.split(".")[0]
+                return major_version
+        except Exception:
+            return "15"  # Default fallback
+    
+    def _log_info(self, message: str):
+        """Log info message."""
+        if self.stdout:
+            self.stdout.write(f"  {message}")
+        if self.logger:
+            self.logger.info(message)
+    
+    def _log_success(self, message: str):
+        """Log success message."""
+        if self.stdout and self.style:
+            self.stdout.write(self.style.SUCCESS(f"  {message}"))
+        elif self.stdout:
+            self.stdout.write(f"  {message}")
+        if self.logger:
+            self.logger.info(message)
+    
+    def _log_warning(self, message: str):
+        """Log warning message."""
+        if self.stdout and self.style:
+            self.stdout.write(self.style.WARNING(f"  {message}"))
+        elif self.stdout:
+            self.stdout.write(f"  {message}")
+        if self.logger:
+            self.logger.warning(message)
+    
+    def _raise_error(self, message: str):
+        """Raise error with logging."""
+        if self.stdout and self.style:
+            self.stdout.write(self.style.ERROR(f"❌ {message}"))
+        elif self.stdout:
+            self.stdout.write(f"❌ {message}")
+        if self.logger:
+            self.logger.error(message)
+        raise SystemExit(1)
+
+
+def ensure_postgresql_extensions(db_name: str, stdout=None, style=None, logger=None):
+    """
+    Convenience function to ensure PostgreSQL extensions are installed.
+    
+    Args:
+        db_name: Database alias name
+        stdout: Django command stdout for output
+        style: Django command style for colored output
+        logger: Logger instance for logging
+        
+    Example:
+        from django_cfg.management.utils.postgresql import ensure_postgresql_extensions
+        
+        ensure_postgresql_extensions('default', self.stdout, self.style, self.logger)
+    """
+    manager = PostgreSQLExtensionManager(stdout, style, logger)
+    manager.ensure_extensions(db_name)
+

django_cfg/middleware/README.md

@@ -5,6 +5,19 @@ Custom Django middleware components for Django CFG applications.
 ## 📋 Contents
 
 - [UserActivityMiddleware](#useractivitymiddleware) - User activity tracking
+- [Admin Login Notifications](#admin-login-notifications) - Real-time Telegram alerts for admin access
+
+## JWT Token Injection for Next.js Apps
+
+**Note:** JWT token injection is now handled by `NextJSStaticView` in `apps/frontend/views.py`, not by middleware.
+
+This provides better security by limiting JWT injection scope to Next.js applications only.
+
+### 📖 Full Documentation
+
+See [`/apps/frontend/JWT_AUTO_INJECTION.md`](../apps/frontend/JWT_AUTO_INJECTION.md) for complete JWT injection documentation.
+
+---
 
 ## UserActivityMiddleware
 
@@ -158,3 +171,362 @@ class MyProjectConfig(DjangoConfig):
 # GET /api/users/?format=json
 # PUT /cfg/newsletter/subscribe/
 ```
+
+---
+
+## Admin Login Notifications
+
+Real-time Telegram notifications for admin panel access monitoring. Automatically sends alerts for successful logins, failed attempts, and account lockouts.
+
+### ✨ Features
+
+- ✅ **Successful admin logins** - Info notifications with user details
+- ✅ **Failed login attempts** - Warning notifications (django-axes integration)
+- ✅ **Account lockouts** - Error alerts for brute-force protection
+- ✅ **Real IP detection** - Cloudflare/nginx/traefik support
+- ✅ **Role identification** - Superuser vs staff differentiation
+- ✅ **Zero configuration** - Works automatically when Telegram is configured
+
+### 🚀 Automatic Integration
+
+Admin login notifications activate automatically when Telegram is configured:
+
+```python
+# config.py
+class MyConfig(DjangoConfig):
+    # Configure Telegram
+    telegram: TelegramConfig = TelegramConfig(
+        bot_token="your-bot-token",
+        chat_id=123456789,
+    )
+
+    # That's it! Admin login notifications are now active
+```
+
+### 📱 Notification Types
+
+#### 1. Successful Login (Info)
+
+**Superuser login:**
+```
+👑 Admin Login (Superuser)
+
+user: admin@example.com
+username: admin
+role: Superuser
+is_superuser: true
+login_time: 2025-10-21 15:30:45 UTC
+ip_address: 192.168.1.100
+user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
+user_id: 1
+```
+
+**Staff login:**
+```
+🔐 Admin Login (Staff)
+
+user: staff@example.com
+username: staff_user
+role: Staff
+is_superuser: false
+login_time: 2025-10-21 15:32:10 UTC
+ip_address: 192.168.1.101
+user_agent: Mozilla/5.0...
+user_id: 5
+```
+
+#### 2. Failed Login Attempt (Warning)
+
+```
+⚠️ Failed Admin Login Attempt
+
+username: admin
+ip_address: 203.0.113.45
+time: 2025-10-21 15:35:22 UTC
+user_agent: Mozilla/5.0...
+path: /admin/login/
+```
+
+#### 3. Account Lockout (Error)
+
+```
+🚨 Admin Account LOCKED OUT
+
+username: admin
+ip_address: 203.0.113.45
+time: 2025-10-21 15:36:10 UTC
+reason: Too many failed login attempts
+action_required: Manual unlock required in admin panel or via axes_reset command
+```
+
+### 🔧 How It Works
+
+The module uses **Django signals** (not traditional middleware):
+
+1. **`user_logged_in` signal** - Catches all successful logins
+   - Filters for `/admin/` paths only
+   - Checks `is_staff` or `is_superuser` permissions
+   - Sends Telegram info notification
+
+2. **`user_login_failed` signal** - Catches failed attempts (django-axes)
+   - Only for admin panel paths
+   - Sends warning notification
+
+3. **`user_locked_out` signal** - Catches lockouts (django-axes)
+   - Critical security alert
+   - Sends error notification
+
+### 🌐 Proxy Support
+
+Automatically extracts real client IP through proxies:
+
+**Header precedence** (matches AxesConfig):
+1. `HTTP_CF_CONNECTING_IP` - Cloudflare real IP
+2. `HTTP_X_FORWARDED_FOR` - Nginx/Traefik proxy
+3. `HTTP_X_REAL_IP` - Alternative proxy header
+4. `REMOTE_ADDR` - Direct connection
+
+**Example with Cloudflare:**
+```
+Client (203.0.113.45) → Cloudflare → nginx → Django
+
+Headers received:
+- HTTP_CF_CONNECTING_IP: 203.0.113.45  ← Real client IP
+- HTTP_X_FORWARDED_FOR: 203.0.113.45, 104.21.1.1
+- REMOTE_ADDR: 172.18.0.1
+
+Detected IP: 203.0.113.45 ✅
+```
+
+### 🔒 Security Benefits
+
+1. **Immediate attack detection** - Real-time alerts for suspicious activity
+2. **Brute-force monitoring** - Track failed login patterns
+3. **Lockout notifications** - Know when accounts are locked
+4. **IP tracking** - Identify attack sources
+5. **Role awareness** - Monitor superuser vs staff access
+
+### 📊 Integration with Django-Axes
+
+Works seamlessly with django-axes brute-force protection:
+
+```python
+# config.py
+class MyConfig(DjangoConfig):
+    # Django-Axes configuration
+    axes: AxesConfig = AxesConfig(
+        failure_limit=5,      # 5 failed attempts
+        cooloff_time=24,      # 24 hour lockout
+    )
+
+    # Telegram configuration
+    telegram: TelegramConfig = TelegramConfig(
+        bot_token="your-token",
+        chat_id=123456789,
+    )
+
+    # Notifications work automatically:
+    # 1. Failed attempt → Telegram warning
+    # 2. 5th failed attempt → Account locked
+    # 3. Lockout → Telegram error alert
+```
+
+### 🎯 Admin Panel Only
+
+Notifications are **only sent for admin panel access**:
+
+✅ **Monitored paths:**
+- `/admin/login/`
+- `/admin/`
+- `/admin/accounts/customuser/`
+- Any path starting with `/admin/`
+
+❌ **Not monitored:**
+- `/api/auth/login/` - API login
+- `/cfg/accounts/otp/` - OTP login
+- Regular user logins
+
+### 🔕 Disabling Notifications
+
+To disable admin login notifications:
+
+```python
+# Option 1: Disable Telegram entirely
+telegram: Optional[TelegramConfig] = None
+
+# Option 2: Set bot_token to empty
+telegram: TelegramConfig = TelegramConfig(
+    bot_token="",  # Notifications disabled
+    chat_id=0,
+)
+```
+
+### 🧪 Testing
+
+Test admin login notifications:
+
+```bash
+# 1. Test successful login
+# - Login to admin panel at /admin/
+# - Check Telegram for "🔐 Admin Login" or "👑 Admin Login (Superuser)"
+
+# 2. Test failed login
+# - Try wrong password at /admin/login/
+# - Check Telegram for "⚠️ Failed Admin Login Attempt"
+
+# 3. Test lockout
+# - Fail login 5 times (default AXES_FAILURE_LIMIT)
+# - Check Telegram for "🚨 Admin Account LOCKED OUT"
+
+# 4. Test unlock
+python manage.py axes_reset username admin
+# Login again - should get success notification
+```
+
+### 📝 Logging
+
+All notifications are logged:
+
+```python
+# settings.py or configure logging
+LOGGING = {
+    'loggers': {
+        'django_cfg.middleware.admin_notifications': {
+            'level': 'INFO',
+            'handlers': ['console'],
+        },
+    },
+}
+```
+
+**Log output:**
+```
+INFO Admin login notification sent for admin@example.com from 192.168.1.100
+WARNING Failed admin login attempt: admin from 203.0.113.45
+ERROR Admin account locked out: admin from 203.0.113.45
+```
+
+### 🚨 Important Notes
+
+1. **Requires Telegram** - Only works when TelegramConfig is configured
+2. **Django-Axes optional** - Failed login/lockout notifications require django-axes
+3. **Signal-based** - Not a traditional middleware class, uses Django signals
+4. **Auto-registers** - Signals register automatically on import
+5. **Fail-safe** - Notification errors don't break login flow
+
+### 💡 Usage Examples
+
+**Example 1: Basic setup**
+```python
+# config.py
+class MyConfig(DjangoConfig):
+    telegram: TelegramConfig = TelegramConfig(
+        bot_token=env.telegram.bot_token,
+        chat_id=env.telegram.chat_id,
+    )
+
+# Done! Admin logins now send Telegram notifications
+```
+
+**Example 2: With django-axes**
+```python
+# config.py
+class MyConfig(DjangoConfig):
+    # Brute-force protection
+    axes: AxesConfig = AxesConfig(
+        failure_limit=3,
+        cooloff_time=48,
+    )
+
+    # Telegram notifications
+    telegram: TelegramConfig = TelegramConfig(
+        bot_token=env.telegram.bot_token,
+        chat_id=env.telegram.chat_id,
+    )
+
+# Get notifications for:
+# ✅ Successful logins
+# ✅ Failed attempts
+# ✅ Lockouts
+```
+
+**Example 3: Production monitoring**
+```python
+# config.py
+class ProdConfig(DjangoConfig):
+    debug: bool = False
+    security_domains: list = ["myapp.com"]
+
+    # Strict brute-force protection
+    axes: AxesConfig = AxesConfig(
+        failure_limit=3,      # Only 3 attempts
+        cooloff_time=72,      # 72 hour lockout
+        allowed_ips=[         # Whitelist office IPs
+            '192.168.1.0/24',
+        ],
+    )
+
+    # Telegram security monitoring
+    telegram: TelegramConfig = TelegramConfig(
+        bot_token=env.telegram.bot_token,
+        chat_id=env.telegram.security_chat_id,  # Dedicated security channel
+    )
+
+# Production security monitoring:
+# 🔐 Know who accesses admin panel
+# ⚠️ Track suspicious login attempts
+# 🚨 Get immediate lockout alerts
+```
+
+### 🔍 Troubleshooting
+
+**Problem: No notifications sent**
+
+1. Check Telegram configuration:
+```python
+from django_cfg.modules.django_telegram import DjangoTelegram
+
+telegram = DjangoTelegram()
+print(telegram.is_configured)  # Should be True
+print(telegram.get_config_info())
+```
+
+2. Test Telegram manually:
+```python
+from django_cfg.modules.django_telegram import DjangoTelegram
+
+DjangoTelegram.send_info("Test", {"message": "Testing admin notifications"})
+```
+
+3. Check logs:
+```bash
+# Enable DEBUG logging
+tail -f logs/django.log | grep admin_notifications
+```
+
+**Problem: Wrong IP address**
+
+Configure proxy settings:
+```python
+# config.py
+axes: AxesConfig = AxesConfig(
+    ipware_proxy_count=1,  # Adjust based on proxy layers
+    ipware_meta_precedence_order=[
+        'HTTP_CF_CONNECTING_IP',  # Add your proxy header
+        'HTTP_X_FORWARDED_FOR',
+        'REMOTE_ADDR',
+    ],
+)
+```
+
+**Problem: Too many notifications**
+
+Notifications are sent once per login. If you're getting duplicates:
+- Check for multiple middleware/signal registrations
+- Verify django-axes is not sending duplicate signals
+
+### 📚 See Also
+
+- [Django-Axes Configuration](../fundamentals/configuration/security.md#django-axes-brute-force-protection)
+- [Telegram Module](../modules/django_telegram)
+- [Security Settings](../fundamentals/configuration/security.md)

django_cfg/middleware/__init__.py

@@ -6,6 +6,12 @@ Provides middleware components for Django CFG applications.
 
 from .user_activity import UserActivityMiddleware
 
+# Import admin_notifications to register signal handlers
+# This module contains Django signal receivers for admin login monitoring
+# No middleware class needed - signals auto-register on import
+from . import admin_notifications  # noqa: F401
+
 __all__ = [
     'UserActivityMiddleware',
+    'admin_notifications',
 ]