granny-devops 0.13.0__tar.gz → 0.14.0__tar.gz

{granny_devops-0.13.0 → granny_devops-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granny-devops
-Version: 0.13.0
+Version: 0.14.0
 Summary: Cloud tools collection -- AWS infrastructure, CDN, and DevOps automation
 Author-email: Martin Wieser <martin.wieser@pseekoo.com>
 License: MIT License

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/__init__.py

@@ -1,19 +1,19 @@
-"""Granny -- Cloud tools collection for AWS infrastructure and DevOps automation."""
-
-__version__ = "0.13.0"
-__all__ = [
-    "get_secret",
-    "load_secrets_into_env",
-]
-
-
-def __getattr__(name: str):
-    if name == "get_secret":
-        from granny.credentials.secrets import get_secret
-
-        return get_secret
-    if name == "load_secrets_into_env":
-        from granny.credentials.secrets import load_secrets_into_env
-
-        return load_secrets_into_env
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+"""Granny -- Cloud tools collection for AWS infrastructure and DevOps automation."""
+
+__version__ = "0.14.0"
+__all__ = [
+    "get_secret",
+    "load_secrets_into_env",
+]
+
+
+def __getattr__(name: str):
+    if name == "get_secret":
+        from granny.credentials.secrets import get_secret
+
+        return get_secret
+    if name == "load_secrets_into_env":
+        from granny.credentials.secrets import load_secrets_into_env
+
+        return load_secrets_into_env
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/cli/dns.py

@@ -43,16 +43,19 @@ def _split_fqdn(value: str, domain: str | None) -> tuple[str, str]:
 
     if "." in value:
         value_lower = value.lower()
-        if domain and value_lower != domain and not value_lower.endswith(f".{domain}"):
-            raise click.UsageError(
-                f"{value!r} is not under domain {domain!r}"
-            )
         if domain is None:
             return ("@", value_lower)
         if value_lower == domain:
             return ("@", domain)
-        short = value_lower[: -(len(domain) + 1)]
-        return (short, domain)
+        if value_lower.endswith(f".{domain}"):
+            short = value_lower[: -(len(domain) + 1)]
+            return (short, domain)
+        # A dotted name that's neither the zone apex nor a FQDN under it.
+        # With an explicit --domain this is a multi-label *relative* subname
+        # (e.g. ``_smtp._tls`` or ``v1-rsa-20260629._domainkey``), so treat it
+        # as relative to the zone rather than rejecting it. The resulting FQDN
+        # is echoed back, so a genuine wrong-domain typo stays visible.
+        return (value_lower, domain)
 
     # Bare label — needs a domain.
     if not domain:

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/cli/email.py

@@ -330,3 +330,122 @@ def workmail_reset_password(
         raise click.ClickException(f"User not found: {user_email}")
     wm.reset_password(org_id, user["Id"], password)
     click.echo(f"Password reset for {user_email}.")
+
+
+# -- Stalwart subgroup --------------------------------------------------------
+
+
+@email.group("stalwart")
+def stalwart() -> None:
+    """Stalwart mail server admin (domains, mailboxes, DNS, delivery test)."""
+
+
+@stalwart.command("list-domains")
+def stalwart_list_domains() -> None:
+    """List configured local domains."""
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    domains = c.list_domains()
+    if not domains:
+        click.echo("No domains configured.")
+        return
+    for d in domains:
+        dkim = (d.get("dkimManagement") or {}).get("@type", "?")
+        click.echo(
+            f"  {d.get('id', '?'):<5} {d.get('name', '?'):<30} "
+            f"enabled={d.get('isEnabled')}  dkim={dkim}"
+        )
+
+
+@stalwart.command("add-domain")
+@click.argument("name")
+def stalwart_add_domain(name: str) -> None:
+    """Create a new local domain (Manual cert, Automatic DKIM, Manual DNS)."""
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    created = c.add_domain(name)
+    click.echo(f"Domain {name} ready (id={created.get('id')})")
+    click.echo(f"Next: granny email stalwart show-dns {name}")
+
+
+@stalwart.command("list-mailboxes")
+def stalwart_list_mailboxes() -> None:
+    """List individual mailboxes."""
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    mailboxes = c.list_mailboxes()
+    if not mailboxes:
+        click.echo("No mailboxes configured.")
+        return
+    for a in mailboxes:
+        role = (a.get("roles") or {}).get("@type", "?")
+        click.echo(
+            f"  {a.get('id', '?'):<5} {a.get('emailAddress', '?'):<40} role={role}"
+        )
+
+
+@stalwart.command("add-mailbox")
+@click.argument("email_address")
+@click.option("--description", default=None, help="Free-text mailbox description.")
+@click.option(
+    "--password",
+    default=None,
+    help="Use this password instead of generating one (NOT recommended).",
+)
+def stalwart_add_mailbox(
+    email_address: str, description: str | None, password: str | None,
+) -> None:
+    """Create a mailbox under an existing local domain.
+
+    The generated password is shown ONCE on stdout. Save it immediately
+    (e.g. into Vaultwarden) — Stalwart hashes it server-side.
+    """
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    record, generated = c.add_mailbox(
+        email_address, password=password, description=description,
+    )
+    click.echo(f"Mailbox created (id={record.get('id')})")
+    click.echo("")
+    click.echo(f"  Email:    {email_address}")
+    click.echo(f"  Password: {generated}")
+    click.echo("")
+    base = c.base_url.removeprefix("https://").removeprefix("http://")
+    click.echo(f"  SMTP submission: {base}:587 (STARTTLS) or :465 (implicit TLS)")
+    click.echo(f"  IMAP:            {base}:993")
+    click.echo(f"  JMAP / WebDAV:   {c.base_url}/")
+    click.echo("")
+    click.echo("  This password is shown ONCE — save it now.")
+
+
+@stalwart.command("show-dns")
+@click.argument("name")
+def stalwart_show_dns(name: str) -> None:
+    """Print Stalwart's generated DNS zone for a domain.
+
+    Output is in BIND zone-file syntax (SPF, MX, DKIM, DMARC, MTA-STS,
+    TLS-RPT, SRV autoconfig). Publish at the domain's registrar.
+    """
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    click.echo(c.get_dns_zone(name))
+
+
+@stalwart.command("delivery-test")
+@click.argument("recipient")
+def stalwart_delivery_test(recipient: str) -> None:
+    """Stream Stalwart's live deliverability report for one recipient.
+
+    Mirrors the admin UI's *Live Delivery Test* page (MX lookup,
+    MTA-STS, TLS-RPT, banner, STARTTLS, etc.).
+    """
+    from granny.email.stalwart import StalwartClient
+
+    c = StalwartClient.from_environment()
+    for line in c.stream_delivery_test(recipient):
+        click.echo(line)

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/credentials/secrets.py

@@ -182,6 +182,12 @@ SECRET_MAP: dict[str, str] = {
     "ELASTICSEARCH_API_KEY": "elasticsearch-api-key",
     "ELASTICSEARCH_USERNAME": "elasticsearch-username",
     "ELASTICSEARCH_PASSWORD": "elasticsearch-password",
+    # Stalwart mail server admin (Basic auth on JMAP / REST). The username is
+    # not secret but is registered alongside the password so both can come from
+    # the same vault item. Base URL defaults to https://mail.pseekoo.io in
+    # StalwartClient.from_environment() and is overridable via STALWART_URL.
+    "STALWART_ADMIN_USER": "stalwart-admin-user",
+    "STALWART_ADMIN_PASSWORD": "stalwart-admin-password",
 }
 
 # Module-level cache so vault is only contacted once per process

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/dns/bunny.py

@@ -107,7 +107,7 @@ class BunnyDNSProvider(DNSProvider):
                 DNSRecord(
                     name=rec.get("Name", "") or "",
                     type=RECORD_TYPE_NAMES.get(rec.get("Type", -1), "?"),
-                    value=rec.get("Value", ""),
+                    value=self._record_value(rec),
                     ttl=int(rec.get("Ttl", 300)),
                     id=str(rec.get("Id")),
                     provider_data=rec,
@@ -124,27 +124,79 @@ class BunnyDNSProvider(DNSProvider):
         ttl: int = 300,
         proxied: bool = False,
     ) -> DNSRecord:
-        type_num = RECORD_TYPES.get(record_type.upper())
+        rtype = record_type.upper()
+        type_num = RECORD_TYPES.get(rtype)
         if type_num is None:
             raise ValueError(f"Unknown record type: {record_type}")
         short_name = "" if name in ("@", None) else name
+        record_value = value.rstrip(".") if rtype == "CNAME" else value
+        priority: int | None = None
+        extra: dict[str, int] = {}
+        if rtype == "MX":
+            # BIND-style "10 mail.example.com" → Priority + target.
+            head, _, tail = value.strip().partition(" ")
+            if head.isdigit() and tail:
+                priority = int(head)
+                record_value = tail.rstrip(".")
+        elif rtype == "SRV":
+            # BIND-style "priority weight port target" → Bunny's separate
+            # Priority/Weight/Port fields plus Value=target.
+            parts = value.split()
+            if len(parts) != 4:
+                raise ValueError(
+                    f"SRV value must be 'priority weight port target', got {value!r}"
+                )
+            prio, weight, port, target = parts
+            priority = int(prio)
+            extra = {"Weight": int(weight), "Port": int(port)}
+            record_value = target.rstrip(".")
         payload = {
             "Type": type_num,
             "Name": short_name,
-            "Value": value.rstrip(".") if record_type.upper() == "CNAME" else value,
+            "Value": record_value,
             "Ttl": ttl,
         }
+        if priority is not None:
+            payload["Priority"] = priority
+        payload.update(extra)
         result = self._request("PUT", f"/dnszone/{zone_id}/records", payload)
         logger.info("Bunny DNS: created %s %s -> %s", record_type, short_name, value)
+        # Build the display value from what we sent — Bunny's create response
+        # doesn't reliably echo Priority/Weight/Port back.
+        if rtype == "MX" and priority is not None:
+            display_value = f"{priority} {record_value}"
+        elif rtype == "SRV":
+            display_value = f"{priority} {extra['Weight']} {extra['Port']} {record_value}"
+        else:
+            display_value = record_value
         return DNSRecord(
             name=short_name,
-            type=record_type.upper(),
-            value=payload["Value"],
+            type=rtype,
+            value=display_value,
             ttl=ttl,
             id=str(result.get("Id")) if isinstance(result, dict) else None,
             provider_data=result if isinstance(result, dict) else {},
         )
 
+    @staticmethod
+    def _record_value(rec: dict) -> str:
+        """Reconstruct a BIND-style value from a Bunny record.
+
+        MX prepends ``Priority``; SRV expands to ``priority weight port
+        target``. Keeps round-tripped values in the same shape callers pass,
+        so ``upsert_record`` compares equal and stays idempotent.
+        """
+        value = rec.get("Value", "") or ""
+        rtype = rec.get("Type")
+        if rtype == RECORD_TYPES["MX"]:
+            return f"{rec.get('Priority', 0)} {value}".strip()
+        if rtype == RECORD_TYPES["SRV"]:
+            return (
+                f"{rec.get('Priority', 0)} {rec.get('Weight', 0)} "
+                f"{rec.get('Port', 0)} {value}"
+            )
+        return value
+
     def delete_record(self, zone_id: str, record_id: str) -> None:
         self._request("DELETE", f"/dnszone/{zone_id}/records/{record_id}")
         logger.info("Bunny DNS: deleted record %s", record_id)

{granny_devops-0.13.0 → granny_devops-0.14.0}/granny/dns/cloudflare.py

@@ -101,7 +101,7 @@ class CloudflareDNSProvider(DNSProvider):
                 DNSRecord(
                     name=rec.get("name", ""),
                     type=rec.get("type", ""),
-                    value=rec.get("content", ""),
+                    value=self._record_value(rec),
                     ttl=int(rec.get("ttl", 300)),
                     id=rec.get("id"),
                     fqdn=rec.get("name"),
@@ -110,6 +110,61 @@ class CloudflareDNSProvider(DNSProvider):
             )
         return out
 
+    @staticmethod
+    def _record_value(rec: dict) -> str:
+        """Reconstruct a BIND-style value string from a Cloudflare record.
+
+        MX prepends its ``priority``; SRV expands its ``data`` object to
+        ``priority weight port target``. Everything else uses ``content``.
+        Keeping the round-tripped value in this shape lets ``upsert_record``
+        compare against the value callers pass and stay idempotent.
+        """
+        rtype = rec.get("type", "")
+        content = rec.get("content", "") or ""
+        if rtype == "MX" and rec.get("priority") is not None:
+            return f"{rec['priority']} {content}".strip()
+        if rtype == "SRV":
+            data = rec.get("data") or {}
+            if data:
+                return (
+                    f"{data.get('priority', 0)} {data.get('weight', 0)} "
+                    f"{data.get('port', 0)} {str(data.get('target', '')).rstrip('.')}"
+                )
+        return content
+
+    @staticmethod
+    def _type_payload(record_type: str, value: str) -> dict:
+        """Build the type-specific Cloudflare payload fields.
+
+        MX and SRV can't be expressed with a bare ``content`` string —
+        Cloudflare requires a separate ``priority`` (MX) or a structured
+        ``data`` object (SRV). Both accept the BIND-style value granny passes
+        around: ``"10 mail.example.com"`` for MX and
+        ``"0 1 443 mail.example.com"`` (priority weight port target) for SRV.
+        A bare MX target defaults to priority 10.
+        """
+        rtype = record_type.upper()
+        parts = value.split()
+        if rtype == "MX":
+            if len(parts) == 2 and parts[0].isdigit():
+                return {"content": parts[1].rstrip("."), "priority": int(parts[0])}
+            return {"content": value.rstrip("."), "priority": 10}
+        if rtype == "SRV":
+            if len(parts) != 4:
+                raise ValueError(
+                    f"SRV value must be 'priority weight port target', got {value!r}"
+                )
+            prio, weight, port, target = parts
+            return {
+                "data": {
+                    "priority": int(prio),
+                    "weight": int(weight),
+                    "port": int(port),
+                    "target": target.rstrip("."),
+                }
+            }
+        return {"content": value}
+
     def get_record(
         self, zone_id: str, name: str, record_type: str
     ) -> DNSRecord | None:
@@ -134,20 +189,22 @@ class CloudflareDNSProvider(DNSProvider):
         payload = {
             "type": record_type.upper(),
             "name": fqdn,
-            "content": value,
             # Cloudflare uses ttl=1 as the sentinel for "automatic". Anything
             # else must be >= 60. Match manage-dns.sh's behavior: if caller
             # passes ttl<=1, use automatic; otherwise send the value.
             "ttl": 1 if ttl <= 1 else ttl,
             "proxied": proxied,
         }
+        # MX needs a separate `priority`, SRV a structured `data` object;
+        # everything else is a plain `content` string.
+        payload.update(self._type_payload(record_type, value))
         body = self._request("POST", f"/zones/{zone_id}/dns_records", json=payload)
         rec = body.get("result") or {}
         logger.info("Cloudflare: created %s %s -> %s", record_type, fqdn, value)
         return DNSRecord(
             name=rec.get("name", fqdn),
             type=rec.get("type", record_type.upper()),
-            value=rec.get("content", value),
+            value=self._record_value(rec) or value,
             ttl=int(rec.get("ttl", ttl)),
             id=rec.get("id"),
             fqdn=rec.get("name", fqdn),
@@ -168,10 +225,10 @@ class CloudflareDNSProvider(DNSProvider):
         payload = {
             "type": record_type.upper(),
             "name": fqdn,
-            "content": value,
             "ttl": 1 if ttl <= 1 else ttl,
             "proxied": proxied,
         }
+        payload.update(self._type_payload(record_type, value))
         body = self._request(
             "PUT", f"/zones/{zone_id}/dns_records/{record_id}", json=payload
         )
@@ -180,7 +237,7 @@ class CloudflareDNSProvider(DNSProvider):
         return DNSRecord(
             name=rec.get("name", fqdn),
             type=rec.get("type", record_type.upper()),
-            value=rec.get("content", value),
+            value=self._record_value(rec) or value,
             ttl=int(rec.get("ttl", ttl)),
             id=rec.get("id", record_id),
             fqdn=rec.get("name", fqdn),

granny_devops-0.14.0/granny/email/__init__.py

@@ -0,0 +1,14 @@
+"""Email management — Mailjet, AWS WorkMail, Stalwart."""
+
+from granny.email.mailjet import MailjetClient
+from granny.email.mailjet_contacts import MailjetContactClient
+from granny.email.stalwart import StalwartClient, StalwartError
+from granny.email.workmail import WorkMailManager
+
+__all__ = [
+    "MailjetClient",
+    "MailjetContactClient",
+    "StalwartClient",
+    "StalwartError",
+    "WorkMailManager",
+]

granny_devops-0.14.0/granny/email/stalwart.py

@@ -0,0 +1,322 @@
+"""Stalwart mail server admin client.
+
+Wraps Stalwart's JMAP management endpoint (POST ``/jmap``) and the small
+REST surface granny needs. The web admin UI uses the
+``urn:stalwart:jmap`` capability with ``x:Domain/*`` and ``x:Account/*``
+methods; there is no REST equivalent for domain/mailbox CRUD, so we use
+the same JMAP calls.
+
+Auth is HTTP Basic with the recovery (or post-bootstrap) admin
+credentials. URLs and credentials resolve via the standard granny
+env-var + Vaultwarden pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets as _secrets
+import string
+from collections.abc import Iterator
+from typing import Any
+
+import requests
+
+from granny.credentials import get_secret
+
+logger = logging.getLogger(__name__)
+
+# Stalwart's web admin uses a fixed accountId "d333333" for all domain /
+# account management calls. It identifies the directory-management
+# principal, not a user account.
+_DIRECTORY_ACCOUNT_ID = "d333333"
+
+_JMAP_CAPS = ["urn:ietf:params:jmap:core", "urn:stalwart:jmap"]
+
+
+class StalwartError(RuntimeError):
+    """Raised on non-2xx responses from Stalwart or JMAP-level errors."""
+
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"HTTP {status}: {body[:400]}")
+        self.status = status
+        self.body = body
+
+
+class StalwartClient:
+    """Authenticated client for Stalwart's JMAP management API.
+
+    Construct directly when you already have the credentials, or use
+    :meth:`from_environment` to resolve them via granny's normal env /
+    vault pipeline.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        user: str,
+        password: str,
+        *,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.auth = (user, password)
+        self._session.headers.update({"Accept": "application/json"})
+
+    @classmethod
+    def from_environment(cls) -> "StalwartClient":
+        """Build a client from env vars + Vaultwarden fallback.
+
+        Resolution:
+
+        - ``STALWART_URL`` (env only; default ``https://mail.pseekoo.io``)
+        - ``STALWART_ADMIN_USER`` and ``STALWART_ADMIN_PASSWORD`` via the
+          normal :func:`granny.credentials.get_secret` chain (env wins,
+          Vaultwarden under ``granny/infra/stalwart-admin-*`` as fallback).
+        """
+        base_url = os.environ.get("STALWART_URL") or "https://mail.pseekoo.io"
+        user = get_secret("STALWART_ADMIN_USER")
+        password = get_secret("STALWART_ADMIN_PASSWORD")
+        if not user or not password:
+            raise StalwartError(
+                0,
+                "STALWART_ADMIN_USER / STALWART_ADMIN_PASSWORD not set "
+                "(env or vault). Set them in .env / .deploy.env, or push "
+                "them to Vaultwarden at granny/infra/stalwart-admin-user "
+                "and granny/infra/stalwart-admin-password.",
+            )
+        return cls(base_url=base_url, user=user, password=password)
+
+    # -- HTTP plumbing --------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+    ) -> Any:
+        if not path.startswith("/"):
+            path = "/" + path
+        url = self.base_url + path
+        resp = self._session.request(
+            method=method.upper(), url=url, json=json, timeout=self._timeout,
+        )
+        if resp.status_code >= 400:
+            raise StalwartError(resp.status_code, resp.text)
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+    def _jmap(self, method: str, args: dict[str, Any]) -> dict[str, Any]:
+        """Execute one JMAP method call and return its response args.
+
+        ``method`` is e.g. ``"x:Domain/get"`` or ``"x:Account/set"``;
+        ``args`` is the per-method argument dict. The accountId is filled
+        in automatically.
+        """
+        body = {
+            "using": _JMAP_CAPS,
+            "methodCalls": [[method, {"accountId": _DIRECTORY_ACCOUNT_ID, **args}, "a"]],
+        }
+        resp = self._request("POST", "/jmap", json=body)
+        if not resp or "methodResponses" not in resp:
+            raise StalwartError(0, f"unexpected JMAP response: {resp!r}")
+        mc = resp["methodResponses"][0]
+        # JMAP-level errors come back as ["error", {type: ..., description: ...}, "a"]
+        if mc[0] == "error":
+            err = mc[1] or {}
+            desc = err.get("description") or err.get("type") or "JMAP error"
+            raise StalwartError(0, f"{method}: {desc}")
+        return mc[1] or {}
+
+    # -- Domains --------------------------------------------------------------
+
+    def list_domains(self) -> list[dict[str, Any]]:
+        """Return all configured local domains."""
+        out = self._jmap("x:Domain/get", {})
+        return list(out.get("list") or [])
+
+    def get_domain(self, name: str) -> dict[str, Any] | None:
+        """Find a domain by its DNS name (e.g. ``"m3rp.ai"``)."""
+        for d in self.list_domains():
+            if d.get("name") == name:
+                return d
+        return None
+
+    def add_domain(
+        self,
+        name: str,
+        *,
+        certificate: str = "manual",
+        dkim_algorithms: tuple[str, ...] = ("Dkim1RsaSha256", "Dkim1Ed25519Sha256"),
+        dkim_rotate_after_ms: int = 7_776_000_000,
+        dkim_retire_after_ms: int = 604_800_000,
+        dkim_delete_after_ms: int = 2_592_000_000,
+        dkim_selector_template: str = "v{version}-{algorithm}-{date-%Y%m%d}",
+        dns_management: str = "manual",
+        allow_relaying: bool = False,
+        report_address_uri: str = "mailto:postmaster",
+    ) -> dict[str, Any]:
+        """Create a new local domain.
+
+        Mirrors the production setup (Manual cert because the MX host
+        already has a Let's Encrypt cert via Caddy, Automatic DKIM
+        rotation, Manual DNS because records are published at the
+        domain's registrar).
+        """
+        existing = self.get_domain(name)
+        if existing is not None:
+            logger.info("Domain %s already exists (id=%s)", name, existing["id"])
+            return existing
+
+        dkim = {
+            "@type": "Automatic",
+            "algorithms": {algo: True for algo in dkim_algorithms},
+            "selectorTemplate": dkim_selector_template,
+            "rotateAfter": dkim_rotate_after_ms,
+            "retireAfter": dkim_retire_after_ms,
+            "deleteAfter": dkim_delete_after_ms,
+        }
+        record = {
+            "name": name,
+            "isEnabled": True,
+            "certificateManagement": {"@type": certificate.capitalize()},
+            "dkimManagement": dkim,
+            "dnsManagement": {"@type": dns_management.capitalize()},
+            "subAddressing": {"@type": "Enabled"},
+            "allowRelaying": allow_relaying,
+            "reportAddressUri": report_address_uri,
+        }
+        out = self._jmap("x:Domain/set", {"create": {"new": record}})
+        not_created = out.get("notCreated") or {}
+        if not_created:
+            raise StalwartError(0, f"Domain/set notCreated: {not_created!r}")
+        created = (out.get("created") or {}).get("new") or {}
+        if not created:
+            raise StalwartError(0, f"Domain/set returned no created entry: {out!r}")
+        return created
+
+    def get_dns_zone(self, name: str) -> str:
+        """Return Stalwart's generated DNS zone file for a domain.
+
+        Includes SPF, MX, DKIM (one per active key), DMARC, MTA-STS,
+        TLS-RPT, and the autoconfig/SRV records.
+        """
+        dom = self.get_domain(name)
+        if dom is None:
+            raise StalwartError(0, f"Domain not found: {name}")
+        zone = dom.get("dnsZoneFile")
+        if zone is None:
+            raise StalwartError(0, f"Domain {name} has no dnsZoneFile field")
+        return zone
+
+    # -- Mailboxes (accounts) -------------------------------------------------
+
+    def list_mailboxes(self) -> list[dict[str, Any]]:
+        """Return all individual user / mailbox accounts."""
+        out = self._jmap("x:Account/get", {})
+        return list(out.get("list") or [])
+
+    def get_mailbox(self, email: str) -> dict[str, Any] | None:
+        """Find a mailbox by its primary email address."""
+        for a in self.list_mailboxes():
+            if a.get("emailAddress") == email:
+                return a
+        return None
+
+    def add_mailbox(
+        self,
+        email: str,
+        *,
+        password: str | None = None,
+        description: str | None = None,
+        encryption_at_rest: bool = False,
+    ) -> tuple[dict[str, Any], str]:
+        """Create a mailbox under an existing local domain.
+
+        Returns ``(record, password)`` so the caller can show the
+        generated password to the operator. When ``password`` is None,
+        a 24-character random password is generated.
+        """
+        if "@" not in email:
+            raise ValueError("email must be 'local@domain' form")
+        local_part, domain = email.split("@", 1)
+        dom = self.get_domain(domain)
+        if dom is None:
+            raise StalwartError(
+                0,
+                f"Domain '{domain}' is not configured in Stalwart. "
+                f"Add it first with add_domain('{domain}').",
+            )
+        if password is None:
+            password = _generate_password()
+
+        record = {
+            "name": local_part,
+            "domainId": dom["id"],
+            "@type": "User",
+            "description": description or f"Mailbox {email}",
+            "roles": {"@type": "User"},
+            "permissions": {"@type": "Inherit"},
+            "encryptionAtRest": {
+                "@type": "Enabled" if encryption_at_rest else "Disabled",
+            },
+            "credentials": {"0": {"@type": "Password", "secret": password}},
+        }
+        out = self._jmap("x:Account/set", {"create": {"new": record}})
+        not_created = out.get("notCreated") or {}
+        if not_created:
+            raise StalwartError(0, f"Account/set notCreated: {not_created!r}")
+        created = (out.get("created") or {}).get("new") or {}
+        if not created:
+            raise StalwartError(0, f"Account/set returned no created entry: {out!r}")
+        return created, password
+
+    # -- Delivery / health ----------------------------------------------------
+
+    def get_delivery_token(self) -> str:
+        """Mint a short-lived token for the live delivery test SSE stream."""
+        resp = self._request("GET", "/api/token/delivery")
+        if not isinstance(resp, str) or not resp.strip():
+            raise StalwartError(0, f"unexpected delivery token response: {resp!r}")
+        return resp.strip()
+
+    def stream_delivery_test(self, recipient: str) -> Iterator[str]:
+        """Yield raw SSE lines from Stalwart's live delivery test.
+
+        Mirrors the admin UI's *Live Delivery Test* page (MX lookup,
+        MTA-STS, TLS-RPT, banner, STARTTLS, etc.). Useful from CLI
+        because the browser EventSource flow returns 401 on this build.
+        """
+        token = self.get_delivery_token()
+        url = f"{self.base_url}/api/live/delivery/{recipient}?token={token}"
+        with self._session.get(
+            url,
+            headers={"Accept": "text/event-stream"},
+            stream=True,
+            timeout=self._timeout,
+        ) as resp:
+            if resp.status_code >= 400:
+                raise StalwartError(resp.status_code, resp.text)
+            for line in resp.iter_lines(decode_unicode=True):
+                if line is not None:
+                    yield line
+
+
+# -- helpers ------------------------------------------------------------------
+
+
+def _generate_password(length: int = 24) -> str:
+    """Generate an URL-safe random password without padding characters.
+
+    Matches the strength of ``openssl rand -base64 24`` and strips the
+    same noisy characters (``/+=``) as the bash helper.
+    """
+    alphabet = string.ascii_letters + string.digits
+    return "".join(_secrets.choice(alphabet) for _ in range(length))

{granny_devops-0.13.0 → granny_devops-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "granny-devops"
-version = "0.13.0"
+version = "0.14.0"
 description = "Cloud tools collection -- AWS infrastructure, CDN, and DevOps automation"
 readme = "README.md"
 license = { file = "LICENSE" }

granny_devops-0.13.0/granny/email/__init__.py

@@ -1,7 +0,0 @@
-"""Email management — Mailjet + AWS WorkMail."""
-
-from granny.email.mailjet import MailjetClient
-from granny.email.mailjet_contacts import MailjetContactClient
-from granny.email.workmail import WorkMailManager
-
-__all__ = ["MailjetClient", "MailjetContactClient", "WorkMailManager"]