spf53 0.1.0__py3-none-any.whl

spf53/__init__.py

@@ -0,0 +1,3 @@
+"""spf53 — self-hosted SPF flattener for Route53."""
+
+__version__ = "0.1.0"

spf53/chunker.py

@@ -0,0 +1,151 @@
+"""Pack flattened SPF mechanisms into chained ``_spf53-N.<domain>`` TXT records.
+
+Split convention (RFC 7208 3.3): a DNS TXT record's character-strings are
+concatenated by resolvers with NO separator between them, so a multi-string
+record must carry its own separating space. When a record's content needs a
+second string, the split always falls exactly between two mechanisms (never
+mid-token): the first string carries no trailing space, and the second
+string carries a single LEADING space. Concatenating the two strings then
+reproduces the original "mech1 mech2 ..." content byte-for-byte.
+"""
+
+from collections.abc import Sequence
+from ipaddress import IPv4Network, IPv6Network
+
+MAX_TXT_STRING = 255
+MAX_STRINGS_PER_RECORD = 2
+DNS_QUERYING_MECHANISMS = ("include:", "exists:", "a", "mx", "ptr")
+
+_MAX_RECORD_CHARS = MAX_TXT_STRING * MAX_STRINGS_PER_RECORD
+
+
+def build_records(
+    domain: str,
+    networks: Sequence[IPv4Network | IPv6Network],
+    passthrough: Sequence[str],
+    policy: str,
+) -> dict[str, list[str]]:
+    """Pack passthrough mechanisms and networks into chained TXT records.
+
+    Chunk 1 carries passthrough mechanisms first, then ip4:, then ip6:
+    mechanisms. Every chunk but the last ends with an ``include:`` link to
+    the next chunk; the last ends with ``policy``. Room for that trailing
+    link (or the policy) is reserved before packing each chunk's body.
+    """
+    v4 = sorted(n for n in networks if isinstance(n, IPv4Network))
+    v6 = sorted(n for n in networks if isinstance(n, IPv6Network))
+    tokens = [*passthrough, *(_render(n) for n in v4), *(_render(n) for n in v6)]
+
+    records: dict[str, list[str]] = {}
+    chunk_num = 1
+    start = 0
+    while True:
+        name = f"_spf53-{chunk_num}.{domain}"
+        remaining = tokens[start:]
+
+        if _fits(["v=spf1", *remaining, policy]):
+            content = " ".join(["v=spf1", *remaining, policy])
+            records[name] = _split(content)
+            return records
+
+        next_link = f"include:_spf53-{chunk_num + 1}.{domain}"
+        n = _max_fit(remaining, next_link)
+        if n == 0:
+            raise ValueError(f"mechanism too large to fit in chunk {name!r}")
+        content = " ".join(["v=spf1", *remaining[:n], next_link])
+        records[name] = _split(content)
+        start += n
+        chunk_num += 1
+
+
+def lookup_cost(records: dict[str, list[str]], passthrough: Sequence[str]) -> int:
+    """Chain length + 1 (apex include) + DNS-querying passthrough mechanisms."""
+    dns_querying = sum(1 for p in passthrough if p.startswith(DNS_QUERYING_MECHANISMS))
+    return len(records) + 1 + dns_querying
+
+
+def to_route53_value(strings: list[str]) -> str:
+    """Render as Route53's space-separated, double-quoted TXT value form."""
+    return " ".join(f'"{_escape(s)}"' for s in strings)
+
+
+def from_route53_value(value: str) -> list[str]:
+    """Parse a Route53 TXT value back into its component strings.
+
+    Defensively unescapes ``\\"`` and ``\\\\`` inside each quoted string.
+    """
+    strings: list[str] = []
+    i, n = 0, len(value)
+    while i < n:
+        if value[i].isspace():
+            i += 1
+            continue
+        if value[i] != '"':
+            raise ValueError(f"malformed Route53 TXT value: {value!r}")
+        i += 1
+        chars: list[str] = []
+        while i < n and value[i] != '"':
+            if value[i] == "\\" and i + 1 < n:
+                chars.append(value[i + 1])
+                i += 2
+            else:
+                chars.append(value[i])
+                i += 1
+        if i >= n:
+            raise ValueError(f"unterminated quoted string in Route53 TXT value: {value!r}")
+        i += 1  # skip closing quote
+        strings.append("".join(chars))
+    return strings
+
+
+def _render(network: IPv4Network | IPv6Network) -> str:
+    """Render a network as an ip4:/ip6: mechanism; host routes drop the prefix."""
+    is_v6 = isinstance(network, IPv6Network)
+    label = "ip6" if is_v6 else "ip4"
+    host_prefixlen = 128 if is_v6 else 32
+    if network.prefixlen == host_prefixlen:
+        return f"{label}:{network.network_address}"
+    return f"{label}:{network}"
+
+
+def _escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _split(content: str) -> list[str]:
+    result = _try_split(content)
+    if result is None:
+        raise ValueError(f"content does not fit in {MAX_STRINGS_PER_RECORD} strings: {content!r}")
+    return result
+
+
+def _try_split(content: str) -> list[str] | None:
+    """Split content into <= MAX_STRINGS_PER_RECORD strings, or None if it can't."""
+    if len(content) <= MAX_TXT_STRING:
+        return [content]
+    if len(content) > _MAX_RECORD_CHARS:
+        return None
+    split_at = None
+    for i, ch in enumerate(content):
+        if i > MAX_TXT_STRING:
+            break
+        if ch == " " and (len(content) - i) <= MAX_TXT_STRING:
+            split_at = i
+    if split_at is None:
+        return None
+    return [content[:split_at], content[split_at:]]
+
+
+def _fits(tokens: list[str]) -> bool:
+    return _try_split(" ".join(tokens)) is not None
+
+
+def _max_fit(remaining: list[str], suffix: str) -> int:
+    """Largest prefix of `remaining` that still fits alongside `suffix`."""
+    best = 0
+    for i in range(len(remaining) + 1):
+        if _fits(["v=spf1", *remaining[:i], suffix]):
+            best = i
+        else:
+            break
+    return best

spf53/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface for spf53: plan, apply, deploy."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from spf53 import core, ssm
+from spf53.config import Spf53Config, load_config_file
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="spf53")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    plan_parser = subparsers.add_parser("plan", help="show pending SPF changes")
+    _add_config_args(plan_parser)
+    plan_parser.set_defaults(func=_cmd_plan)
+
+    apply_parser = subparsers.add_parser("apply", help="apply pending SPF changes")
+    _add_config_args(apply_parser)
+    apply_parser.add_argument(
+        "--force", action="store_true", help="apply changes even if a guard refuses"
+    )
+    apply_parser.set_defaults(func=_cmd_apply)
+
+    deploy_parser = subparsers.add_parser("deploy", help="deploy the spf53 Lambda")
+    deploy_parser.add_argument("-c", "--config", required=True, metavar="FILE")
+    deploy_parser.add_argument("--schedule", default="rate(1 hour)")
+    deploy_parser.add_argument("--create-topic", metavar="NAME")
+    deploy_parser.add_argument("--param-name", default=ssm.DEFAULT_PARAM)
+    deploy_parser.add_argument("--function-name", default="spf53")
+    deploy_parser.add_argument("--region")
+    deploy_parser.add_argument("--dry-run", action="store_true")
+    deploy_parser.set_defaults(func=_cmd_deploy)
+
+    return parser
+
+
+def _add_config_args(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("-c", "--config", metavar="FILE", help="local YAML config file")
+    group.add_argument(
+        "--ssm-param",
+        metavar="NAME",
+        help=f"SSM parameter name (default: {ssm.DEFAULT_PARAM})",
+    )
+
+
+def _load_config(args: argparse.Namespace) -> Spf53Config:
+    if args.config:
+        return load_config_file(args.config)
+    return ssm.load_config_ssm(args.ssm_param or ssm.DEFAULT_PARAM)
+
+
+def _expected_apex_line(p: core.DomainPlan) -> str | None:
+    if not p.desired:
+        return None
+    last_name = f"_spf53-{len(p.desired)}.{p.domain}"
+    last_strings = p.desired.get(last_name)
+    if not last_strings:
+        return None
+    policy = "".join(last_strings).split()[-1]
+    return f"v=spf1 include:_spf53-1.{p.domain} {policy}"
+
+
+def _cmd_plan(args: argparse.Namespace) -> int:
+    cfg = _load_config(args)
+    result = core.plan(cfg)
+
+    for p in result.plans:
+        print(f"== {p.domain} ==")
+        apex_line = _expected_apex_line(p)
+        print(f"expected apex record: {apex_line if apex_line else 'n/a'}")
+        cost_note = " (WARNING: exceeds 9-lookup limit)" if p.lookup_cost > 9 else ""
+        print(f"lookup cost: {p.lookup_cost}{cost_note}")
+        if p.apex_warning:
+            print(f"WARNING: {p.apex_warning}")
+        if not p.guard.ok:
+            print(f"guard: REFUSED - {'; '.join(p.guard.reasons)}")
+        if not p.has_changes:
+            print("changes: none")
+        else:
+            print(f"changes: {len(p.upserts)} upsert(s), {len(p.deletes)} delete(s)")
+        print(p.summary)
+        print()
+
+    for err in result.errors:
+        print(f"ERROR: {err}", file=sys.stderr)
+
+    if result.errors:
+        return 1
+    if any(p.has_changes for p in result.plans):
+        return 2
+    return 0
+
+
+def _cmd_apply(args: argparse.Namespace) -> int:
+    cfg = _load_config(args)
+    result = core.apply(cfg, force=args.force)
+
+    refused: list[str] = []
+    for p in result.plans:
+        if not p.has_changes:
+            continue
+        if not p.guard.ok and not args.force:
+            refused.append(p.domain)
+            print(f"{p.domain}: refused - {'; '.join(p.guard.reasons)}")
+        else:
+            print(f"{p.domain}: applied")
+
+    for err in result.errors:
+        print(f"ERROR: {err}", file=sys.stderr)
+
+    if result.errors or refused:
+        return 1
+    return 0
+
+
+def _cmd_deploy(args: argparse.Namespace) -> int:
+    from spf53 import deploy
+
+    result = deploy.run_deploy(args)
+    return result if isinstance(result, int) else 0

spf53/config.py

@@ -0,0 +1,153 @@
+"""Config schema and YAML parsing for spf53."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+_ALLOWED_TOP_KEYS = {"sns_topic_arn", "resolver_ips", "domains"}
+_ALLOWED_DOMAIN_KEYS = {
+    "name",
+    "hosted_zone_id",
+    "includes",
+    "passthrough",
+    "policy",
+    "max_shrink_pct",
+}
+_VALID_POLICIES = ("~all", "-all")
+
+
+class ConfigError(Exception):
+    """Raised when a config fails validation."""
+
+
+@dataclass(frozen=True)
+class DomainConfig:
+    name: str
+    hosted_zone_id: str
+    includes: tuple[str, ...]
+    passthrough: tuple[str, ...] = ()
+    policy: str = "~all"
+    max_shrink_pct: int = 30
+
+
+@dataclass(frozen=True)
+class Spf53Config:
+    domains: tuple[DomainConfig, ...]
+    sns_topic_arn: str | None = None
+    resolver_ips: tuple[str, ...] = ("1.1.1.1", "8.8.8.8")
+
+
+def parse_config(yaml_text: str) -> Spf53Config:
+    try:
+        raw = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as e:
+        raise ConfigError(f"invalid YAML: {e}") from e
+
+    if raw is None:
+        raise ConfigError("config is empty")
+    if not isinstance(raw, dict):
+        raise ConfigError(f"config must be a mapping, got {type(raw).__name__}")
+
+    unknown = set(raw) - _ALLOWED_TOP_KEYS
+    if unknown:
+        raise ConfigError(f"unknown top-level field(s): {', '.join(sorted(unknown))}")
+
+    if "domains" not in raw:
+        raise ConfigError("missing required field 'domains'")
+    domains_raw = raw["domains"]
+    if not isinstance(domains_raw, list) or not domains_raw:
+        raise ConfigError("'domains' must be a non-empty list")
+    domains = tuple(_parse_domain(i, d) for i, d in enumerate(domains_raw))
+
+    sns_topic_arn = raw.get("sns_topic_arn")
+    if sns_topic_arn is not None and not isinstance(sns_topic_arn, str):
+        raise ConfigError("'sns_topic_arn' must be a string")
+
+    if "resolver_ips" in raw:
+        resolver_ips_raw = raw["resolver_ips"]
+        if not isinstance(resolver_ips_raw, list) or not all(
+            isinstance(x, str) for x in resolver_ips_raw
+        ):
+            raise ConfigError("'resolver_ips' must be a list of strings")
+        if not resolver_ips_raw:
+            raise ConfigError("'resolver_ips' must not be empty")
+        resolver_ips = tuple(resolver_ips_raw)
+    else:
+        resolver_ips = ("1.1.1.1", "8.8.8.8")
+
+    return Spf53Config(domains=domains, sns_topic_arn=sns_topic_arn, resolver_ips=resolver_ips)
+
+
+def _parse_domain(index: int, raw: object) -> DomainConfig:
+    label = f"domains[{index}]"
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{label}: must be a mapping, got {type(raw).__name__}")
+
+    unknown = set(raw) - _ALLOWED_DOMAIN_KEYS
+    if unknown:
+        raise ConfigError(f"{label}: unknown field(s): {', '.join(sorted(unknown))}")
+
+    if "name" not in raw:
+        raise ConfigError(f"{label}: missing required field 'name'")
+    name = raw["name"]
+    if not isinstance(name, str) or not name:
+        raise ConfigError(f"{label}: 'name' must be a non-empty string")
+    # Normalize so config names match what Route53 returns (always lowercase,
+    # unqualified) — otherwise every diff looks like a change and the shrink
+    # guard never sees a matching live record.
+    name = name.lower()
+    if name.endswith("."):
+        name = name[:-1]
+    if not name:
+        raise ConfigError(f"{label}: 'name' must be a non-empty string")
+    label = f"domain '{name}'"
+
+    if "hosted_zone_id" not in raw:
+        raise ConfigError(f"{label}: missing required field 'hosted_zone_id'")
+    hosted_zone_id = raw["hosted_zone_id"]
+    if not isinstance(hosted_zone_id, str) or not hosted_zone_id:
+        raise ConfigError(f"{label}: 'hosted_zone_id' must be a non-empty string")
+
+    if "includes" not in raw:
+        raise ConfigError(f"{label}: missing required field 'includes'")
+    includes_raw = raw["includes"]
+    if not isinstance(includes_raw, list) or not all(isinstance(x, str) for x in includes_raw):
+        raise ConfigError(f"{label}: 'includes' must be a list of strings")
+    includes = tuple(includes_raw)
+
+    passthrough_raw = raw.get("passthrough", [])
+    if not isinstance(passthrough_raw, list) or not all(
+        isinstance(x, str) for x in passthrough_raw
+    ):
+        raise ConfigError(f"{label}: 'passthrough' must be a list of strings")
+    passthrough = tuple(passthrough_raw)
+
+    policy = raw.get("policy", "~all")
+    if policy not in _VALID_POLICIES:
+        raise ConfigError(f"{label}: 'policy' must be '~all' or '-all', got {policy!r}")
+
+    max_shrink_pct = raw.get("max_shrink_pct", 30)
+    if (
+        isinstance(max_shrink_pct, bool)
+        or not isinstance(max_shrink_pct, int)
+        or not 0 <= max_shrink_pct <= 100
+    ):
+        raise ConfigError(
+            f"{label}: 'max_shrink_pct' must be an int between 0 and 100, got {max_shrink_pct!r}"
+        )
+
+    return DomainConfig(
+        name=name,
+        hosted_zone_id=hosted_zone_id,
+        includes=includes,
+        passthrough=passthrough,
+        policy=policy,
+        max_shrink_pct=max_shrink_pct,
+    )
+
+
+def load_config_file(path: str | Path) -> Spf53Config:
+    return parse_config(Path(path).read_text())

spf53/core.py

@@ -0,0 +1,189 @@
+"""Orchestration: resolve, chunk, diff against live DNS, guard-check, apply, notify."""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+
+from botocore.exceptions import ClientError
+
+from spf53 import chunker, guards, notify, resolver, route53
+from spf53.config import Spf53Config
+from spf53.guards import GuardResult
+from spf53.resolver import ResolutionError
+
+IPNetwork = ipaddress.IPv4Network | ipaddress.IPv6Network
+
+_SUMMARY_LIST_CAP = 20
+
+
+@dataclass(frozen=True)
+class DomainPlan:
+    domain: str
+    zone_id: str
+    desired: dict[str, list[str]]
+    live: dict[str, list[str]]
+    upserts: dict[str, list[str]]
+    deletes: dict[str, list[str]]
+    guard: GuardResult
+    lookup_cost: int
+    apex_warning: str | None
+    summary: str
+    delete_ttls: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.upserts or self.deletes)
+
+
+@dataclass(frozen=True)
+class RunResult:
+    plans: tuple[DomainPlan, ...]
+    errors: tuple[str, ...]
+
+
+def plan(cfg: Spf53Config) -> RunResult:
+    plans: list[DomainPlan] = []
+    errors: list[str] = []
+
+    for dc in cfg.domains:
+        try:
+            networks = resolver.flatten(dc.includes, cfg.resolver_ips)
+        except ResolutionError as exc:
+            errors.append(str(exc))
+            continue
+
+        desired = chunker.build_records(dc.name, networks, dc.passthrough, dc.policy)
+        live_all, live_ttls = route53.get_txt_records(dc.hosted_zone_id, dc.name)
+        live = {name: strings for name, strings in live_all.items() if name != dc.name}
+        apex_warning = _apex_warning(dc.name, live_all.get(dc.name))
+
+        upserts = {name: strings for name, strings in desired.items() if live.get(name) != strings}
+        deletes = {name: strings for name, strings in live.items() if name not in desired}
+        delete_ttls = {name: live_ttls[name] for name in deletes if name in live_ttls}
+
+        try:
+            live_networks = _networks_from_records(live)
+        except ValueError as exc:
+            errors.append(f"{dc.name}: {exc}")
+            continue
+        guard = guards.check_guards(live_networks, networks, dc.max_shrink_pct)
+
+        plans.append(
+            DomainPlan(
+                domain=dc.name,
+                zone_id=dc.hosted_zone_id,
+                desired=desired,
+                live=live,
+                upserts=upserts,
+                deletes=deletes,
+                guard=guard,
+                lookup_cost=chunker.lookup_cost(desired, dc.passthrough),
+                apex_warning=apex_warning,
+                summary=_build_summary(dc.name, live_networks, networks),
+                delete_ttls=delete_ttls,
+            )
+        )
+
+    return RunResult(plans=tuple(plans), errors=tuple(errors))
+
+
+def apply(cfg: Spf53Config, force: bool = False) -> RunResult:
+    result = plan(cfg)
+    errors = list(result.errors)
+
+    for p in result.plans:
+        if not p.has_changes:
+            continue
+        if not p.guard.ok and not force:
+            _notify_refusal(cfg.sns_topic_arn, p)
+            continue
+        try:
+            route53.apply_changes(p.zone_id, p.upserts, p.deletes, delete_ttls=p.delete_ttls)
+        except ClientError as exc:
+            msg = f"{p.domain}: failed to apply Route53 changes: {exc}"
+            errors.append(msg)
+            notify.publish(cfg.sns_topic_arn, f"spf53: failed to apply changes for {p.domain}", msg)
+            continue
+        _notify_success(cfg.sns_topic_arn, p)
+
+    for err in result.errors:
+        notify.publish(cfg.sns_topic_arn, "spf53: SPF resolution failed", err)
+
+    return RunResult(plans=result.plans, errors=tuple(errors))
+
+
+def _apex_warning(domain: str, apex_record: list[str] | None) -> str | None:
+    expected = f"include:_spf53-1.{domain}"
+    if apex_record is None:
+        return (
+            f"no apex TXT record found for {domain} — create one: "
+            f"v=spf1 include:_spf53-1.{domain} ~all"
+        )
+    if expected in "".join(apex_record):
+        return None
+    return (
+        f"live apex TXT record for {domain} does not contain '{expected}' — "
+        f"the apex should read: v=spf1 include:_spf53-1.{domain} <policy>"
+    )
+
+
+def _networks_from_records(records: dict[str, list[str]]) -> list[IPNetwork]:
+    networks: list[IPNetwork] = []
+    for name, strings in records.items():
+        for token in "".join(strings).split():
+            for prefix in ("ip4:", "ip6:"):
+                if token.startswith(prefix):
+                    try:
+                        networks.append(ipaddress.ip_network(token[len(prefix) :], strict=False))
+                    except ValueError as exc:
+                        raise ValueError(
+                            f"invalid {prefix} token {token!r} in live record {name!r}: {exc}"
+                        ) from exc
+                    break
+    return networks
+
+
+def _sort_key(network: IPNetwork) -> tuple[int, int, int]:
+    return (network.version, int(network.network_address), network.prefixlen)
+
+
+def _format_cidrs(networks: Iterable[IPNetwork]) -> str:
+    ordered = sorted(networks, key=_sort_key)
+    if not ordered:
+        return "none"
+    shown = [str(n) for n in ordered[:_SUMMARY_LIST_CAP]]
+    if len(ordered) > _SUMMARY_LIST_CAP:
+        shown.append(f"+{len(ordered) - _SUMMARY_LIST_CAP} more")
+    return ", ".join(shown)
+
+
+def _build_summary(
+    domain: str,
+    live_networks: Sequence[IPNetwork],
+    new_networks: Sequence[IPNetwork],
+) -> str:
+    live_set = set(live_networks)
+    new_set = set(new_networks)
+    added = new_set - live_set
+    removed = live_set - new_set
+    return (
+        f"{domain}: {len(added)} CIDR(s) added, {len(removed)} CIDR(s) removed\n"
+        f"  added:   {_format_cidrs(added)}\n"
+        f"  removed: {_format_cidrs(removed)}"
+    )
+
+
+def _notify_refusal(topic_arn: str | None, p: DomainPlan) -> None:
+    reasons = "; ".join(p.guard.reasons)
+    notify.publish(
+        topic_arn,
+        f"spf53: refused to apply changes for {p.domain}",
+        f"spf53 refused to publish new SPF records for {p.domain} because the "
+        f"safety guard failed: {reasons}\n\n{p.summary}",
+    )
+
+
+def _notify_success(topic_arn: str | None, p: DomainPlan) -> None:
+    notify.publish(topic_arn, f"spf53: applied SPF changes for {p.domain}", p.summary)