agri-secure-framework 2.0.0__py3-none-any.whl

agri_secure/__init__.py

@@ -0,0 +1,857 @@
+"""
+agri_secure - Production-ready cybersecurity framework for agricultural data systems
+===============================================================================
+
+A comprehensive framework that provides:
+    - Military-grade encryption (AES-256)
+    - Multi-factor authentication
+    - Role-based access control
+    - Blockchain-inspired audit trails
+    - Cloud-native architecture
+    - Database agnostic (PostgreSQL, MySQL, MongoDB, etc.)
+    - Web framework adapters (Django, Flask, FastAPI)
+
+Basic Usage:
+    >>> from agri_secure import AgriculturalSecurity
+    >>> 
+    >>> # Initialize the framework
+    >>> security = AgriculturalSecurity(
+    ...     app_name="my_farm_app",
+    ...     environment="production",
+    ...     encryption_key=os.getenv("ENCRYPTION_KEY")
+    ... )
+    >>> 
+    >>> # Secure data sharing
+    >>> result = security.share_data(
+    ...     data={"farmer": "John", "yield": 500},
+    ...     recipient="ministry",
+    ...     user_role="extension_officer"
+    ... )
+"""
+
+import logging
+import os
+import sys
+from typing import Dict, Any, Optional, Union, List
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# Version
+__version__ = "2.0.0"
+__author__ = "Zambia Agricultural Cybersecurity Initiative"
+__license__ = "MIT"
+
+# Configure root logger
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout),
+        logging.FileHandler('agri_secure.log')
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+# Import core components
+from .core.encryption import AgriculturalEncryption
+from .core.authentication import AgriculturalAuthenticator
+from .core.access_control import AgriculturalAccessControl
+from .blockchain.ledger import AgriculturalLedger
+from .models.schemas import (
+    UserBase, UserCreate, UserInDB, UserResponse,
+    FarmBase, FarmCreate, FarmInDB, FarmResponse,
+    DataClassification, UserRole
+)
+from .exceptions import (
+    AgriSecureError, AuthenticationError, AuthorizationError,
+    EncryptionError, ValidationError, BlockchainError
+)
+from .utils.validators import DataValidator
+from .utils.helpers import generate_id, hash_password, verify_password
+
+class AgriculturalSecurity:
+    """
+    Main framework class - production-ready agricultural security system.
+    
+    This class integrates all security components into a unified interface.
+    Designed for high performance, scalability, and ease of use.
+    """
+    
+    def __init__(
+        self,
+        app_name: str,
+        environment: str = "development",
+        encryption_key: Optional[str] = None,
+        jwt_secret: Optional[str] = None,
+        database_url: Optional[str] = None,
+        redis_url: Optional[str] = None,
+        mfa_required: bool = True,
+        blockchain_enabled: bool = True,
+        log_level: str = "INFO",
+        metrics_enabled: bool = True,
+        tracing_enabled: bool = False,
+        cache_ttl: int = 3600,
+        max_failed_attempts: int = 5,
+        session_timeout: int = 28800,  # 8 hours
+        token_expiry: int = 3600,       # 1 hour
+        backup_enabled: bool = True,
+        auto_migrate: bool = False
+    ):
+        """
+        Initialize the agricultural security framework.
+        
+        Args:
+            app_name: Name of your application
+            environment: development/staging/production
+            encryption_key: Master encryption key (from environment)
+            jwt_secret: Secret for JWT tokens
+            database_url: Database connection string
+            redis_url: Redis URL for caching/sessions
+            mfa_required: Require multi-factor authentication
+            blockchain_enabled: Enable blockchain audit trail
+            log_level: Logging level
+            metrics_enabled: Enable Prometheus metrics
+            tracing_enabled: Enable OpenTelemetry tracing
+            cache_ttl: Cache TTL in seconds
+            max_failed_attempts: Max failed login attempts before lockout
+            session_timeout: Session timeout in seconds
+            token_expiry: JWT token expiry in seconds
+            backup_enabled: Enable automatic backups
+            auto_migrate: Auto-run database migrations
+        """
+        self.app_name = app_name
+        self.environment = environment
+        self.start_time = datetime.utcnow()
+        
+        # Configure logging
+        self._configure_logging(log_level)
+        self.logger = logging.getLogger(f"agri_secure.{app_name}")
+        self.logger.info(f"Initializing Agricultural Security Framework v{__version__}")
+        self.logger.info(f"Environment: {environment}")
+        
+        # Validate production requirements
+        if environment == "production":
+            self._validate_production_config(
+                encryption_key, jwt_secret, database_url
+            )
+        
+        # Initialize components
+        try:
+            # Core security
+            self.encryption = AgriculturalEncryption(
+                master_key=encryption_key,
+                key_rotation_days=90,
+                algorithm="AES-256-GCM"
+            )
+            self.logger.debug("Encryption module initialized")
+            
+            self.auth = AgriculturalAuthenticator(
+                secret_key=jwt_secret,
+                mfa_required=mfa_required,
+                token_expiry=token_expiry,
+                max_failed_attempts=max_failed_attempts,
+                redis_url=redis_url,
+                session_timeout=session_timeout
+            )
+            self.logger.debug("Authentication module initialized")
+            
+            self.access = AgriculturalAccessControl(
+                cache_ttl=cache_ttl,
+                redis_url=redis_url
+            )
+            self.logger.debug("Access control module initialized")
+            
+            # Blockchain ledger
+            if blockchain_enabled:
+                self.ledger = AgriculturalLedger(
+                    database_url=database_url,
+                    consensus="raft",
+                    backup_enabled=backup_enabled
+                )
+                self.logger.debug("Blockchain ledger initialized")
+            else:
+                self.ledger = None
+                self.logger.warning("Blockchain ledger disabled")
+            
+            # Database connection
+            if database_url:
+                self._init_database(database_url, auto_migrate)
+            
+            # Cache connection
+            if redis_url:
+                self._init_cache(redis_url)
+            
+            # Metrics and tracing
+            if metrics_enabled:
+                self._init_metrics()
+            
+            if tracing_enabled:
+                self._init_tracing()
+            
+            self.logger.info("Framework initialization complete")
+            
+        except Exception as e:
+            self.logger.error(f"Failed to initialize framework: {e}")
+            raise AgriSecureError(f"Initialization failed: {e}")
+    
+    def _configure_logging(self, level: str):
+        """Configure structured logging for cloud environments"""
+        log_level = getattr(logging, level.upper(), logging.INFO)
+        
+        # Use JSON logging in production for better cloud integration
+        if self.environment == "production":
+            from pythonjsonlogger import jsonlogger
+            
+            log_handler = logging.StreamHandler(sys.stdout)
+            formatter = jsonlogger.JsonFormatter(
+                fmt='%(asctime)s %(name)s %(levelname)s %(message)s'
+            )
+            log_handler.setFormatter(formatter)
+            
+            logging.root.handlers = [log_handler]
+            logging.root.setLevel(log_level)
+    
+    def _validate_production_config(self, encryption_key, jwt_secret, database_url):
+        """Validate required configuration for production"""
+        missing = []
+        
+        if not encryption_key:
+            missing.append("ENCRYPTION_KEY")
+        if not jwt_secret:
+            missing.append("JWT_SECRET")
+        if not database_url:
+            missing.append("DATABASE_URL")
+        
+        if missing:
+            raise AgriSecureError(
+                f"Production environment requires: {', '.join(missing)}. "
+                "Set these in environment variables or .env file."
+            )
+    
+    def _init_database(self, database_url: str, auto_migrate: bool):
+        """Initialize database connection"""
+        self.logger.info(f"Connecting to database: {database_url.split('@')[-1]}")
+        # Database initialization logic
+        from .adapters.database import DatabaseAdapter
+        self.db = DatabaseAdapter(database_url, auto_migrate)
+    
+    def _init_cache(self, redis_url: str):
+        """Initialize Redis cache"""
+        self.logger.info("Connecting to Redis cache")
+        from .adapters.cache import CacheAdapter
+        self.cache = CacheAdapter(redis_url)
+    
+    def _init_metrics(self):
+        """Initialize Prometheus metrics"""
+        from prometheus_client import Counter, Histogram, Gauge
+        
+        self.metrics = {
+            'requests': Counter('agri_secure_requests_total', 'Total requests'),
+            'errors': Counter('agri_secure_errors_total', 'Total errors'),
+            'response_time': Histogram('agri_secure_response_seconds', 'Response time'),
+            'active_users': Gauge('agri_secure_active_users', 'Active users')
+        }
+        self.logger.debug("Metrics initialized")
+    
+    def _init_tracing(self):
+        """Initialize OpenTelemetry tracing"""
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+        
+        trace.set_tracer_provider(TracerProvider())
+        tracer = trace.get_tracer(__name__)
+        self.logger.debug("Tracing initialized")
+    
+    def share_data(
+        self,
+        data: Dict[str, Any],
+        recipient: Union[str, List[str]],
+        user_role: str,
+        user_id: Optional[str] = None,
+        consent_verified: bool = False,
+        purpose: str = "agricultural_analysis",
+        expiry: Optional[datetime] = None,
+        encrypt: bool = True,
+        audit: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Securely share agricultural data with authorized recipients.
+        
+        This is the main method for data sharing. It handles:
+            - Access control verification
+            - Data encryption
+            - Consent management
+            - Audit logging
+            - Blockchain recording
+            - Recipient notification
+        
+        Args:
+            data: Agricultural data to share (dictionary)
+            recipient: Recipient ID(s) - single user or list
+            user_role: Role of user sharing data
+            user_id: ID of user sharing data
+            consent_verified: Whether farmer consent obtained
+            purpose: Reason for sharing (for audit)
+            expiry: When the share permission expires
+            encrypt: Whether to encrypt the data
+            audit: Whether to record in audit log
+        
+        Returns:
+            Dictionary with:
+                - share_id: Unique identifier for this share
+                - transaction_id: Blockchain transaction ID
+                - encrypted_data: Encrypted data (if encrypt=True)
+                - recipients: List of recipients
+                - timestamp: When shared
+                - expires_at: When access expires
+        
+        Raises:
+            AuthorizationError: If user not authorized to share
+            ValidationError: If data is invalid
+            EncryptionError: If encryption fails
+        """
+        start_time = datetime.utcnow()
+        
+        try:
+            # Update metrics
+            if hasattr(self, 'metrics'):
+                self.metrics['requests'].inc()
+            
+            self.logger.info(
+                f"Data share attempt: {user_role} ({user_id}) -> {recipient}"
+            )
+            
+            # Validate input
+            if not isinstance(data, dict):
+                raise ValidationError("Data must be a dictionary")
+            
+            # Check authorization
+            if not self.access.check_permission(
+                user_role=user_role,
+                resource_type="farm_data",
+                action="share",
+                resource_owner=data.get("farmer_id"),
+                current_user=user_id
+            ):
+                self.logger.warning(
+                    f"Access denied: {user_role} attempted unauthorized share"
+                )
+                if hasattr(self, 'metrics'):
+                    self.metrics['errors'].inc()
+                raise AuthorizationError(
+                    f"{user_role} not authorized to share this data"
+                )
+            
+            # Verify consent for farmer data
+            if "farmer_id" in data and not consent_verified:
+                if user_role != "farmer":
+                    raise AuthorizationError(
+                        "Farmer consent required for data sharing"
+                    )
+            
+            # Generate share ID
+            share_id = generate_id(prefix="share")
+            
+            # Prepare metadata
+            metadata = {
+                "share_id": share_id,
+                "shared_by": user_id or user_role,
+                "shared_by_role": user_role,
+                "recipients": [recipient] if isinstance(recipient, str) else recipient,
+                "purpose": purpose,
+                "timestamp": datetime.utcnow().isoformat(),
+                "expires_at": (expiry or datetime.utcnow() + timedelta(days=30)).isoformat(),
+                "data_types": list(data.keys())
+            }
+            
+            # Encrypt data if requested
+            encrypted_payload = None
+            if encrypt:
+                encrypted_payload = self.encryption.encrypt_data(
+                    data=data,
+                    context={
+                        "purpose": purpose,
+                        "recipients": metadata["recipients"]
+                    }
+                )
+                self.logger.debug("Data encrypted successfully")
+            
+            # Record in blockchain if enabled
+            transaction_id = None
+            if self.ledger and audit:
+                transaction_id = self.ledger.add_transaction(
+                    transaction_type="DATA_SHARE",
+                    data={
+                        "share_id": share_id,
+                        "metadata": metadata,
+                        "data_hash": self.encryption.hash_data(data)
+                    },
+                    initiator=user_id or user_role
+                )
+                self.logger.debug(f"Blockchain transaction: {transaction_id}")
+            
+            # Store share record
+            share_record = {
+                "share_id": share_id,
+                "transaction_id": transaction_id,
+                "metadata": metadata,
+                "encrypted_data": encrypted_payload,
+                "status": "active"
+            }
+            
+            # Save to database if available
+            if hasattr(self, 'db'):
+                self.db.save_share(share_record)
+            
+            # Cache share record
+            if hasattr(self, 'cache'):
+                self.cache.set(
+                    f"share:{share_id}",
+                    share_record,
+                    ttl=metadata.get("expires_at")
+                )
+            
+            # Record response time
+            if hasattr(self, 'metrics'):
+                duration = (datetime.utcnow() - start_time).total_seconds()
+                self.metrics['response_time'].observe(duration)
+            
+            self.logger.info(f"Data shared successfully: {share_id}")
+            
+            return {
+                "success": True,
+                "share_id": share_id,
+                "transaction_id": transaction_id,
+                "encrypted_data": encrypted_payload,
+                "recipients": metadata["recipients"],
+                "timestamp": metadata["timestamp"],
+                "expires_at": metadata["expires_at"],
+                "verification_url": f"/api/verify/{transaction_id}" if transaction_id else None
+            }
+            
+        except Exception as e:
+            self.logger.error(f"Data sharing failed: {str(e)}", exc_info=True)
+            if hasattr(self, 'metrics'):
+                self.metrics['errors'].inc()
+            raise
+    
+    def receive_data(
+        self,
+        share_id: str,
+        user_role: str,
+        user_id: str,
+        access_reason: str = "operational_need"
+    ) -> Dict[str, Any]:
+        """
+        Receive and decrypt shared data.
+        
+        Args:
+            share_id: Share identifier from share_data()
+            user_role: Role of receiving user
+            user_id: ID of receiving user
+            access_reason: Why user needs this data
+        
+        Returns:
+            Decrypted data with metadata
+        """
+        self.logger.info(f"Data receive attempt: {user_role} ({user_id}) -> {share_id}")
+        
+        # Get share record
+        share_record = None
+        
+        # Try cache first
+        if hasattr(self, 'cache'):
+            share_record = self.cache.get(f"share:{share_id}")
+        
+        # Try database if not in cache
+        if not share_record and hasattr(self, 'db'):
+            share_record = self.db.get_share(share_id)
+        
+        if not share_record:
+            raise ValidationError(f"Share {share_id} not found")
+        
+        # Check if share has expired
+        expires_at = datetime.fromisoformat(share_record["metadata"]["expires_at"])
+        if expires_at < datetime.utcnow():
+            raise AuthorizationError("Share has expired")
+        
+        # Check if user is authorized recipient
+        if user_id not in share_record["metadata"]["recipients"]:
+            if user_role not in ["system_admin", "auditor"]:
+                raise AuthorizationError("Not authorized to receive this data")
+        
+        # Decrypt data
+        decrypted_data = self.encryption.decrypt_data(
+            encrypted_payload=share_record["encrypted_data"],
+            context={"user_role": user_role, "user_id": user_id}
+        )
+        
+        # Record access in blockchain
+        if self.ledger:
+            self.ledger.add_transaction(
+                transaction_type="DATA_ACCESS",
+                data={
+                    "share_id": share_id,
+                    "accessor": user_id,
+                    "accessor_role": user_role,
+                    "reason": access_reason,
+                    "timestamp": datetime.utcnow().isoformat()
+                },
+                initiator=user_id
+            )
+        
+        self.logger.info(f"Data accessed successfully: {share_id}")
+        
+        return {
+            "success": True,
+            "data": decrypted_data,
+            "metadata": share_record["metadata"],
+            "accessed_at": datetime.utcnow().isoformat()
+        }
+    
+    def verify_data_integrity(
+        self,
+        transaction_id: str,
+        include_proof: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Verify that data hasn't been tampered with.
+        
+        Args:
+            transaction_id: Blockchain transaction ID
+            include_proof: Include cryptographic proof
+        
+        Returns:
+            Verification results with proof if requested
+        """
+        if not self.ledger:
+            raise AgriSecureError("Blockchain ledger not enabled")
+        
+        self.logger.info(f"Verifying transaction: {transaction_id}")
+        
+        verification = self.ledger.verify_transaction(
+            transaction_id,
+            include_proof=include_proof
+        )
+        
+        return {
+            "transaction_id": transaction_id,
+            "verified": verification["valid"],
+            "timestamp": verification["timestamp"],
+            "block_height": verification.get("block_height"),
+            "previous_hash": verification.get("previous_hash"),
+            "proof": verification.get("proof") if include_proof else None,
+            "message": "Data integrity confirmed" if verification["valid"] 
+                      else "Data may have been tampered with"
+        }
+    
+    def get_audit_trail(
+        self,
+        user_id: Optional[str] = None,
+        resource_id: Optional[str] = None,
+        start_date: Optional[datetime] = None,
+        end_date: Optional[datetime] = None,
+        limit: int = 1000,
+        offset: int = 0,
+        include_blockchain: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Get comprehensive audit trail.
+        
+        Args:
+            user_id: Filter by user
+            resource_id: Filter by resource
+            start_date: Start of date range
+            end_date: End of date range
+            limit: Max records to return
+            offset: Pagination offset
+            include_blockchain: Include blockchain records
+        
+        Returns:
+            Audit trail with metadata
+        """
+        self.logger.info(f"Generating audit trail for user={user_id}, resource={resource_id}")
+        
+        events = []
+        
+        # Get from database if available
+        if hasattr(self, 'db'):
+            db_events = self.db.get_audit_events(
+                user_id=user_id,
+                resource_id=resource_id,
+                start_date=start_date,
+                end_date=end_date,
+                limit=limit,
+                offset=offset
+            )
+            events.extend(db_events)
+        
+        # Get from blockchain if requested
+        if include_blockchain and self.ledger:
+            blockchain_events = self.ledger.get_transactions(
+                user_id=user_id,
+                resource_id=resource_id,
+                start_date=start_date,
+                end_date=end_date,
+                limit=limit
+            )
+            events.extend(blockchain_events)
+        
+        # Sort by timestamp
+        events.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+        
+        return {
+            "total_events": len(events),
+            "events": events[:limit],
+            "filters": {
+                "user_id": user_id,
+                "resource_id": resource_id,
+                "start_date": start_date.isoformat() if start_date else None,
+                "end_date": end_date.isoformat() if end_date else None
+            },
+            "generated_at": datetime.utcnow().isoformat()
+        }
+    
+    def health_check(self, deep: bool = False) -> Dict[str, Any]:
+        """
+        Comprehensive health check of all components.
+        
+        Args:
+            deep: Perform deep checks (may be slower)
+        
+        Returns:
+            Health status of all modules
+        """
+        health = {
+            "status": "healthy",
+            "version": __version__,
+            "app_name": self.app_name,
+            "environment": self.environment,
+            "uptime": (datetime.utcnow() - self.start_time).total_seconds(),
+            "timestamp": datetime.utcnow().isoformat(),
+            "modules": {}
+        }
+        
+        # Check encryption
+        try:
+            test_data = {"test": "health_check", "timestamp": datetime.utcnow().isoformat()}
+            encrypted = self.encryption.encrypt_data(test_data)
+            decrypted = self.encryption.decrypt_data(encrypted)
+            
+            if decrypted["test"] == test_data["test"]:
+                health["modules"]["encryption"] = {
+                    "status": "operational",
+                    "algorithm": "AES-256-GCM",
+                    "key_rotation_days": self.encryption.key_rotation_days
+                }
+            else:
+                health["modules"]["encryption"] = {"status": "degraded", "error": "Encryption/decryption mismatch"}
+                health["status"] = "degraded"
+        except Exception as e:
+            health["modules"]["encryption"] = {"status": "failed", "error": str(e)}
+            health["status"] = "degraded"
+        
+        # Check authentication
+        try:
+            health["modules"]["authentication"] = {
+                "status": "operational",
+                "mfa_required": self.auth.mfa_required,
+                "active_sessions": len(self.auth.active_sessions) if hasattr(self.auth, 'active_sessions') else 0
+            }
+        except Exception as e:
+            health["modules"]["authentication"] = {"status": "failed", "error": str(e)}
+            health["status"] = "degraded"
+        
+        # Check database
+        if hasattr(self, 'db'):
+            try:
+                db_status = self.db.health_check()
+                health["modules"]["database"] = db_status
+                if db_status.get("status") != "operational":
+                    health["status"] = "degraded"
+            except Exception as e:
+                health["modules"]["database"] = {"status": "failed", "error": str(e)}
+                health["status"] = "degraded"
+        
+        # Check cache
+        if hasattr(self, 'cache'):
+            try:
+                cache_status = self.cache.health_check()
+                health["modules"]["cache"] = cache_status
+                if cache_status.get("status") != "operational":
+                    health["status"] = "degraded"
+            except Exception as e:
+                health["modules"]["cache"] = {"status": "failed", "error": str(e)}
+                health["status"] = "degraded"
+        
+        # Check blockchain
+        if self.ledger:
+            try:
+                if deep:
+                    # Deep check - verify entire chain
+                    verification = self.ledger.verify_chain()
+                    health["modules"]["blockchain"] = {
+                        "status": "operational" if verification["valid"] else "compromised",
+                        "blocks": verification["blocks_checked"],
+                        "height": verification.get("height")
+                    }
+                    if not verification["valid"]:
+                        health["status"] = "degraded"
+                else:
+                    health["modules"]["blockchain"] = {
+                        "status": "operational",
+                        "height": self.ledger.get_height()
+                    }
+            except Exception as e:
+                health["modules"]["blockchain"] = {"status": "failed", "error": str(e)}
+                health["status"] = "degraded"
+        
+        # Check metrics
+        if hasattr(self, 'metrics'):
+            health["modules"]["metrics"] = {"status": "operational"}
+        
+        # Check tracing
+        if hasattr(self, 'tracer'):
+            health["modules"]["tracing"] = {"status": "operational"}
+        
+        return health
+    
+    def create_user(
+        self,
+        username: str,
+        password: str,
+        role: str,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        metadata: Optional[Dict] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new user in the system.
+        
+        Args:
+            username: Unique username
+            password: User password (will be hashed)
+            role: User role (farmer, extension_officer, etc.)
+            email: User email (for notifications)
+            phone: User phone (for MFA)
+            metadata: Additional user metadata
+        
+        Returns:
+            User object with ID and MFA setup
+        """
+        self.logger.info(f"Creating user: {username} with role: {role}")
+        
+        # Validate role
+        if role not in [r.value for r in UserRole]:
+            valid_roles = [r.value for r in UserRole]
+            raise ValidationError(f"Invalid role. Must be one of: {valid_roles}")
+        
+        # Create user in authentication system
+        user = self.auth.register_user(
+            username=username,
+            password=password,
+            role=role,
+            email=email,
+            phone=phone
+        )
+        
+        # Add metadata
+        if metadata:
+            user["metadata"] = metadata
+        
+        # Save to database if available
+        if hasattr(self, 'db'):
+            self.db.save_user(user)
+        
+        # Cache user
+        if hasattr(self, 'cache'):
+            self.cache.set(f"user:{user['user_id']}", user, ttl=86400)
+        
+        # Record in blockchain
+        if self.ledger:
+            self.ledger.add_transaction(
+                transaction_type="USER_CREATED",
+                data={"user_id": user["user_id"], "role": role, "username": username},
+                initiator="system"
+            )
+        
+        self.logger.info(f"User created successfully: {user['user_id']}")
+        
+        return user
+    
+    def authenticate_user(
+        self,
+        username: str,
+        password: str,
+        mfa_code: Optional[str] = None,
+        ip_address: Optional[str] = None,
+        user_agent: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Authenticate a user with MFA.
+        
+        Args:
+            username: Username
+            password: Password
+            mfa_code: MFA code from authenticator app
+            ip_address: Client IP for audit
+            user_agent: Client user agent for audit
+        
+        Returns:
+            Session with JWT token and user info
+        """
+        self.logger.info(f"Authentication attempt: {username} from {ip_address}")
+        
+        # Authenticate
+        session = self.auth.authenticate(
+            username=username,
+            password=password,
+            mfa_code=mfa_code
+        )
+        
+        # Add audit info
+        session["ip_address"] = ip_address
+        session["user_agent"] = user_agent
+        session["authenticated_at"] = datetime.utcnow().isoformat()
+        
+        # Record in blockchain
+        if self.ledger:
+            self.ledger.add_transaction(
+                transaction_type="USER_LOGIN",
+                data={
+                    "user_id": session["user_id"],
+                    "ip_address": ip_address,
+                    "success": True
+                },
+                initiator=session["user_id"]
+            )
+        
+        # Update metrics
+        if hasattr(self, 'metrics'):
+            self.metrics['active_users'].inc()
+        
+        self.logger.info(f"Authentication successful: {username}")
+        
+        return session
+    
+    def __repr__(self) -> str:
+        return f"<AgriculturalSecurity app={self.app_name} env={self.environment}>"
+    
+    def __str__(self) -> str:
+        return f"Agricultural Security Framework - {self.app_name} ({self.environment})"
+
+# Export main class
+__all__ = [
+    "AgriculturalSecurity",
+    "UserRole",
+    "DataClassification",
+    "AgriSecureError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "EncryptionError",
+    "ValidationError",
+    "BlockchainError"
+]