gitwebhooks 2.0.0__py3-none-any.whl

gitwebhooks/__init__.py

@@ -0,0 +1,18 @@
+"""Git Webhooks Server - Modular package structure.
+
+Automated deployment server supporting GitHub, Gitee, GitLab, and custom webhooks.
+"""
+
+__version__ = '2.0.0'
+
+# Export main classes for convenient import paths
+from .server import WebhookServer
+from .models.provider import Provider
+from .models.request import WebhookRequest
+
+__all__ = [
+    '__version__',
+    'WebhookServer',
+    'Provider',
+    'WebhookRequest',
+]

gitwebhooks/__main__.py

@@ -0,0 +1,10 @@
+"""Python module entry point
+
+Supports running the server using `python3 -m gitwebhooks.cli`.
+"""
+
+from gitwebhooks.cli import main
+import sys
+
+if __name__ == '__main__':
+    sys.exit(main())

gitwebhooks/auth/__init__.py

@@ -0,0 +1,20 @@
+"""Authentication and signature verification module
+
+Verifies signatures and tokens for webhook requests.
+"""
+
+from .verifier import SignatureVerifier
+from .github import GithubSignatureVerifier
+from .gitee import GiteeSignatureVerifier
+from .gitlab import GitlabTokenVerifier
+from .custom import CustomTokenVerifier
+from .factory import VerifierFactory
+
+__all__ = [
+    'SignatureVerifier',
+    'GithubSignatureVerifier',
+    'GiteeSignatureVerifier',
+    'GitlabTokenVerifier',
+    'CustomTokenVerifier',
+    'VerifierFactory',
+]

gitwebhooks/auth/custom.py

@@ -0,0 +1,40 @@
+"""Custom token verifier
+
+Verifies tokens from custom webhooks.
+"""
+
+from gitwebhooks.auth.verifier import SignatureVerifier
+from gitwebhooks.models.result import SignatureVerificationResult
+
+
+class CustomTokenVerifier(SignatureVerifier):
+    """Custom token verifier"""
+
+    def __init__(self, verify_enabled: bool = True):
+        """Initialize verifier
+
+        Args:
+            verify_enabled: Whether verification is enabled (False = always return success)
+        """
+        self.verify_enabled = verify_enabled
+
+    def verify(self, payload: bytes, signature: str, secret: str,
+               **kwargs) -> SignatureVerificationResult:
+        """Verify custom token
+
+        Args:
+            payload: Raw request body bytes (unused)
+            signature: Token value from custom header
+            secret: Configured secret key
+            **kwargs: Unused
+
+        Returns:
+            SignatureVerificationResult instance
+        """
+        if not self.verify_enabled:
+            return SignatureVerificationResult.success()
+
+        if signature == secret:
+            return SignatureVerificationResult.success()
+        else:
+            return SignatureVerificationResult.failure('Invalid token')

gitwebhooks/auth/factory.py

@@ -0,0 +1,73 @@
+"""Verifier factory class
+
+Creates corresponding verifier instances based on provider type.
+"""
+
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.auth.verifier import SignatureVerifier
+from gitwebhooks.auth.github import GithubSignatureVerifier
+from gitwebhooks.auth.gitee import GiteeSignatureVerifier
+from gitwebhooks.auth.gitlab import GitlabTokenVerifier
+from gitwebhooks.auth.custom import CustomTokenVerifier
+from gitwebhooks.utils.exceptions import UnsupportedProviderError
+
+
+class VerifierFactory:
+    """Verifier factory class
+
+    Creates corresponding verifier instances based on provider type
+    """
+
+    _verifiers = {
+        Provider.GITHUB: GithubSignatureVerifier(),
+        Provider.GITEE: GiteeSignatureVerifier(),
+        Provider.GITLAB: GitlabTokenVerifier(),
+        Provider.CUSTOM: None,  # Custom verifier created dynamically
+    }
+
+    @classmethod
+    def get_verifier(cls, provider: Provider,
+                    verify_enabled: bool = True) -> SignatureVerifier:
+        """Get verifier for the specified provider
+
+        Args:
+            provider: Provider type
+            verify_enabled: Whether verification is enabled (CUSTOM only)
+
+        Returns:
+            SignatureVerifier instance
+
+        Raises:
+            UnsupportedProviderError: Unsupported provider
+        """
+        if provider == Provider.CUSTOM:
+            return CustomTokenVerifier(verify_enabled=verify_enabled)
+
+        verifier = cls._verifiers.get(provider)
+        if verifier is None:
+            raise UnsupportedProviderError(f'No verifier for provider: {provider}')
+        return verifier
+
+    @classmethod
+    def create_github_verifier(cls) -> GithubSignatureVerifier:
+        """Create GitHub verifier (convenience method)"""
+        return GithubSignatureVerifier()
+
+    @classmethod
+    def create_gitee_verifier(cls) -> GiteeSignatureVerifier:
+        """Create Gitee verifier (convenience method)"""
+        return GiteeSignatureVerifier()
+
+    @classmethod
+    def create_gitlab_verifier(cls) -> GitlabTokenVerifier:
+        """Create GitLab verifier (convenience method)"""
+        return GitlabTokenVerifier()
+
+    @classmethod
+    def create_custom_verifier(cls, verify_enabled: bool = True) -> CustomTokenVerifier:
+        """Create custom verifier (convenience method)
+
+        Args:
+            verify_enabled: Whether verification is enabled
+        """
+        return CustomTokenVerifier(verify_enabled=verify_enabled)

gitwebhooks/auth/gitee.py

@@ -0,0 +1,86 @@
+"""Gitee HMAC-SHA256/password verifier
+
+Verifies signatures or passwords from Gitee webhooks.
+
+According to Gitee official documentation:
+https://help.gitee.com/webhook/how-to-verify-webhook-keys
+
+Signature generation algorithm:
+1. sign_string = timestamp + "\\n" + secret
+2. hmac_sha256 = HmacSHA256(sign_string)
+3. signature = base64(urlEncode(hmac_sha256))
+
+Note: The Gitee signature does NOT include the request payload.
+"""
+
+import base64
+import hashlib
+import hmac
+
+from gitwebhooks.auth.verifier import SignatureVerifier
+from gitwebhooks.models.result import SignatureVerificationResult
+
+
+class GiteeSignatureVerifier(SignatureVerifier):
+    """Gitee HMAC-SHA256/password verifier"""
+
+    HASH_ALGORITHM = hashlib.sha256
+
+    def verify(self, payload: bytes, signature: str, secret: str,
+               **kwargs) -> SignatureVerificationResult:
+        """Verify Gitee signature or password
+
+        Gitee sends X-Gitee-Timestamp in both signature and password modes.
+        To distinguish between them:
+        1. First try password validation (direct comparison)
+        2. If password fails and timestamp exists, try signature validation
+
+        This approach works because:
+        - Passwords are typically short plaintext without special chars
+        - Signatures are Base64 encoded, containing chars like '+', '/', '='
+
+        Args:
+            payload: Raw request body bytes (not used in Gitee signature)
+            signature: X-Gitee-Token header value
+            secret: Webhook secret/password
+            **kwargs: May contain 'timestamp' key
+
+        Returns:
+            SignatureVerificationResult instance
+        """
+        if signature is None:
+            return SignatureVerificationResult.failure('Missing signature or password')
+
+        # Step 1: Try password validation first (direct comparison)
+        if hmac.compare_digest(signature, secret):
+            return SignatureVerificationResult.success()
+
+        # Step 2: If password failed, try signature validation
+        timestamp = kwargs.get('timestamp')
+        if timestamp is not None:
+            # Verify signature
+            try:
+                timestamp_int = int(timestamp)
+            except ValueError:
+                return SignatureVerificationResult.failure('Invalid timestamp format')
+
+            # Gitee signature: timestamp + "\n" + secret
+            # Reference: https://help.gitee.com/webhook/how-to-verify-webhook-keys
+            sign_string = f'{timestamp_int}\n{secret}'
+            secret_bytes = secret.encode('utf-8')
+
+            signature_bytes = hmac.new(
+                secret_bytes,
+                sign_string.encode('utf-8'),
+                self.HASH_ALGORITHM
+            ).digest()
+            # Gitee sends Base64 encoded signature (NOT URL encoded)
+            expected_signature = base64.b64encode(signature_bytes).decode('utf-8')
+
+            if hmac.compare_digest(signature, expected_signature):
+                return SignatureVerificationResult.success()
+            else:
+                return SignatureVerificationResult.failure('Invalid signature')
+
+        # Password validation failed and no timestamp for signature validation
+        return SignatureVerificationResult.failure('Invalid password')

gitwebhooks/auth/github.py

@@ -0,0 +1,52 @@
+"""GitHub HMAC-SHA1 signature verifier
+
+Verifies HMAC-SHA1 signatures from GitHub webhooks.
+"""
+
+import hashlib
+import hmac
+
+from gitwebhooks.auth.verifier import SignatureVerifier
+from gitwebhooks.models.result import SignatureVerificationResult
+
+
+class GithubSignatureVerifier(SignatureVerifier):
+    """GitHub HMAC-SHA1 signature verifier"""
+
+    PREFIX = 'sha1='
+    HASH_ALGORITHM = hashlib.sha1
+
+    def verify(self, payload: bytes, signature: str, secret: str,
+               **kwargs) -> SignatureVerificationResult:
+        """Verify GitHub HMAC-SHA1 signature
+
+        Args:
+            payload: Raw request body bytes
+            signature: X-Hub-Signature header value
+            secret: Webhook secret
+            **kwargs: Unused
+
+        Returns:
+            SignatureVerificationResult instance
+        """
+        if signature is None:
+            return SignatureVerificationResult.failure('Missing signature')
+
+        if not secret:
+            return SignatureVerificationResult.failure('Secret not configured')
+
+        if not signature.startswith(self.PREFIX):
+            return SignatureVerificationResult.failure('Invalid signature format')
+
+        secret_bytes = secret.encode('utf-8')
+        expected_signature = self.PREFIX + hmac.new(
+            secret_bytes,
+            payload,
+            self.HASH_ALGORITHM
+        ).hexdigest()
+
+        # Use constant-time comparison
+        if hmac.compare_digest(signature, expected_signature):
+            return SignatureVerificationResult.success()
+        else:
+            return SignatureVerificationResult.failure('Invalid signature')

gitwebhooks/auth/gitlab.py

@@ -0,0 +1,29 @@
+"""GitLab token verifier
+
+Verifies tokens from GitLab webhooks.
+"""
+
+from gitwebhooks.auth.verifier import SignatureVerifier
+from gitwebhooks.models.result import SignatureVerificationResult
+
+
+class GitlabTokenVerifier(SignatureVerifier):
+    """GitLab token verifier"""
+
+    def verify(self, payload: bytes, signature: str, secret: str,
+               **kwargs) -> SignatureVerificationResult:
+        """Verify GitLab token
+
+        Args:
+            payload: Raw request body bytes (unused)
+            signature: X-Gitlab-Token header value
+            secret: Webhook token
+            **kwargs: Unused
+
+        Returns:
+            SignatureVerificationResult instance
+        """
+        if signature == secret:
+            return SignatureVerificationResult.success()
+        else:
+            return SignatureVerificationResult.failure('Invalid token')

gitwebhooks/auth/verifier.py

@@ -0,0 +1,34 @@
+"""Signature verifier base class
+
+Defines the abstract interface for signature verification.
+"""
+
+from abc import ABC, abstractmethod
+
+from gitwebhooks.models.result import SignatureVerificationResult
+
+
+class SignatureVerifier(ABC):
+    """Signature verifier base class
+
+    All platform-specific verifiers must inherit from this class and implement the verification method.
+    """
+
+    @abstractmethod
+    def verify(self, payload: bytes, signature: str, secret: str,
+               **kwargs) -> SignatureVerificationResult:
+        """Verify signature
+
+        Args:
+            payload: Raw request body bytes
+            signature: Signature string from request
+            secret: Configured secret key
+            **kwargs: Platform-specific additional parameters (e.g., timestamp)
+
+        Returns:
+            SignatureVerificationResult instance
+
+        Raises:
+            SignatureValidationError: When verification fails (optional)
+        """
+        pass

gitwebhooks/cli.py

@@ -0,0 +1,107 @@
+"""CLI main function
+
+Command-line interface module providing compatibility with the original git-webhooks-server.py.
+"""
+
+import getopt
+import sys
+from pathlib import Path
+from typing import List
+
+from gitwebhooks.server import WebhookServer
+from gitwebhooks.utils.exceptions import ConfigurationError
+
+
+def main(argv: List[str] = None) -> int:
+    """Main entry point
+
+    Args:
+        argv: Command-line argument list (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+
+    Raises:
+        SystemExit: Exit on error
+
+    Command Line Arguments:
+        -h, --help      Show help message and exit
+        -c, --config    Specify configuration file path
+
+    Default Config Path:
+        /usr/local/etc/git-webhooks-server.ini
+
+    Examples:
+        python3 -m gitwebhooks.cli -c /path/to/config.ini
+        gitwebhooks-cli --config /etc/webhooks.ini
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Default configuration file path
+    default_config = '/usr/local/etc/git-webhooks-server.ini'
+    config_file = default_config
+
+    # Parse command-line arguments
+    try:
+        opts, _ = getopt.getopt(argv, 'hc:', ['config=', 'help'])
+    except getopt.GetoptError:
+        print_help()
+        return 1
+
+    for opt, value in opts:
+        if opt in ('-h', '--help'):
+            print_help()
+            return 0
+        elif opt in ('-c', '--config'):
+            config_file = value
+
+    # Check configuration file exists
+    if not Path(config_file).exists():
+        print(f'Error: Configuration file not found: {config_file}', file=sys.stderr)
+        return 1
+
+    # Create and run server
+    try:
+        server = WebhookServer(config_path=config_file)
+        server.run()
+        return 0
+    except ConfigurationError as e:
+        print(f'Configuration error: {e}', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print('\nServer stopped by user')
+        return 0
+    except Exception as e:
+        print(f'Error: {e}', file=sys.stderr)
+        return 1
+
+
+def print_help() -> None:
+    """Print help information
+
+    Display command-line usage instructions
+    """
+    print('Git Webhooks Server - Automated deployment webhook handler')
+    print()
+    print('Usage:')
+    print('  gitwebhooks-cli -c <configuration_file>')
+    print('  gitwebhooks-cli --config=<configuration_file>')
+    print('  gitwebhooks-cli --help')
+    print()
+    print('Options:')
+    print('  -h, --help      Show this help message and exit')
+    print('  -c, --config    Path to INI configuration file')
+    print()
+    print('Default configuration path:')
+    print('  /usr/local/etc/git-webhooks-server.ini')
+    print()
+    print('Examples:')
+    print('  gitwebhooks-cli -c /etc/webhooks.ini')
+    print('  gitwebhooks-cli --config=./my-config.ini')
+    print()
+    print('Report bugs to: https://github.com/yourusername/git-webhooks-server/issues')
+
+
+if __name__ == '__main__':
+    sys.exit(main())

gitwebhooks/config/__init__.py

@@ -0,0 +1,17 @@
+"""Configuration management module
+
+Responsible for loading, parsing, and managing INI format configuration files.
+"""
+
+from .loader import ConfigLoader
+from .models import ProviderConfig, RepositoryConfig
+from .registry import ConfigurationRegistry
+from .server import ServerConfig
+
+__all__ = [
+    'ConfigLoader',
+    'ProviderConfig',
+    'RepositoryConfig',
+    'ServerConfig',
+    'ConfigurationRegistry',
+]

gitwebhooks/config/loader.py

@@ -0,0 +1,170 @@
+"""Configuration loader
+
+Load and parse configuration from INI files.
+"""
+
+import configparser
+from pathlib import Path
+from typing import Dict, Optional
+
+from gitwebhooks.config.models import ProviderConfig, RepositoryConfig
+from gitwebhooks.models.provider import Provider
+from gitwebhooks.utils.exceptions import ConfigurationError
+
+
+class ConfigLoader:
+    """Configuration loader
+
+    Responsible for loading and validating configuration from INI files
+    """
+
+    def __init__(self, config_path: str):
+        """Initialize configuration loader
+
+        Args:
+            config_path: INI configuration file path
+
+        Raises:
+            ConfigurationError: File does not exist or cannot be parsed
+        """
+        self.config_path = Path(config_path)
+        self.parser = configparser.ConfigParser()
+        self._load_file()
+
+    def _load_file(self) -> None:
+        """Load configuration file
+
+        Raises:
+            ConfigurationError: File does not exist or parsing failed
+        """
+        if not self.config_path.exists():
+            raise ConfigurationError(f'Config file not found: {self.config_path}')
+
+        try:
+            self.parser.read(str(self.config_path))
+        except (configparser.Error, UnicodeDecodeError) as e:
+            raise ConfigurationError(f'Failed to parse config: {e}')
+
+    def load_provider_config(self, provider: Provider) -> ProviderConfig:
+        """Load configuration for specified provider
+
+        Args:
+            provider: Provider type
+
+        Returns:
+            ProviderConfig instance
+
+        Raises:
+            ConfigurationError: Configuration section does not exist
+        """
+        try:
+            return ProviderConfig.from_config_parser(self.parser, provider)
+        except configparser.NoSectionError:
+            # Return default configuration
+            return ProviderConfig(
+                provider=provider,
+                verify=False,
+                secret='',
+                handle_events=[]
+            )
+
+    def load_all_provider_configs(self) -> Dict[Provider, ProviderConfig]:
+        """Load all provider configurations
+
+        Returns:
+            Mapping of provider to configuration
+        """
+        configs = {}
+        for provider in Provider:
+            configs[provider] = self.load_provider_config(provider)
+        return configs
+
+    def load_repository_config(self, name: str) -> Optional[RepositoryConfig]:
+        """Load configuration for specified repository
+
+        Args:
+            name: Repository name (configuration section name)
+
+        Returns:
+            RepositoryConfig instance, or None if section does not exist
+        """
+        return RepositoryConfig.from_config_parser(self.parser, name)
+
+    def load_all_repository_configs(self) -> Dict[str, RepositoryConfig]:
+        """Load all repository configurations
+
+        Returns:
+            Mapping of repository name to configuration
+
+        Note:
+            Skips reserved section names: server, ssl, github, gitee, gitlab, custom
+        """
+        configs = {}
+        reserved_sections = self._get_reserved_sections()
+
+        for section in self.parser.sections():
+            if section not in reserved_sections:
+                repo_config = self.load_repository_config(section)
+                if repo_config is not None:
+                    configs[section] = repo_config
+
+        return configs
+
+    def _get_reserved_sections(self) -> set:
+        """Get reserved configuration section names
+
+        Returns:
+            Set of reserved section names
+        """
+        return {'server', 'ssl', 'github', 'gitee', 'gitlab', 'custom'}
+
+    def get_server_config(self) -> Dict[str, any]:
+        """Get server configuration
+
+        Returns:
+            Dictionary containing server configuration, keys include:
+            - address: Listen address
+            - port: Listen port
+            - log_file: Log file path
+        """
+        return {
+            'address': self.parser.get('server', 'address', fallback='0.0.0.0'),
+            'port': self.parser.getint('server', 'port', fallback=6789),
+            'log_file': self.parser.get('server', 'log_file', fallback='').strip(),
+        }
+
+    def get_ssl_config(self) -> Optional[Dict[str, str]]:
+        """Get SSL configuration
+
+        Returns:
+            Dictionary containing SSL configuration, or None if not enabled
+            Keys include:
+            - enable: Whether SSL is enabled
+            - key_file: SSL key file path
+            - cert_file: SSL certificate file path
+        """
+        try:
+            if not self.parser.getboolean('ssl', 'enable'):
+                return None
+        except (configparser.NoSectionError, ValueError):
+            return None
+
+        return {
+            'enable': True,
+            'key_file': self.parser.get('ssl', 'key_file'),
+            'cert_file': self.parser.get('ssl', 'cert_file'),
+        }
+
+    def validate_repository_configs(self) -> None:
+        """Validate all repository configurations
+
+        Raises:
+            ConfigurationError: Configuration is invalid
+        """
+        configs = self.load_all_repository_configs()
+
+        for name, config in configs.items():
+            try:
+                config.validate()
+            except ConfigurationError as e:
+                raise ConfigurationError(f'Repository {name}: {e}')