TimeTracker/app/models/api_token.py

"""API Token model for REST API authentication"""
import secrets
from datetime import datetime, timedelta
from app import db
from sqlalchemy.orm import relationship


class ApiToken(db.Model):
    """API Token for authenticating REST API requests"""
    
    __tablename__ = 'api_tokens'
    
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(100), nullable=False)
    description = db.Column(db.Text)
    token_hash = db.Column(db.String(128), unique=True, nullable=False, index=True)
    token_prefix = db.Column(db.String(10), nullable=False)  # First 8 chars for identification
    
    # Ownership and permissions
    user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False)
    user = relationship('User', backref='api_tokens')
    
    # Scopes for fine-grained permissions (comma-separated)
    # Examples: read:projects, write:time_entries, admin:all
    scopes = db.Column(db.Text, default='')
    
    # Token lifecycle
    created_at = db.Column(db.DateTime, nullable=False, default=datetime.utcnow)
    expires_at = db.Column(db.DateTime)
    last_used_at = db.Column(db.DateTime)
    is_active = db.Column(db.Boolean, default=True, nullable=False)
    
    # IP restrictions (comma-separated list of allowed IPs/CIDR blocks)
    ip_whitelist = db.Column(db.Text)
    
    # Usage tracking
    usage_count = db.Column(db.Integer, default=0, nullable=False)
    
    def __repr__(self):
        return f'<ApiToken {self.name} ({self.token_prefix}...)>'
    
    @staticmethod
    def generate_token():
        """Generate a new secure random token"""
        # Format: tt_<32 random chars>
        random_part = secrets.token_urlsafe(32)[:32]
        return f"tt_{random_part}"
    
    @staticmethod
    def hash_token(token):
        """Hash a token for storage"""
        import hashlib
        return hashlib.sha256(token.encode()).hexdigest()
    
    @classmethod
    def create_token(cls, user_id, name, description='', scopes='', expires_days=None):
        """Create a new API token
        
        Args:
            user_id: User ID who owns this token
            name: Human-readable name for the token
            description: Optional description
            scopes: Comma-separated list of scopes
            expires_days: Number of days until expiration (None = never expires)
        
        Returns:
            tuple: (ApiToken instance, plain_token)
        """
        plain_token = cls.generate_token()
        token_hash = cls.hash_token(plain_token)
        token_prefix = plain_token[:8]
        
        expires_at = None
        if expires_days:
            expires_at = datetime.utcnow() + timedelta(days=expires_days)
        
        api_token = cls(
            name=name,
            description=description,
            token_hash=token_hash,
            token_prefix=token_prefix,
            user_id=user_id,
            scopes=scopes,
            expires_at=expires_at
        )
        
        return api_token, plain_token
    
    def verify_token(self, plain_token):
        """Verify if the provided token matches this record"""
        return self.token_hash == self.hash_token(plain_token)
    
    def is_valid(self):
        """Check if token is valid (active and not expired)"""
        if not self.is_active:
            return False
        if self.expires_at and self.expires_at < datetime.utcnow():
            return False
        return True
    
    def has_scope(self, required_scope):
        """Check if token has a specific scope
        
        Args:
            required_scope: The scope to check (e.g., 'read:projects')
        
        Returns:
            bool: True if token has the scope
        """
        if not self.scopes:
            return False
        
        token_scopes = [s.strip() for s in self.scopes.split(',')]
        
        # Check for wildcard admin scope
        if 'admin:all' in token_scopes or '*' in token_scopes:
            return True
        
        # Check for exact match
        if required_scope in token_scopes:
            return True
        
        # Check for wildcard resource scope (e.g., read:* matches read:projects)
        resource_type = required_scope.split(':')[0] if ':' in required_scope else None
        if resource_type and f"{resource_type}:*" in token_scopes:
            return True
        
        return False
    
    def record_usage(self, ip_address=None):
        """Record token usage"""
        self.last_used_at = datetime.utcnow()
        self.usage_count += 1
        db.session.commit()
    
    def to_dict(self, include_token=False):
        """Convert to dictionary for API responses"""
        data = {
            'id': self.id,
            'name': self.name,
            'description': self.description,
            'token_prefix': self.token_prefix,
            'scopes': self.scopes.split(',') if self.scopes else [],
            'created_at': self.created_at.isoformat() if self.created_at else None,
            'expires_at': self.expires_at.isoformat() if self.expires_at else None,
            'last_used_at': self.last_used_at.isoformat() if self.last_used_at else None,
            'is_active': self.is_active,
            'usage_count': self.usage_count,
            'user_id': self.user_id
        }
        
        return data