granny-devops 0.4.0__py3-none-any.whl

granny/email/__init__.py

@@ -0,0 +1,7 @@
+"""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"]

granny/email/mailjet.py

@@ -0,0 +1,119 @@
+"""Mailjet REST API client — sender CRUD, DNS settings, verification.
+
+Lifted from ``tools/create/setup_mailjet_dns.py:MailjetClient``.
+Also includes SPF parsing/merging utilities used during DNS auth setup.
+"""
+
+import logging
+from typing import Any
+
+import requests
+
+from granny.credentials.secrets import get_secret
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://api.mailjet.com/v3/REST"
+
+
+class MailjetClient:
+    """Mailjet REST API v3 client for sender and DNS management."""
+
+    def __init__(self) -> None:
+        api_key = get_secret("MAILJET_API_KEY")
+        secret_key = get_secret("MAILJET_SECRET_KEY")
+        if not api_key or not secret_key:
+            raise ValueError(
+                "MAILJET_API_KEY / MAILJET_SECRET_KEY not set (env or vault)."
+            )
+        self.session = requests.Session()
+        self.session.auth = (api_key, secret_key)
+        self.session.headers.update({"Content-Type": "application/json"})
+
+    def _request(self, method: str, endpoint: str, data: dict | None = None) -> Any:
+        url = f"{API_BASE}{endpoint}"
+        resp = getattr(self.session, method.lower())(url, json=data, timeout=30)
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Mailjet {method} {endpoint}: {resp.status_code} {resp.text}"
+            )
+        return resp.json() if resp.text else {}
+
+    def find_sender(self, domain: str) -> dict | None:
+        """Find a catch-all ``*@domain`` sender."""
+        result = self._request("GET", "/sender")
+        catch_all = f"*@{domain}"
+        for sender in result.get("Data", []):
+            if sender.get("Email", "").lower() == catch_all.lower():
+                return sender
+        return None
+
+    def create_sender(self, domain: str) -> dict:
+        catch_all = f"*@{domain}"
+        result = self._request("POST", "/sender", {"Email": catch_all})
+        sender = result.get("Data", [{}])[0]
+        logger.info("Created Mailjet sender %s (ID %s)", catch_all, sender.get("ID"))
+        return sender
+
+    def get_or_create_sender(self, domain: str) -> dict:
+        sender = self.find_sender(domain)
+        if sender:
+            logger.info("Found existing sender *@%s (ID %s)", domain, sender.get("ID"))
+            return sender
+        return self.create_sender(domain)
+
+    def get_dns_settings(self, domain: str) -> dict:
+        """Retrieve DKIM/SPF/ownership settings from Mailjet API."""
+        result = self._request("GET", f"/dns/{domain}")
+        return result.get("Data", [{}])[0]
+
+    def check_dns(self, dns_id: str) -> dict:
+        """Trigger a Mailjet DNS verification check."""
+        result = self._request("POST", f"/dns/{dns_id}/check", {})
+        return result.get("Data", [{}])[0]
+
+
+# -- SPF utilities (used by setup_mailjet_dns.py and granny email mailjet) -----
+
+
+def parse_spf(spf_record: str) -> tuple[list[str], str]:
+    """Parse an SPF record into (mechanisms, qualifier).
+
+    Returns e.g. (["include:_spf.google.com", "include:spf.mailjet.com"], "~all").
+    """
+    parts = spf_record.strip().split()
+    mechanisms: list[str] = []
+    qualifier = "~all"
+    for part in parts:
+        if part == "v=spf1":
+            continue
+        if part.endswith("all"):
+            qualifier = part
+        else:
+            mechanisms.append(part)
+    return mechanisms, qualifier
+
+
+def merge_spf(
+    existing_spf: str | None,
+    target_qualifier: str = "~all",
+    include: str = "include:spf.mailjet.com",
+) -> tuple[str, list[str]]:
+    """Merge a Mailjet include into an existing SPF record.
+
+    Returns (merged_record, warnings).
+    """
+    warnings: list[str] = []
+    if not existing_spf:
+        return f"v=spf1 {include} {target_qualifier}", warnings
+
+    mechanisms, qualifier = parse_spf(existing_spf)
+
+    if include not in mechanisms:
+        mechanisms.append(include)
+
+    if qualifier == "?all" and target_qualifier in ("~all", "-all"):
+        warnings.append(f"Upgraded SPF qualifier from ?all to {target_qualifier}")
+        qualifier = target_qualifier
+
+    return f"v=spf1 {' '.join(mechanisms)} {qualifier}", warnings

granny/email/mailjet_contacts.py

@@ -0,0 +1,115 @@
+"""Mailjet contact management — check, block, unblock, bounce clearing.
+
+Lifted from ``tools/create/manage_mailjet_contacts.py:MailjetContactClient``.
+"""
+
+import logging
+from typing import Any
+
+import requests
+
+from granny.credentials.secrets import get_secret
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://api.mailjet.com/v3/REST"
+
+
+class MailjetContactClient:
+    """Mailjet REST API client for contact management."""
+
+    def __init__(self) -> None:
+        api_key = get_secret("MAILJET_API_KEY")
+        secret_key = get_secret("MAILJET_SECRET_KEY")
+        if not api_key or not secret_key:
+            raise ValueError(
+                "MAILJET_API_KEY / MAILJET_SECRET_KEY not set (env or vault)."
+            )
+        self.session = requests.Session()
+        self.session.auth = (api_key, secret_key)
+        self.session.headers.update({"Content-Type": "application/json"})
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        data: dict | None = None,
+        params: dict | None = None,
+    ) -> Any:
+        url = f"{API_BASE}{endpoint}"
+        resp = getattr(self.session, method.lower())(
+            url, json=data, params=params, timeout=30
+        )
+        if resp.status_code == 404:
+            return None
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Mailjet {method} {endpoint}: {resp.status_code} {resp.text}"
+            )
+        return resp.json() if resp.text else {}
+
+    def get_contact(self, email: str) -> dict | None:
+        result = self._request("GET", f"/contact/{email}")
+        if not result:
+            return None
+        contacts = result.get("Data", [])
+        return contacts[0] if contacts else None
+
+    def unblock_contact(self, email: str) -> dict:
+        result = self._request(
+            "PUT", f"/contact/{email}", data={"IsExcludedFromCampaigns": "false"}
+        )
+        if not result:
+            raise RuntimeError(f"Contact not found: {email}")
+        return result.get("Data", [{}])[0]
+
+    def block_contact(self, email: str) -> dict:
+        result = self._request(
+            "PUT", f"/contact/{email}", data={"IsExcludedFromCampaigns": "true"}
+        )
+        if not result:
+            raise RuntimeError(f"Contact not found: {email}")
+        return result.get("Data", [{}])[0]
+
+    def list_contacts(
+        self, limit: int = 1000, offset: int = 0, is_excluded: bool | None = None
+    ) -> list[dict]:
+        params: dict[str, Any] = {"Limit": min(limit, 1000), "Offset": offset}
+        if is_excluded is not None:
+            params["IsExcludedFromCampaigns"] = str(is_excluded).lower()
+        result = self._request("GET", "/contact", params=params)
+        return result.get("Data", []) if result else []
+
+    def list_all_excluded(self, domain: str | None = None) -> list[dict]:
+        """Paginate through all excluded contacts."""
+        all_contacts: list[dict] = []
+        offset = 0
+        while True:
+            batch = self.list_contacts(limit=1000, offset=offset, is_excluded=True)
+            if not batch:
+                break
+            if domain:
+                batch = [
+                    c for c in batch if c.get("Email", "").endswith(f"@{domain}")
+                ]
+            all_contacts.extend(batch)
+            if len(batch) < 1000:
+                break
+            offset += 1000
+        return all_contacts
+
+    def get_message_history(self, contact_id: int, limit: int = 10) -> list[dict]:
+        result = self._request(
+            "GET", "/message", params={"Contact": contact_id, "Limit": limit}
+        )
+        return result.get("Data", []) if result else []
+
+    def delete_contact(self, contact_id: int) -> bool:
+        """Delete via v4 API (clears bounce history)."""
+        url = f"https://api.mailjet.com/v4/contacts/{contact_id}"
+        resp = self.session.delete(url, timeout=30)
+        if resp.status_code == 200:
+            return True
+        if resp.status_code == 404:
+            return False
+        raise RuntimeError(f"Mailjet v4 delete: {resp.status_code} {resp.text}")

granny/email/ses_forwarding.py

@@ -0,0 +1,281 @@
+"""SES email forwarding manager — Lambda + IAM + SES receipt rules.
+
+Lifted from ``tools/create/setup_workmail.py:SESForwardingManager``.
+Sets up email forwarding from a WorkMail address to an external address
+using SES receipt rules with a Lambda function.
+"""
+
+import io
+import json
+import logging
+import time
+import zipfile
+
+import boto3
+from botocore.exceptions import ClientError
+
+logger = logging.getLogger(__name__)
+
+
+class SESForwardingManager:
+    """Email forwarding via Amazon SES receipt rules + Lambda."""
+
+    def __init__(self, region: str | None = None) -> None:
+        import os
+
+        region = region or os.environ.get("AWS_REGION", "us-east-1")
+        self.region = region
+        self.ses = boto3.client("ses", region_name=region)
+        self.lam = boto3.client("lambda", region_name=region)
+        self.iam = boto3.client("iam", region_name=region)
+
+    def check_domain_verified(self, domain: str) -> bool:
+        resp = self.ses.list_identities(IdentityType="Domain")
+        return domain in resp.get("Identities", [])
+
+    def get_or_create_rule_set(
+        self, rule_set_name: str = "workmail-forwarding"
+    ) -> str:
+        try:
+            self.ses.describe_receipt_rule_set(RuleSetName=rule_set_name)
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] == "RuleSetDoesNotExist":
+                self.ses.create_receipt_rule_set(RuleSetName=rule_set_name)
+                logger.info("Created SES rule set: %s", rule_set_name)
+            else:
+                raise
+        return rule_set_name
+
+    def find_forwarding_rule(
+        self, rule_set_name: str, email: str
+    ) -> dict | None:
+        try:
+            resp = self.ses.describe_receipt_rule_set(RuleSetName=rule_set_name)
+            rule_name = f"forward-{email.replace('@', '-at-')}"
+            for rule in resp.get("Rules", []):
+                if rule.get("Name") == rule_name:
+                    return rule
+        except ClientError:
+            pass
+        return None
+
+    def setup_forwarding(
+        self,
+        email: str,
+        forward_to: str,
+        rule_set_name: str = "workmail-forwarding",
+        *,
+        dry_run: bool = False,
+    ) -> dict:
+        """Set up SES receipt rule + Lambda forwarder.
+
+        Returns a status dict. The WorkMail mailbox still receives the original.
+        """
+        domain = email.split("@")[1]
+        rule_name = f"forward-{email.replace('@', '-at-')}"
+        lambda_name = f"workmail-forward-{domain.replace('.', '-')}"
+        result = {
+            "email": email,
+            "forward_to": forward_to,
+            "rule_set": rule_set_name,
+            "rule_name": rule_name,
+            "lambda_name": lambda_name,
+        }
+
+        if dry_run:
+            result["status"] = "dry_run"
+            return result
+
+        if not self.check_domain_verified(domain):
+            result["status"] = "domain_not_verified"
+            result["fix"] = f"aws ses verify-domain-identity --domain {domain}"
+            return result
+
+        self.get_or_create_rule_set(rule_set_name)
+
+        existing = self.find_forwarding_rule(rule_set_name, email)
+        if existing:
+            result["status"] = "exists"
+            return result
+
+        lambda_arn = self._get_or_create_lambda(lambda_name, forward_to)
+        result["lambda_arn"] = lambda_arn
+
+        self.ses.create_receipt_rule(
+            RuleSetName=rule_set_name,
+            Rule={
+                "Name": rule_name,
+                "Enabled": True,
+                "Recipients": [email],
+                "Actions": [
+                    {
+                        "LambdaAction": {
+                            "FunctionArn": lambda_arn,
+                            "InvocationType": "Event",
+                        }
+                    }
+                ],
+                "ScanEnabled": True,
+            },
+        )
+        logger.info("Created forwarding rule: %s -> %s", email, forward_to)
+
+        try:
+            self.ses.set_active_receipt_rule_set(RuleSetName=rule_set_name)
+        except ClientError as exc:
+            logger.warning("Could not activate rule set: %s", exc)
+
+        result["status"] = "created"
+        return result
+
+    def _get_or_create_lambda(self, lambda_name: str, forward_to: str) -> str:
+        try:
+            resp = self.lam.get_function(FunctionName=lambda_name)
+            arn = resp["Configuration"]["FunctionArn"]
+            self.lam.update_function_configuration(
+                FunctionName=lambda_name,
+                Environment={
+                    "Variables": {"FORWARD_TO": forward_to, "REGION": self.region}
+                },
+            )
+            return arn
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] != "ResourceNotFoundException":
+                raise
+
+        role_arn = self._get_or_create_role(lambda_name)
+
+        code = _FORWARDER_LAMBDA_CODE.strip()
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            zf.writestr("lambda_function.py", code)
+        buf.seek(0)
+
+        logger.info("Waiting for IAM role propagation...")
+        time.sleep(10)
+
+        resp = self.lam.create_function(
+            FunctionName=lambda_name,
+            Runtime="python3.12",
+            Role=role_arn,
+            Handler="lambda_function.handler",
+            Code={"ZipFile": buf.read()},
+            Description=f"Email forwarder -> {forward_to}",
+            Timeout=30,
+            MemorySize=128,
+            Environment={
+                "Variables": {"FORWARD_TO": forward_to, "REGION": self.region}
+            },
+        )
+        arn = resp["FunctionArn"]
+        logger.info("Created Lambda %s", lambda_name)
+
+        try:
+            self.lam.add_permission(
+                FunctionName=lambda_name,
+                StatementId="AllowSES",
+                Action="lambda:InvokeFunction",
+                Principal="ses.amazonaws.com",
+            )
+        except ClientError:
+            pass
+
+        return arn
+
+    def _get_or_create_role(self, lambda_name: str) -> str:
+        role_name = f"{lambda_name}-role"
+        try:
+            resp = self.iam.get_role(RoleName=role_name)
+            return resp["Role"]["Arn"]
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] != "NoSuchEntity":
+                raise
+
+        assume = json.dumps(
+            {
+                "Version": "2012-10-17",
+                "Statement": [
+                    {
+                        "Effect": "Allow",
+                        "Principal": {"Service": "lambda.amazonaws.com"},
+                        "Action": "sts:AssumeRole",
+                    }
+                ],
+            }
+        )
+        resp = self.iam.create_role(
+            RoleName=role_name,
+            AssumeRolePolicyDocument=assume,
+            Description=f"Role for {lambda_name} forwarder",
+        )
+        role_arn = resp["Role"]["Arn"]
+
+        self.iam.attach_role_policy(
+            RoleName=role_name,
+            PolicyArn="arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole",
+        )
+
+        ses_policy = json.dumps(
+            {
+                "Version": "2012-10-17",
+                "Statement": [
+                    {
+                        "Effect": "Allow",
+                        "Action": ["ses:SendEmail", "ses:SendRawEmail"],
+                        "Resource": "*",
+                    }
+                ],
+            }
+        )
+        self.iam.put_role_policy(
+            RoleName=role_name,
+            PolicyName="SESForwardingPolicy",
+            PolicyDocument=ses_policy,
+        )
+        return role_arn
+
+
+_FORWARDER_LAMBDA_CODE = '''
+import boto3
+import os
+
+FORWARD_TO = os.environ.get('FORWARD_TO', '')
+REGION = os.environ.get('REGION', 'us-east-1')
+
+
+def handler(event, context):
+    ses_client = boto3.client('ses', region_name=REGION)
+    for record in event.get('Records', []):
+        ses_message = record.get('ses', {})
+        mail = ses_message.get('mail', {})
+        message_id = mail.get('messageId', '')
+        if not message_id or not FORWARD_TO:
+            continue
+        source = mail.get('source', 'noreply@example.com')
+        destinations = [addr.strip() for addr in FORWARD_TO.split(',')]
+        common_headers = mail.get('commonHeaders', {})
+        subject = common_headers.get('subject', 'Forwarded Email')
+        from_addr = common_headers.get('from', [source])[0]
+        try:
+            ses_client.send_email(
+                Source=source,
+                Destination={'ToAddresses': destinations},
+                Message={
+                    'Subject': {'Data': f"[FWD] {subject}"},
+                    'Body': {
+                        'Text': {
+                            'Data': (
+                                f"Forwarded email from: {from_addr}\\n"
+                                f"Original recipient: {', '.join(mail.get('destination', []))}\\n"
+                                f"Subject: {subject}\\n"
+                                f"Date: {common_headers.get('date', 'Unknown')}\\n"
+                                f"\\n--- Forwarded by WorkMail Forwarder ---"
+                            )
+                        }
+                    }
+                }
+            )
+        except Exception as e:
+            print(f"Failed to forward {message_id}: {e}")
+    return {'disposition': 'CONTINUE'}
+'''

granny/email/workmail.py

@@ -0,0 +1,145 @@
+"""AWS WorkMail user management — org/user CRUD, password reset.
+
+Lifted from ``tools/create/setup_workmail.py:WorkMailManager``.
+"""
+
+import logging
+from typing import Any
+
+import boto3
+
+logger = logging.getLogger(__name__)
+
+WORKMAIL_REGIONS = {
+    "us-east-1": "N. Virginia",
+    "us-west-2": "Oregon",
+    "eu-west-1": "Ireland",
+}
+
+
+class WorkMailManager:
+    """Amazon WorkMail organization and user management."""
+
+    def __init__(self, region: str | None = None) -> None:
+        import os
+
+        region = region or os.environ.get("AWS_REGION", "us-east-1")
+        if region not in WORKMAIL_REGIONS:
+            raise ValueError(
+                f"WorkMail not available in {region!r}. "
+                f"Choices: {', '.join(WORKMAIL_REGIONS)}"
+            )
+        self.region = region
+        self.client = boto3.client("workmail", region_name=region)
+        self._org_cache: dict[str, dict] = {}
+
+    def list_organizations(self) -> list[dict]:
+        orgs: list[dict] = []
+        paginator = self.client.get_paginator("list_organizations")
+        for page in paginator.paginate():
+            orgs.extend(page.get("OrganizationSummaries", []))
+        return orgs
+
+    def find_organization(self, domain: str) -> dict | None:
+        if domain in self._org_cache:
+            return self._org_cache[domain]
+        for org in self.list_organizations():
+            if org.get("State") != "Active":
+                continue
+            if org.get("DefaultMailDomain") == domain or org.get("Alias") == domain:
+                self._org_cache[domain] = org
+                return org
+        return None
+
+    def get_org_id(self, domain: str) -> str:
+        org = self.find_organization(domain)
+        if not org:
+            available = [
+                o.get("DefaultMailDomain", o.get("Alias", "?"))
+                for o in self.list_organizations()
+            ]
+            raise RuntimeError(
+                f"WorkMail org not found for {domain!r}. Available: {available}"
+            )
+        return org["OrganizationId"]
+
+    def list_users(self, org_id: str) -> list[dict]:
+        users: list[dict] = []
+        paginator = self.client.get_paginator("list_users")
+        for page in paginator.paginate(OrganizationId=org_id):
+            users.extend(page.get("Users", []))
+        return users
+
+    def find_user_by_email(self, org_id: str, email: str) -> dict | None:
+        for user in self.list_users(org_id):
+            if user.get("Email", "").lower() == email.lower():
+                return user
+        return None
+
+    def describe_user(self, org_id: str, user_id: str) -> dict:
+        return self.client.describe_user(OrganizationId=org_id, UserId=user_id)
+
+    def create_user(
+        self,
+        org_id: str,
+        username: str,
+        display_name: str,
+        password: str,
+        *,
+        first_name: str | None = None,
+        last_name: str | None = None,
+    ) -> str:
+        """Create a user. Returns user ID."""
+        params: dict[str, Any] = {
+            "OrganizationId": org_id,
+            "Name": username,
+            "DisplayName": display_name,
+            "Password": password,
+        }
+        if first_name:
+            params["FirstName"] = first_name
+        if last_name:
+            params["LastName"] = last_name
+        resp = self.client.create_user(**params)
+        user_id = resp["UserId"]
+        logger.info("Created user %s (ID %s)", username, user_id)
+        return user_id
+
+    def register_to_workmail(self, org_id: str, user_id: str, email: str) -> None:
+        self.client.register_to_work_mail(
+            OrganizationId=org_id, EntityId=user_id, Email=email
+        )
+        logger.info("Registered %s for WorkMail", email)
+
+    def reset_password(self, org_id: str, user_id: str, password: str) -> None:
+        self.client.reset_password(
+            OrganizationId=org_id, UserId=user_id, Password=password
+        )
+        logger.info("Password reset for user %s", user_id)
+
+    def create_and_register_user(
+        self,
+        org_id: str,
+        email: str,
+        display_name: str,
+        password: str,
+        *,
+        first_name: str | None = None,
+        last_name: str | None = None,
+    ) -> str:
+        """Create + register (2-step). Returns user ID. Idempotent."""
+        existing = self.find_user_by_email(org_id, email)
+        if existing:
+            logger.info("User %s already exists (ID %s)", email, existing["Id"])
+            return existing["Id"]
+        username = email.split("@")[0]
+        user_id = self.create_user(
+            org_id,
+            username,
+            display_name,
+            password,
+            first_name=first_name,
+            last_name=last_name,
+        )
+        self.register_to_workmail(org_id, user_id, email)
+        return user_id