certmate-sdk 0.1.0__tar.gz

certmate_sdk-0.1.0/.gitignore

@@ -0,0 +1,111 @@
+# Node (Tailwind CSS build)
+node_modules/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+venv*/
+.venv/
+env/
+ENV/
+
+# Application specific
+# SECURITY: Never commit settings.json - may contain API tokens and secrets
+settings.json
+data/settings.json
+cloudflare.ini
+certificates/
+data/
+logs/
+*.pem
+*.key
+*.crt
+*.csr
+letsencrypt/
+.secrets/
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Backup files
+*_old.*
+*_backup.*
+
+# Planning and development documents
+NEXT_FEATURES.md
+PLAN_2.0.md
+PLAN_*.docx
+
+htmlcov/
+.pytest_cache/
+.coverage
+coverage.xml
+test_results.json
+
+# Local dev / debug scripts (kept on developer machines only)
+debug_*.py
+
+backups/
+app.py.backup
+
+.claude/
+test_screenshots/
+
+# Test files with sensitive data
+test_real_cert_*.py
+test_api_*.py
+test_certificate_creation_*.py
+real_world_test_*.py
+integration_test_*.py
+github_response.md
+
+# local
+PLAN.md
+scratch/
+test_settings.py
+# Internal audit docs (not for distribution)
+UI_AUDIT.md
+UI_SHOTS_ANALYSIS.md
+
+# Theme migration screenshot baseline (regenerated by scripts/theme_baseline.py)
+theme-baseline/
+UI_DRACONIAN_ANALYSIS.md
+UI_UX_Opinioni_CertMate.pdf
+UI_REDESIGN_PLAN.md

certmate_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: certmate-sdk
+Version: 0.1.0
+Summary: Thin Python client for the CertMate REST API
+Project-URL: Homepage, https://github.com/fabriziosalmi/certmate
+Project-URL: Source, https://github.com/fabriziosalmi/certmate/tree/main/clients/certmate-sdk
+Author-email: Fabrizio Salmi <fabrizio.salmi@gmail.com>
+License: MIT
+Keywords: acme,certificates,certmate,letsencrypt,sdk,tls
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# certmate-sdk
+
+A thin, dependency-light Python client for the [CertMate](https://github.com/fabriziosalmi/certmate) REST API.
+
+```python
+from certmate import Client
+
+with Client("https://certmate.example.com", token="...") as c:
+    job = c.create_certificate("app.example.com", dns_provider="cloudflare", wait=True)
+    for cert in c.list_certificates():
+        print(cert.domain, cert.days_until_expiry)
+    print(c.audit_verify()["ok"])
+```
+
+`base_url`/`token` fall back to `CERTMATE_URL` / `CERTMATE_TOKEN`. The only
+runtime dependency is `httpx` — no server code, no certbot.

certmate_sdk-0.1.0/README.md

@@ -0,0 +1,16 @@
+# certmate-sdk
+
+A thin, dependency-light Python client for the [CertMate](https://github.com/fabriziosalmi/certmate) REST API.
+
+```python
+from certmate import Client
+
+with Client("https://certmate.example.com", token="...") as c:
+    job = c.create_certificate("app.example.com", dns_provider="cloudflare", wait=True)
+    for cert in c.list_certificates():
+        print(cert.domain, cert.days_until_expiry)
+    print(c.audit_verify()["ok"])
+```
+
+`base_url`/`token` fall back to `CERTMATE_URL` / `CERTMATE_TOKEN`. The only
+runtime dependency is `httpx` — no server code, no certbot.

certmate_sdk-0.1.0/certmate/__init__.py

@@ -0,0 +1,17 @@
+"""certmate-sdk — a thin Python client for the CertMate REST API.
+
+    from certmate import Client
+    with Client("https://certmate.example.com", token="...") as c:
+        job = c.create_certificate("app.example.com", dns_provider="cloudflare", wait=True)
+"""
+from .client import Client
+from .errors import (APIError, AuthError, CertMateError, ConflictError,
+                     JobFailed, JobTimeout, NotFoundError)
+from .models import Certificate, Job
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client", "Certificate", "Job",
+    "CertMateError", "APIError", "AuthError", "NotFoundError", "ConflictError",
+    "JobFailed", "JobTimeout",
+]

certmate_sdk-0.1.0/certmate/client.py

@@ -0,0 +1,198 @@
+"""Synchronous HTTP client for the CertMate REST API.
+
+Endpoints mirror the ones the MCP server drives (the working reference client),
+so the SDK talks to the same `/api/...` surface the web UI and agents use.
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+
+from .errors import (APIError, AuthError, ConflictError, JobFailed, JobTimeout,
+                     NotFoundError)
+from .models import Certificate, Job
+
+_DEFAULT_URL = "http://localhost:8000"
+
+
+class Client:
+    """A thin CertMate API client.
+
+    >>> with Client("https://certmate.example.com", token="...") as c:
+    ...     for cert in c.list_certificates():
+    ...         print(cert.domain, cert.days_until_expiry)
+
+    ``base_url``/``token`` fall back to ``CERTMATE_URL`` / ``CERTMATE_TOKEN``.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, token: Optional[str] = None,
+                 *, timeout: float = 30.0, verify: bool = True):
+        base_url = (base_url or os.getenv("CERTMATE_URL") or _DEFAULT_URL).rstrip("/")
+        token = token if token is not None else os.getenv("CERTMATE_TOKEN")
+        headers = {"Accept": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(base_url=base_url, headers=headers,
+                                  timeout=timeout, verify=verify)
+        self.base_url = base_url
+
+    # -- lifecycle -----------------------------------------------------------
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- low level -----------------------------------------------------------
+    def _request(self, method: str, path: str, **kw) -> Any:
+        resp = self._http.request(method, path, **kw)
+        if resp.status_code // 100 == 2:
+            if not resp.content:
+                return None
+            ctype = resp.headers.get("content-type", "")
+            return resp.json() if "application/json" in ctype else resp.content
+        # Error path: pull CertMate's {error, code} shape when present.
+        payload: Any = None
+        code = None
+        message = f"HTTP {resp.status_code}"
+        try:
+            payload = resp.json()
+            if isinstance(payload, dict):
+                message = payload.get("error") or payload.get("message") or message
+                code = payload.get("code")
+        except Exception:
+            payload = resp.text
+        exc_cls = {401: AuthError, 403: AuthError, 404: NotFoundError,
+                   409: ConflictError}.get(resp.status_code, APIError)
+        raise exc_cls(message, status=resp.status_code, code=code, payload=payload)
+
+    # -- certificates --------------------------------------------------------
+    def list_certificates(self) -> List[Certificate]:
+        data = self._request("GET", "/api/certificates")
+        items = data.get("certificates", data) if isinstance(data, dict) else data
+        return [Certificate.from_dict(d) for d in (items or [])]
+
+    def get_certificate(self, domain: str) -> Certificate:
+        data = self._request("GET", f"/api/certificates/{domain}")
+        return Certificate.from_dict(data if isinstance(data, dict) else {"domain": domain})
+
+    def create_certificate(self, domain: str, *, dns_provider: Optional[str] = None,
+                           ca_provider: Optional[str] = None,
+                           san_domains: Optional[List[str]] = None,
+                           account_id: Optional[str] = None,
+                           wait: bool = False,
+                           on_progress: Optional[Callable[[Job], None]] = None,
+                           **extra: Any) -> Job:
+        """Submit an async issuance. Returns the accepted Job immediately;
+        with ``wait=True`` polls until the job reaches a terminal state (and
+        raises :class:`JobFailed` on failure)."""
+        body: Dict[str, Any] = {"domain": domain, "async": True}
+        if dns_provider:
+            body["dns_provider"] = dns_provider
+        if ca_provider:
+            body["ca_provider"] = ca_provider
+        if san_domains:
+            body["san_domains"] = san_domains
+        if account_id:
+            body["account_id"] = account_id
+        body.update(extra)
+        data = self._request("POST", "/api/certificates/create", json=body)
+        job = Job.from_dict(data if isinstance(data, dict) else {})
+        if not job.job_id:
+            # Server ran it synchronously (async not honoured): treat as done.
+            job.status = job.status or "succeeded"
+            return job
+        return self.wait_for_job(job.job_id, on_progress=on_progress) if wait else job
+
+    def renew_certificate(self, domain: str, *, force: bool = False) -> Dict[str, Any]:
+        # Always send an (empty) JSON body so endpoints that read request.json
+        # don't 415 on a bodyless POST.
+        params = {"force": "true"} if force else None
+        return self._request("POST", f"/api/certificates/{domain}/renew",
+                             params=params, json={}) or {}
+
+    def reissue_certificate(self, domain: str, **body: Any) -> Dict[str, Any]:
+        return self._request("POST", f"/api/certificates/{domain}/reissue", json=body) or {}
+
+    def delete_certificate(self, domain: str) -> None:
+        self._request("DELETE", f"/api/certificates/{domain}")
+
+    def download_certificate(self, domain: str, fmt: str = "json") -> Any:
+        """Download the bundle. ``fmt`` is one of json/pem/zip/pfx (json returns
+        a dict, the binary formats return bytes)."""
+        return self._request("GET", f"/api/certificates/{domain}/download",
+                             params={"format": fmt})
+
+    def set_auto_renew(self, domain: str, enabled: bool) -> Dict[str, Any]:
+        return self._request("PUT", f"/api/certificates/{domain}/auto-renew",
+                             json={"enabled": bool(enabled)}) or {}
+
+    def deploy_certificate(self, domain: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/certificates/{domain}/deploy", json={}) or {}
+
+    # -- async jobs ----------------------------------------------------------
+    def get_job(self, job_id: str) -> Job:
+        return Job.from_dict(self._request("GET", f"/api/certificates/jobs/{job_id}") or {})
+
+    def wait_for_job(self, job_id: str, *, interval: float = 2.0, timeout: float = 600.0,
+                     on_progress: Optional[Callable[[Job], None]] = None) -> Job:
+        deadline = None  # computed lazily to avoid importing time at module import
+        start = time.monotonic()
+        while True:
+            job = self.get_job(job_id)
+            if on_progress:
+                on_progress(job)
+            if job.is_terminal:
+                if job.failed:
+                    raise JobFailed(job.error or f"job {job_id} failed", job=job)
+                return job
+            if time.monotonic() - start > timeout:
+                raise JobTimeout(f"job {job_id} did not finish within {timeout:.0f}s")
+            time.sleep(interval)
+
+    # -- dns -----------------------------------------------------------------
+    def list_dns_providers(self) -> Any:
+        return self._request("GET", "/api/settings/dns-providers")
+
+    def list_dns_accounts(self, provider: Optional[str] = None) -> Any:
+        path = f"/api/dns/{provider}/accounts" if provider else "/api/dns/accounts"
+        return self._request("GET", path)
+
+    def test_dns_provider(self, provider: str, **config: Any) -> Dict[str, Any]:
+        """Preflight a DNS provider without issuing. Backs the CLI ``--dry-run``."""
+        body = {"provider": provider}
+        body.update(config)
+        return self._request("POST", "/api/web/certificates/test-provider", json=body) or {}
+
+    # -- audit / misc --------------------------------------------------------
+    def audit_verify(self) -> Dict[str, Any]:
+        """Verify the audit chain. The endpoint returns 200 when intact and
+        409 (WITH the full result body) when the chain is broken/absent — both
+        are valid verification results, so return the dict in either case and
+        only raise on a genuine transport/auth error. Inspect ``result['ok']``.
+        """
+        try:
+            return self._request("GET", "/api/audit/verify") or {}
+        except ConflictError as e:
+            if isinstance(e.payload, dict):
+                return e.payload
+            raise
+
+    def activity(self, limit: int = 100) -> Any:
+        return self._request("GET", "/api/activity", params={"limit": limit})
+
+    def health(self) -> Dict[str, Any]:
+        return self._request("GET", "/health") or {}
+
+    # -- backups -------------------------------------------------------------
+    def list_backups(self) -> Any:
+        return self._request("GET", "/api/web/backups")
+
+    def create_backup(self, *, reason: str = "manual") -> Dict[str, Any]:
+        return self._request("POST", "/api/web/backups/create", json={"reason": reason}) or {}

certmate_sdk-0.1.0/certmate/errors.py

@@ -0,0 +1,47 @@
+"""Exception hierarchy for the CertMate SDK."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class CertMateError(Exception):
+    """Base class for every SDK error."""
+
+
+class APIError(CertMateError):
+    """The API returned a non-2xx response.
+
+    ``status`` is the HTTP status code; ``code`` is CertMate's machine-readable
+    error code (e.g. ``DOMAIN_OUT_OF_SCOPE``) when present; ``payload`` is the
+    parsed response body."""
+
+    def __init__(self, message: str, *, status: int, code: Optional[str] = None,
+                 payload: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+
+class AuthError(APIError):
+    """401/403 — missing, invalid, or insufficiently-scoped credentials."""
+
+
+class NotFoundError(APIError):
+    """404 — the domain / resource does not exist."""
+
+
+class ConflictError(APIError):
+    """409 — e.g. the certificate already exists, or an operation is in flight."""
+
+
+class JobFailed(CertMateError):
+    """An async issuance/renewal job finished in a failed state."""
+
+    def __init__(self, message: str, *, job: Any = None):
+        super().__init__(message)
+        self.job = job
+
+
+class JobTimeout(CertMateError):
+    """wait_for_job exceeded its timeout before the job reached a terminal state."""

certmate_sdk-0.1.0/certmate/models.py

@@ -0,0 +1,78 @@
+"""Light, tolerant dataclasses over the CertMate API responses.
+
+Kept deliberately forgiving: the API is the source of truth, so every model
+keeps the raw dict and only surfaces the well-known fields as typed
+attributes. Unknown/absent fields never raise — the SDK must not break when
+the server adds a field."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Certificate:
+    domain: str
+    expiry_date: Optional[str] = None
+    days_until_expiry: Optional[int] = None
+    needs_renewal: Optional[bool] = None
+    ca_provider: Optional[str] = None
+    dns_provider: Optional[str] = None
+    auto_renew: Optional[bool] = None
+    san_domains: List[str] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Certificate":
+        d = d or {}
+        return cls(
+            domain=d.get("domain") or d.get("name") or "",
+            expiry_date=d.get("expiry_date") or d.get("expires") or d.get("not_after"),
+            days_until_expiry=d.get("days_until_expiry"),
+            needs_renewal=d.get("needs_renewal"),
+            ca_provider=d.get("ca_provider") or d.get("staging"),
+            dns_provider=d.get("dns_provider"),
+            auto_renew=d.get("auto_renew"),
+            san_domains=list(d.get("san_domains") or []),
+            raw=d,
+        )
+
+
+# Terminal job states, normalised.
+JOB_DONE = {"succeeded", "success", "completed", "done"}
+JOB_FAILED = {"failed", "error"}
+
+
+@dataclass
+class Job:
+    job_id: str
+    operation: Optional[str] = None
+    domain: Optional[str] = None
+    status: Optional[str] = None
+    error: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Job":
+        d = d or {}
+        return cls(
+            job_id=d.get("job_id") or d.get("id") or "",
+            operation=d.get("operation"),
+            domain=d.get("domain"),
+            status=(d.get("status") or d.get("state")),
+            error=d.get("error"),
+            raw=d,
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        s = (self.status or "").lower()
+        return s in JOB_DONE or s in JOB_FAILED
+
+    @property
+    def succeeded(self) -> bool:
+        return (self.status or "").lower() in JOB_DONE
+
+    @property
+    def failed(self) -> bool:
+        return (self.status or "").lower() in JOB_FAILED

certmate_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "certmate-sdk"
+version = "0.1.0"
+description = "Thin Python client for the CertMate REST API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Fabrizio Salmi", email = "fabrizio.salmi@gmail.com" }]
+keywords = ["certmate", "acme", "letsencrypt", "tls", "certificates", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Internet :: WWW/HTTP",
+]
+# Deliberately tiny: the SDK is an HTTP client, not the server. No certbot,
+# no DNS plugins, no cloud SDKs — `pip install certmate-sdk` stays light.
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://github.com/fabriziosalmi/certmate"
+Source = "https://github.com/fabriziosalmi/certmate/tree/main/clients/certmate-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["certmate"]