swarmauri_certs_acme 0.3.3.dev3

ACME certificate service for Swarmauri

---

Swarmauri ACME Certificate Service

Community plugin providing an ACME (RFC 8555) certificate service built on top of Swarmauri's certificate interfaces.

Features

• Implements AcmeCertService, a drop-in CertServiceBase compatible class for Swarmauri workflows.
• Supports ACME directory discovery, order creation, finalization, and full chain retrieval.
• Handles RSA and EC key material while exposing capability metadata through supports().
• Convenience helpers for certificate verification and parsing using cryptography primitives.

Prerequisites

• Python 3.10 or newer.
• Existing ACME account key material (PEM encoded) accessible to your Swarmauri runtime.
• Network access to your chosen ACME directory (defaults to Let's Encrypt production).
• DNS or HTTP challenge automation handled externally; this service focuses on CSR submission and certificate retrieval.

Installation

# pip
pip install swarmauri_certs_acme

# poetry
poetry add swarmauri_certs_acme

# uv (pyproject-based projects)
uv add swarmauri_certs_acme

Quickstart

The snippet below submits a CSR to Let's Encrypt using AcmeCertService and persists the resulting PEM chain.

import asyncio
from pathlib import Path

from swarmauri_certs_acme import AcmeCertService
from swarmauri_core.crypto.types import KeyRef


async def main() -> None:
    account_key = KeyRef(material=Path("account-key.pem").read_bytes())

    service = AcmeCertService(
        account_key=account_key,
        contact_emails=["[e-mail]"],
    )

    csr_bytes = Path("server.csr").read_bytes()
    certificate_chain = await service.sign_cert(
        csr=csr_bytes,
        ca_key=account_key,  # required by the CertService interface
    )

    Path("server-fullchain.pem").write_bytes(certificate_chain)
    print("Certificate chain written to server-fullchain.pem")


if __name__ == "__main__":
    asyncio.run(main())

CSR Generation Example

AcmeCertService can construct a CSR when provided with private key material and subject metadata:

import asyncio
from pathlib import Path

from swarmauri_certs_acme import AcmeCertService
from swarmauri_core.crypto.types import KeyRef


async def build_csr() -> None:
    account_key = KeyRef(material=Path("account-key.pem").read_bytes())
    host_key = KeyRef(material=Path("server-key.pem").read_bytes())

    service = AcmeCertService(account_key=account_key)

    csr_bytes = await service.create_csr(
        key=host_key,
        subject={"CN": "example.com"},
        san={"dns": ["example.com", "www.example.com"]},
    )
    Path("server.csr").write_bytes(csr_bytes)


if __name__ == "__main__":
    asyncio.run(build_csr())

Verification and Parsing

Use the built-in helpers to inspect returned certificates before deployment:

import asyncio
from pathlib import Path

from swarmauri_certs_acme import AcmeCertService
from swarmauri_core.crypto.types import KeyRef


async def inspect() -> None:
    account_key = KeyRef(material=Path("account-key.pem").read_bytes())
    service = AcmeCertService(account_key=account_key)

    pem_chain = Path("server-fullchain.pem").read_bytes()

    info = await service.verify_cert(pem_chain)
    print("Issuer:", info["issuer"])
    print("Valid until:", info["not_after"])

    metadata = await service.parse_cert(pem_chain)
    print(metadata)


if __name__ == "__main__":
    asyncio.run(inspect())

Best Practices

• Rotate account keys periodically and store them in a secure vault (KeyRef works with external KMS integrations).
• When using Let's Encrypt production, respect rate limits and consider staging endpoints during development.
• Automate DNS/HTTP challenges upstream; this service assumes the order is ready for finalization once the CSR is submitted.
• Cache successful certificate chains and perform proactive renewals before not_after to avoid downtime.