gitwebhooks 2.1.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`.
+"""
+
+from gitwebhooks.main 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/__init__.py

@@ -0,0 +1,107 @@
+"""CLI subcommands module
+
+Provides subcommand registration and implementation for gitwebhooks-cli.
+"""
+
+from gitwebhooks.cli.service import cmd_install, cmd_uninstall
+from gitwebhooks.cli.config import cmd_init, cmd_view
+
+
+def register_subparsers(subparsers):
+    """Register all CLI subparsers
+
+    Args:
+        subparsers: argparse subparsers object from ArgumentParser.add_subparsers()
+
+    Returns:
+        None
+    """
+    # Register service subcommand
+    register_service_subparser(subparsers)
+
+    # Register config subcommand
+    register_config_subparser(subparsers)
+
+
+def register_service_subparser(subparsers):
+    """Register service subcommand and its actions
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    service_parser = subparsers.add_parser(
+        'service',
+        help='Manage systemd service installation'
+    )
+    service_subparsers = service_parser.add_subparsers(dest='service_action')
+
+    # install action
+    install_parser = service_subparsers.add_parser('install')
+    install_parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force overwrite existing service'
+    )
+    install_parser.add_argument(
+        '-v', '--verbose',
+        action='count',
+        default=0,
+        help='Increase verbosity (can be used: -v, -vv)'
+    )
+    install_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview service file without installing'
+    )
+    install_parser.set_defaults(func=cmd_install)
+
+    # uninstall action
+    uninstall_parser = service_subparsers.add_parser('uninstall')
+    uninstall_parser.add_argument(
+        '--purge',
+        action='store_true',
+        help='Also remove configuration file'
+    )
+    uninstall_parser.set_defaults(func=cmd_uninstall)
+
+
+def register_config_subparser(subparsers):
+    """Register config subcommand and its actions
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    config_parser = subparsers.add_parser(
+        'config',
+        help='Manage gitwebhooks configuration'
+    )
+    config_subparsers = config_parser.add_subparsers(dest='config_action')
+
+    # init action
+    init_parser = config_subparsers.add_parser(
+        'init',
+        help='Initialize configuration file using interactive wizard'
+    )
+    init_parser.add_argument(
+        'level',
+        nargs='?',
+        choices=['system', 'local', 'user'],
+        help='Configuration level (system/local/user). If not specified, will be prompted.'
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # view action
+    view_parser = config_subparsers.add_parser('view')
+    view_parser.add_argument(
+        '-c',
+        '--config',
+        dest='config',
+        help='Path to configuration file (default: auto-detect)'
+    )
+    view_parser.set_defaults(func=cmd_view)

gitwebhooks/cli/config.py

@@ -0,0 +1,216 @@
+"""Configuration CLI commands
+
+Provides configuration initialization and viewing commands.
+"""
+
+import argparse
+import configparser
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from gitwebhooks.cli.init_wizard import Wizard
+from gitwebhooks.utils.constants import (
+    CONFIG_SEARCH_PATHS,
+    SENSITIVE_KEYWORDS,
+    COLOR_SENSITIVE,
+    COLOR_RESET
+)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Initialize configuration file using interactive wizard
+
+    Args:
+        args: Parsed command-line arguments
+            - level: Configuration level (system/local/user), optional
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+    """
+    try:
+        # Create and run wizard
+        level = getattr(args, 'level', None)
+        wizard = Wizard(level=level)
+        config_path = wizard.run()
+        return 0
+
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+    except PermissionError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 2
+    except FileExistsError:
+        print("操作已取消", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\n操作已取消")
+        return 0
+
+
+def locate_config_file(args: argparse.Namespace) -> Optional[Path]:
+    """Locate configuration file based on arguments or default priority
+
+    Args:
+        args: Parsed command-line arguments
+            - config: User-specified configuration file path (optional)
+
+    Returns:
+        Path to configuration file, or None if not found
+    """
+    # If user specified a config file with -c, use it
+    if hasattr(args, 'config') and args.config:
+        config_path = Path(args.config).expanduser()
+        if config_path.exists():
+            return config_path
+        return None
+
+    # Otherwise, search in priority order
+    for path_str in CONFIG_SEARCH_PATHS:
+        config_path = Path(path_str).expanduser()
+        if config_path.exists():
+            return config_path
+
+    return None
+
+
+def cmd_view(args: argparse.Namespace) -> int:
+    """View configuration file content
+
+    Args:
+        args: Parsed command-line arguments
+            - config: User-specified configuration file path (optional)
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+    """
+    # Locate configuration file
+    config_path = locate_config_file(args)
+
+    if config_path is None:
+        # Handle file not found
+        if hasattr(args, 'config') and args.config:
+            print(f'Error: Configuration file not found: {args.config}', file=sys.stderr)
+        else:
+            print('Error: No configuration file found.', file=sys.stderr)
+            print('\nSearched paths (in priority order):', file=sys.stderr)
+            for i, path_str in enumerate(CONFIG_SEARCH_PATHS, 1):
+                expanded = Path(path_str).expanduser()
+                print(f'  {i}. {expanded}', file=sys.stderr)
+            print('\nTo create a configuration file, run:', file=sys.stderr)
+            print('  gitwebhooks-cli config init', file=sys.stderr)
+        return 1
+
+    # Read and parse configuration
+    try:
+        parser = configparser.ConfigParser()
+        parser.read(config_path, encoding='utf-8')
+    except configparser.Error as e:
+        print(f'Error: Failed to parse configuration file: {config_path}', file=sys.stderr)
+        print(f'\nParsing error: {e}', file=sys.stderr)
+        print('\nPlease check the file format and fix any syntax errors.', file=sys.stderr)
+        return 1
+    except PermissionError:
+        print(f'Error: Permission denied: {config_path}', file=sys.stderr)
+        print('\nPlease check file permissions or run with appropriate privileges.', file=sys.stderr)
+        return 1
+
+    # Determine source type
+    source = 'user-specified' if (hasattr(args, 'config') and args.config) else 'auto-detected'
+
+    # Format and display output
+    print(format_config_header(config_path, source))
+    print()
+    print(format_config_content(parser))
+
+    return 0
+
+
+def format_config_header(config_path: Path, source: str) -> str:
+    """Format configuration file header
+
+    Args:
+        config_path: Path to configuration file
+        source: Source type ('user-specified' or 'auto-detected')
+
+    Returns:
+        Formatted header string
+    """
+    # Handle symlinks
+    display_path = str(config_path)
+    if config_path.is_symlink():
+        target = config_path.resolve()
+        display_path = f'{config_path} -> {target}'
+
+    return f'Config File: {display_path} (source: {source})'
+
+
+def format_config_content(parser: configparser.ConfigParser) -> str:
+    """Format configuration content by sections
+
+    Args:
+        parser: ConfigParser instance with loaded configuration
+
+    Returns:
+        Formatted configuration content
+    """
+    if not parser.sections():
+        return '(Configuration file is empty or has no valid sections)'
+
+    lines = []
+    for section in parser.sections():
+        lines.append(f'[{section}]')
+        for key, value in parser.items(section):
+            formatted_value = format_sensitive_field(key, value)
+            lines.append(f'{key} = {formatted_value}')
+        lines.append('')  # Empty line between sections
+
+    return '\n'.join(lines)
+
+
+def is_sensitive_key(key: str) -> bool:
+    """Check if a configuration key is sensitive
+
+    Args:
+        key: Configuration key name
+
+    Returns:
+        True if key contains sensitive keyword, False otherwise
+    """
+    key_lower = key.lower()
+    return any(keyword in key_lower for keyword in SENSITIVE_KEYWORDS)
+
+
+def should_use_color() -> bool:
+    """Check if color output should be used
+
+    Returns:
+        True if color should be used, False otherwise
+    """
+    # Check NO_COLOR environment variable
+    if os.getenv('NO_COLOR'):
+        return False
+
+    # Check TERM environment variable
+    term = os.getenv('TERM', '')
+    if term == 'dumb':
+        return False
+
+    return True
+
+
+def format_sensitive_field(key: str, value: str) -> str:
+    """Format a configuration field with sensitive field highlighting
+
+    Args:
+        key: Configuration key name
+        value: Configuration value
+
+    Returns:
+        Formatted value with color if sensitive
+    """
+    if is_sensitive_key(key) and should_use_color():
+        return f'{COLOR_SENSITIVE}{value}{COLOR_RESET}'
+    return value