dcert 3.0.35__py3-none-win_amd64.whl

dcert/__init__.py

@@ -0,0 +1,91 @@
+"""dcert: A Python MCP wrapper for the dcert TLS certificate MCP server.
+
+This package provides a FastMCP proxy that wraps the dcert-mcp Rust binary,
+automatically exposing all TLS certificate tools via the Model Context Protocol.
+
+The proxy pattern means this package requires zero code changes when new
+tools are added to the Rust binary — they are discovered and forwarded
+automatically at runtime via the MCP protocol.
+
+Usage as a server:
+    from dcert import create_server
+    server = create_server()
+    server.run()
+
+Usage as a client:
+    from dcert import create_client
+    async with create_client() as client:
+        tools = await client.list_tools()
+        result = await client.call_tool("analyze_certificate", {"target": "example.com"})
+
+Usage with typed async wrappers:
+    from dcert.tools import DcertClient
+    async with DcertClient() as dcert:
+        result = await dcert.analyze_certificate(target="example.com")
+"""
+
+__version__ = "3.0.35"
+
+from dcert.client import create_client
+from dcert.resilience import (
+    CircuitBreaker,
+    CircuitBreakerOpen,
+    OTelConfig,
+    RateLimiter,
+    ResilienceConfig,
+    setup_otel,
+    truncate_response,
+)
+from dcert.server import create_server
+from dcert.tools import (
+    DcertClient,
+    DcertConnectionError,
+    DcertError,
+    DcertTimeoutError,
+    DcertToolError,
+    analyze_certificate,
+    check_expiry,
+    check_revocation,
+    compare_certificates,
+    convert_pem_to_pfx,
+    convert_pfx_to_pem,
+    create_keystore,
+    create_truststore,
+    export_pem,
+    tls_connection_info,
+    verify_key_match,
+)
+
+__all__ = [
+    # Core API
+    "create_server",
+    "create_client",
+    "__version__",
+    # Client
+    "DcertClient",
+    # Exceptions
+    "DcertError",
+    "DcertTimeoutError",
+    "DcertConnectionError",
+    "DcertToolError",
+    # Resilience
+    "ResilienceConfig",
+    "OTelConfig",
+    "CircuitBreaker",
+    "CircuitBreakerOpen",
+    "RateLimiter",
+    "setup_otel",
+    "truncate_response",
+    # Tool wrappers
+    "analyze_certificate",
+    "check_expiry",
+    "check_revocation",
+    "compare_certificates",
+    "tls_connection_info",
+    "export_pem",
+    "verify_key_match",
+    "convert_pfx_to_pem",
+    "convert_pem_to_pfx",
+    "create_keystore",
+    "create_truststore",
+]

dcert/checksums.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.0.0",
+  "archives": {}
+}

dcert/cli.py

@@ -0,0 +1,263 @@
+"""CLI entry points for dcert.
+
+Provides three commands:
+  - ``dcert``:        Thin wrapper that execs the bundled Rust ``dcert`` binary.
+  - ``dcert-mcp``:    Thin wrapper that execs the bundled Rust ``dcert-mcp`` binary.
+  - ``dcert-python``: Python MCP proxy server wrapping the Rust binary via FastMCP.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import stat
+import sys
+from pathlib import Path
+
+
+def _is_python_script(path: str) -> bool:
+    """Check if *path* is a Python console-script wrapper (not a compiled binary).
+
+    Reads the first 128 bytes; if the file starts with ``#!`` and the first
+    line contains ``python``, it is a pip-generated console_script wrapper
+    and must be skipped to avoid an infinite exec loop (see helm-mcp PR #33).
+    """
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(128)
+        first_line = head.split(b"\n", 1)[0].lower()
+        return head[:2] == b"#!" and b"python" in first_line
+    except OSError:
+        return False
+
+
+def _find_bundled_binary(name: str) -> str | None:
+    """Locate a binary bundled inside the package ``bin/`` directory.
+
+    If the binary exists but is not executable, it is chmod'd on first use.
+
+    Returns:
+        Absolute path to the binary, or ``None`` if not found.
+    """
+    pkg_dir = Path(__file__).parent
+    bundled = pkg_dir / "bin" / name
+    # On Windows the bundled binary carries a .exe suffix (dcert.exe).
+    if not bundled.is_file() and sys.platform == "win32" and not name.endswith(".exe"):
+        win_bundled = pkg_dir / "bin" / f"{name}.exe"
+        if win_bundled.is_file():
+            bundled = win_bundled
+    if not bundled.is_file():
+        return None
+    # Ensure the binary is executable (pip may not preserve permissions
+    # for package-data files extracted from wheels).
+    if not os.access(str(bundled), os.X_OK):
+        try:
+            bundled.chmod(bundled.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        except OSError:
+            return None
+    return str(bundled)
+
+
+def _find_binary(name: str) -> str:
+    """Find a binary by name: bundled in package, then PATH, then auto-download.
+
+    Skips Python console-script wrappers on PATH to avoid infinite exec
+    loops when pip installs the universal wheel.
+
+    Raises:
+        FileNotFoundError: If the binary cannot be located.
+    """
+    # 1. Bundled binary inside the Python package
+    bundled = _find_bundled_binary(name)
+    if bundled:
+        return bundled
+
+    # 2. Binary on PATH — skip Python console-script wrappers
+    found = shutil.which(name)
+    if found and not _is_python_script(found):
+        return found
+
+    # 3. Auto-download from GitHub Releases (fallback for universal wheel)
+    from dcert import __version__
+    from dcert.download import ensure_binary
+
+    try:
+        downloaded = ensure_binary(__version__)
+        if downloaded:
+            return downloaded
+    except Exception:
+        pass
+
+    raise FileNotFoundError(
+        f"{name} binary not found. Install dcert via:\n"
+        "  brew tap SCGIS-Wales/tap && brew install dcert\n"
+        "  or: pip install dcert  (platform wheel bundles the binary)"
+    )
+
+
+def dcert_main() -> None:
+    """Entry point for the ``dcert`` command.
+
+    Locates the bundled Rust ``dcert`` binary and replaces the current
+    process with it, forwarding all command-line arguments.
+    """
+    try:
+        binary = _find_binary("dcert")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    os.execvp(binary, [binary] + sys.argv[1:])
+
+
+def dcert_mcp_main() -> None:
+    """Entry point for the ``dcert-mcp`` command.
+
+    Locates the bundled Rust ``dcert-mcp`` binary and replaces the current
+    process with it, forwarding all command-line arguments.
+    """
+    try:
+        binary = _find_binary("dcert-mcp")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    os.execvp(binary, [binary] + sys.argv[1:])
+
+
+def main() -> None:
+    """Run the dcert MCP proxy server (``dcert-python`` command)."""
+    parser = argparse.ArgumentParser(
+        description="dcert: MCP server for TLS certificate analysis",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http", "sse"],
+        default="stdio",
+        help="Transport mode (default: stdio)",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host for HTTP/SSE mode (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for HTTP/SSE mode (default: 8080)",
+    )
+    parser.add_argument(
+        "--binary",
+        default=None,
+        help="Path to dcert-mcp binary (auto-detected if not set)",
+    )
+    parser.add_argument(
+        "--setup",
+        action="store_true",
+        help="Download the dcert-mcp binary and exit",
+    )
+
+    # -- Resiliency flags --
+    parser.add_argument(
+        "--no-retry",
+        action="store_true",
+        help="Disable automatic retry on connection errors",
+    )
+    parser.add_argument(
+        "--no-circuit-breaker",
+        action="store_true",
+        help="Disable circuit breaker",
+    )
+    parser.add_argument(
+        "--rate-limit",
+        type=float,
+        default=None,
+        metavar="RPS",
+        help="Enable rate limiting at RPS requests per second",
+    )
+    parser.add_argument(
+        "--cache",
+        action="store_true",
+        help="Enable response caching",
+    )
+    parser.add_argument(
+        "--bulkhead-max",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum concurrent tool calls (default: 10)",
+    )
+
+    # -- OpenTelemetry --
+    parser.add_argument(
+        "--otel",
+        action="store_true",
+        help="Enable OpenTelemetry tracing",
+    )
+    parser.add_argument(
+        "--otel-exporter",
+        choices=["console", "otlp"],
+        default=None,
+        help="OpenTelemetry exporter (default: console)",
+    )
+
+    args = parser.parse_args()
+
+    if args.setup:
+        from dcert import __version__
+        from dcert.download import ensure_binary
+
+        try:
+            path = ensure_binary(__version__)
+            if path:
+                print(f"dcert-mcp binary ready at: {path}")
+            else:
+                print(
+                    "No checksums available for this platform. Install the binary manually.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+        except Exception as e:
+            print(f"Error downloading binary: {e}", file=sys.stderr)
+            sys.exit(1)
+        return
+
+    # Apply CLI overrides to environment so ResilienceConfig picks them up
+    if args.no_retry:
+        os.environ["DCERT_MCP_NO_RETRY"] = "1"
+    if args.no_circuit_breaker:
+        os.environ["DCERT_MCP_NO_CIRCUIT_BREAKER"] = "1"
+    if args.rate_limit is not None:
+        os.environ["DCERT_MCP_RATE_LIMIT_ENABLED"] = "1"
+        os.environ["DCERT_MCP_RATE_LIMIT_RPS"] = str(args.rate_limit)
+    if args.cache:
+        os.environ["DCERT_MCP_CACHE_ENABLED"] = "1"
+    if args.bulkhead_max is not None:
+        os.environ["DCERT_MCP_BULKHEAD_MAX"] = str(args.bulkhead_max)
+
+    # OpenTelemetry
+    if args.otel:
+        os.environ["DCERT_MCP_OTEL_ENABLED"] = "1"
+    if args.otel_exporter is not None:
+        os.environ["DCERT_MCP_OTEL_EXPORTER"] = args.otel_exporter
+
+    from dcert.resilience import OTelConfig, setup_otel
+
+    setup_otel(OTelConfig())
+
+    from dcert.server import create_server
+
+    try:
+        server = create_server(binary_path=args.binary)
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.transport == "stdio":
+        server.run()
+    else:
+        server.run(transport=args.transport, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

dcert/client.py

@@ -0,0 +1,44 @@
+"""FastMCP client for connecting to the dcert-mcp Rust binary.
+
+Provides a thin client wrapper that connects to the Rust binary via stdio
+transport. All tool discovery is handled by the MCP protocol at runtime,
+so new tools added to the binary are automatically available.
+"""
+
+from __future__ import annotations
+
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+
+from dcert.server import _build_subprocess_env, _find_binary
+
+
+def create_client(
+    binary_path: str | None = None,
+    env: dict[str, str] | None = None,
+) -> Client:
+    """Create a FastMCP client connected to the dcert-mcp Rust binary via stdio.
+
+    Args:
+        binary_path: Explicit path to the dcert-mcp binary. Auto-detected if ``None``.
+        env: Additional environment variables to pass to the subprocess.
+
+    Returns:
+        A FastMCP ``Client`` instance. Use as an async context manager.
+
+    Example::
+
+        async with create_client() as client:
+            tools = await client.list_tools()
+            result = await client.call_tool(
+                "analyze_certificate", {"target": "example.com"}
+            )
+    """
+    binary = binary_path or _find_binary()
+    subprocess_env = _build_subprocess_env(extra_env=env)
+    transport = StdioTransport(
+        command=binary,
+        args=[],
+        env=subprocess_env or None,
+    )
+    return Client(transport)

dcert/download.py

@@ -0,0 +1,268 @@
+"""Auto-download dcert binaries from GitHub Releases.
+
+Downloads the platform-appropriate tar.gz archive, verifies its SHA256
+checksum against values embedded in the package (checksums.json), extracts
+the ``dcert`` and ``dcert-mcp`` binaries, and installs them to a
+PATH-accessible directory.
+
+Supply chain security:
+  - Checksums are baked into the wheel at build time, not fetched at runtime.
+  - Downloads use HTTPS with certificate verification.
+  - Archive is written to a temp file and only extracted after checksum passes.
+  - No shell commands or install-time hooks are used.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import platform
+import shutil
+import stat
+import sys
+import sysconfig
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+GITHUB_RELEASE_URL = (
+    "https://github.com/SCGIS-Wales/dcert/releases/download/v{version}/{archive_name}"
+)
+
+# Timeout for the HTTP connection and read (seconds).
+DOWNLOAD_TIMEOUT = 60
+
+# Maps (system, machine) to Rust target triple
+PLATFORM_MAP: dict[tuple[str, str], str] = {
+    ("darwin", "arm64"): "aarch64-apple-darwin",
+    ("darwin", "x86_64"): "x86_64-apple-darwin",
+    ("linux", "x86_64"): "x86_64-unknown-linux-gnu",
+    ("windows", "amd64"): "x86_64-pc-windows-msvc",
+}
+
+
+def _is_windows() -> bool:
+    return platform.system().lower() == "windows"
+
+
+def _bin_filename(stem: str) -> str:
+    """Return the on-disk binary filename for *stem* (adds .exe on Windows)."""
+    return f"{stem}.exe" if _is_windows() else stem
+
+
+def _load_checksums() -> dict:
+    """Load embedded checksums from package data.
+
+    Returns:
+        Parsed checksums dict, or empty dict if file is missing.
+    """
+    checksums_path = Path(__file__).parent / "checksums.json"
+    if not checksums_path.exists():
+        return {}
+    with open(checksums_path) as f:
+        return json.load(f)
+
+
+def _get_target_triple() -> str | None:
+    """Get the Rust target triple for the current platform.
+
+    Returns:
+        Target triple like ``aarch64-apple-darwin``, or ``None`` if
+        the platform is not supported.
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    return PLATFORM_MAP.get((system, machine))
+
+
+def _get_archive_name() -> str | None:
+    """Get the platform-specific archive filename.
+
+    Returns:
+        Archive name like ``dcert-aarch64-apple-darwin.tar.gz``,
+        or ``None`` if the platform is not supported.
+    """
+    triple = _get_target_triple()
+    if triple is None:
+        return None
+    # Windows binaries are shipped as .zip (PowerShell-friendly); other
+    # platforms use .tar.gz.
+    ext = "zip" if _is_windows() else "tar.gz"
+    return f"dcert-{triple}.{ext}"
+
+
+def _get_install_dir() -> Path:
+    """Get the best directory for installing the binaries.
+
+    Prefers the Python scripts directory (where pip puts console_scripts,
+    which is on PATH). Falls back to ``~/.local/bin``.
+
+    Returns:
+        Writable directory path.
+    """
+    scripts_dir = Path(sysconfig.get_path("scripts"))
+    if os.access(str(scripts_dir), os.W_OK):
+        return scripts_dir
+    # Fallback: user-local bin
+    local_bin = Path.home() / ".local" / "bin"
+    local_bin.mkdir(parents=True, exist_ok=True)
+    return local_bin
+
+
+def _verify_checksum(file_path: Path, expected_sha256: str) -> bool:
+    """Verify SHA256 checksum of a file.
+
+    Args:
+        file_path: Path to the file to verify.
+        expected_sha256: Expected hex-encoded SHA256 digest.
+
+    Returns:
+        True if checksum matches, False otherwise.
+    """
+    sha256 = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest() == expected_sha256
+
+
+def _extract_binaries(archive_path: Path, install_dir: Path) -> Path:
+    """Extract dcert and dcert-mcp binaries from a downloaded archive.
+
+    Handles both .tar.gz (Linux/macOS) and .zip (Windows) archives. On
+    Windows the binaries are named ``dcert.exe`` / ``dcert-mcp.exe``.
+
+    Args:
+        archive_path: Path to the downloaded .tar.gz or .zip file.
+        install_dir: Directory to install binaries into.
+
+    Returns:
+        Path to the installed dcert-mcp binary.
+
+    Raises:
+        RuntimeError: If the dcert-mcp binary is not found in the archive.
+    """
+    is_win = _is_windows()
+    mcp_name = _bin_filename("dcert-mcp")
+    wanted = {_bin_filename("dcert"), mcp_name}
+    found_mcp = False
+
+    def _emit(name: str, file_obj) -> None:
+        nonlocal found_mcp
+        # Write contents manually rather than using extract() to avoid path
+        # traversal — member names could contain "../" even after Path.name.
+        target = install_dir / name
+        with open(target, "wb") as out:
+            shutil.copyfileobj(file_obj, out)
+        if not is_win:
+            target.chmod(target.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        if name == mcp_name:
+            found_mcp = True
+
+    if archive_path.suffix == ".zip" or is_win:
+        with zipfile.ZipFile(archive_path) as zf:
+            for member in zf.infolist():
+                name = Path(member.filename).name
+                if name in wanted:
+                    with zf.open(member) as file_obj:
+                        _emit(name, file_obj)
+    else:
+        with tarfile.open(archive_path, "r:gz") as tar:
+            for member in tar.getmembers():
+                name = Path(member.name).name
+                if name in wanted:
+                    file_obj = tar.extractfile(member)
+                    if file_obj is None:
+                        continue
+                    _emit(name, file_obj)
+
+    if not found_mcp:
+        raise RuntimeError("dcert-mcp binary not found in archive")
+
+    return install_dir / mcp_name
+
+
+def ensure_binary(version: str) -> str | None:
+    """Ensure the dcert-mcp binary is available, downloading if needed.
+
+    If the binary already exists in the install directory and is executable,
+    returns its path immediately. Otherwise downloads the platform archive
+    from GitHub Releases, verifies the SHA256 checksum, extracts the
+    binaries, and installs them.
+
+    Args:
+        version: Package version (e.g. ``"3.0.12"``). Used to construct
+            the download URL and match against checksums.
+
+    Returns:
+        Absolute path to the dcert-mcp binary, or ``None`` if download
+        is not possible (e.g. no checksums available for this platform).
+
+    Raises:
+        RuntimeError: If the downloaded archive fails checksum verification.
+        urllib.error.URLError: If the download fails.
+    """
+    install_dir = _get_install_dir()
+    target = install_dir / _bin_filename("dcert-mcp")
+
+    # Already installed?
+    if target.exists() and os.access(str(target), os.X_OK):
+        return str(target)
+
+    # Load embedded checksums
+    archive_name = _get_archive_name()
+    if archive_name is None:
+        logger.debug(
+            "Unsupported platform %s/%s — skipping auto-download",
+            platform.system(),
+            platform.machine(),
+        )
+        return None
+
+    checksums = _load_checksums()
+    expected = checksums.get("archives", {}).get(archive_name)
+    if not expected:
+        logger.debug("No checksum for %s — skipping auto-download", archive_name)
+        return None
+
+    url = GITHUB_RELEASE_URL.format(version=version, archive_name=archive_name)
+    logger.info("Downloading dcert binaries from %s", url)
+    print(
+        f"Downloading dcert binaries for {platform.system()}/{platform.machine()}...",
+        file=sys.stderr,
+    )
+
+    # Download to temp file, verify checksum, then extract
+    fd, tmp_path = tempfile.mkstemp(dir=str(install_dir), prefix=".dcert-")
+    try:
+        os.close(fd)
+        with (
+            urllib.request.urlopen(url, timeout=DOWNLOAD_TIMEOUT) as resp,
+            open(tmp_path, "wb") as out,
+        ):
+            shutil.copyfileobj(resp, out)
+
+        if not _verify_checksum(Path(tmp_path), expected):
+            raise RuntimeError(
+                f"Checksum mismatch for {archive_name}. "
+                "The downloaded archive does not match the expected hash. "
+                "This could indicate a tampered download."
+            )
+
+        # Extract binaries from the verified archive
+        mcp_path = _extract_binaries(Path(tmp_path), install_dir)
+
+        print(f"Installed dcert binaries to {install_dir}", file=sys.stderr)
+        logger.info("Installed dcert binaries to %s", install_dir)
+        return str(mcp_path)
+    except Exception:
+        # Clean up temp file on any failure
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise