emailsec 0.1.0__tar.gz

emailsec-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

emailsec-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

emailsec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Sileo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emailsec-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: emailsec
+Version: 0.1.0
+Summary: SPF (Sender Policy Framework) and DKIM parser and checker.
+Author-email: Thomas Sileo <thomas.sileo@sent.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Requires-Python: >=3.10
+Requires-Dist: aiodns>=3.2.0
+Requires-Dist: pyparsing>=3.2.3
+Description-Content-Type: text/markdown
+
+# emailsec
+
+`emailsec` is a Python library that provides tools to parse and verify SPF (Sender Policy Framework) and DKIM (DomainKeys Identified Mail) records.
+
+**This project is still in early development.**
+
+## Sender Policy Framework
+
+[RFC 7208](https://datatracker.ietf.org/doc/html/rfc7208)-compliant parser and checker.
+
+### Parser
+
+```
+>>> from emailsec.spf.parser import parse_record
+>>> parse_record("v=spf1 +a mx/30 mx:example.org/30 -all")
+[A(qualifier=<Qualifier.PASS: '+'>, domain_spec=None, cidr=None),
+ MX(qualifier=<Qualifier.PASS: '+'>, domain_spec=None, cidr='/30'),
+ MX(qualifier=<Qualifier.PASS: '+'>, domain_spec='example.org', cidr='/30'),
+ All(qualifier=<Qualifier.FAIL: '-'>)]
+```
+
+### Checker
+
+```
+>>> import asyncio
+>>> from emailsec.spf.checker import check_host
+>>>  asyncio.run(check_host(ip="192.0.2.10", sender="hello@example.com"))
+(<Result.PASS: 'pass'>, '')
+```
+
+## Contribution
+
+Contributions are welcome but please open an issue to start a discussion before starting something consequent.
+
+## License
+
+Copyright (c) 2025 Thomas Sileo and contributors. Released under the MIT license.

emailsec-0.1.0/README.md

@@ -0,0 +1,37 @@
+# emailsec
+
+`emailsec` is a Python library that provides tools to parse and verify SPF (Sender Policy Framework) and DKIM (DomainKeys Identified Mail) records.
+
+**This project is still in early development.**
+
+## Sender Policy Framework
+
+[RFC 7208](https://datatracker.ietf.org/doc/html/rfc7208)-compliant parser and checker.
+
+### Parser
+
+```
+>>> from emailsec.spf.parser import parse_record
+>>> parse_record("v=spf1 +a mx/30 mx:example.org/30 -all")
+[A(qualifier=<Qualifier.PASS: '+'>, domain_spec=None, cidr=None),
+ MX(qualifier=<Qualifier.PASS: '+'>, domain_spec=None, cidr='/30'),
+ MX(qualifier=<Qualifier.PASS: '+'>, domain_spec='example.org', cidr='/30'),
+ All(qualifier=<Qualifier.FAIL: '-'>)]
+```
+
+### Checker
+
+```
+>>> import asyncio
+>>> from emailsec.spf.checker import check_host
+>>>  asyncio.run(check_host(ip="192.0.2.10", sender="hello@example.com"))
+(<Result.PASS: 'pass'>, '')
+```
+
+## Contribution
+
+Contributions are welcome but please open an issue to start a discussion before starting something consequent.
+
+## License
+
+Copyright (c) 2025 Thomas Sileo and contributors. Released under the MIT license.

emailsec-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "emailsec"
+version = "0.1.0"
+description = "SPF (Sender Policy Framework) and DKIM parser and checker."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Thomas Sileo", email = "thomas.sileo@sent.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "aiodns>=3.2.0",
+    "pyparsing>=3.2.3",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "pyyaml>=6.0.2",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".build.yml",
+  "uv.lock",
+  "tests/",
+]

emailsec-0.1.0/src/emailsec/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from spf-checker!"

emailsec-0.1.0/src/emailsec/dns_resolver.py

@@ -0,0 +1,48 @@
+import asyncio
+import typing
+
+from emailsec import errors
+
+import aiodns
+import pycares
+
+_MAX_LOOKUPS = 10
+
+
+class DNSResolver:
+    def __init__(self) -> None:
+        self.__lookups_counter = 0
+        self.__resolver = aiodns.DNSResolver(loop=asyncio.get_event_loop())
+
+    async def _query(self, name: str, query_type: str) -> typing.Any:
+        self.__lookups_counter += 1
+        if self.__lookups_counter > _MAX_LOOKUPS:
+            raise errors.Permerror("Max DNS lookups exceeded")
+
+        try:
+            return await self.__resolver.query(name, query_type)
+        except aiodns.error.DNSError as dns_error:
+            print(dns_error)
+            error_msg = dns_error.args[1]
+            match dns_error.args[0]:
+                case aiodns.error.ARES_ENOTFOUND:  # type: ignore
+                    return None
+                case aiodns.error.ARES_EBADQUERY:  # type: ignore
+                    raise errors.Permerror(f"DNS Error: {error_msg}")
+                case _:
+                    raise errors.Temperror(f"DNS error: {error_msg}")
+
+    async def txt(self, name: str) -> list[pycares.ares_query_txt_result] | None:
+        return await self._query(name, "TXT")
+
+    async def mx(self, name: str) -> list[pycares.ares_query_mx_result] | None:
+        return await self._query(name, "MX")
+
+    async def a(self, name: str) -> list[pycares.ares_query_a_result] | None:
+        return await self._query(name, "A")
+
+    async def aaaa(self, name: str) -> list[pycares.ares_query_aaaa_result] | None:
+        return await self._query(name, "AAAA")
+
+    async def ptr(self, name: str) -> pycares.ares_query_ptr_result | None:
+        return await self._query(name, "PTR")

emailsec-0.1.0/src/emailsec/errors.py

@@ -0,0 +1,10 @@
+class SPFCheckerError(Exception):
+    """Base errror."""
+
+
+class Permerror(Exception):
+    pass
+
+
+class Temperror(Exception):
+    pass

emailsec-0.1.0/src/emailsec/spf/checker.py

@@ -0,0 +1,236 @@
+import typing
+import enum
+from pycares import ares_query_a_result, ares_query_aaaa_result
+import ipaddress
+from emailsec.spf import parser
+from emailsec.spf.parser import parse_record, Qualifier
+from emailsec.spf.expander import Expander
+from emailsec import errors
+from emailsec.dns_resolver import DNSResolver
+
+IPVersion = typing.Literal[4, 6]
+
+
+class Result(enum.StrEnum):
+    NONE = "none"
+    NEUTRAL = "neutral"
+    PASS = "pass"
+    FAIL = "fail"
+    SOFTFAIL = "softfail"
+    TEMPERROR = "temperror"
+    PERMERROR = "permerror"
+
+    @classmethod
+    def from_qualifier(cls, q: Qualifier) -> "Result":
+        match q:
+            case Qualifier.PASS:
+                return cls.PASS
+            case Qualifier.FAIL:
+                return cls.FAIL
+            case Qualifier.SOFTFAIL:
+                return cls.SOFTFAIL
+            case Qualifier.NEUTRAL:
+                return cls.NEUTRAL
+
+
+async def _ip_networks_from_a_records(
+    dns_resolver: DNSResolver, name: str, ip_version: IPVersion, cidr: str | None = None
+) -> list[ipaddress.IPv4Network | ipaddress.IPv6Network]:
+    ip_networks = []
+
+    query_results: list[ares_query_a_result] | list[ares_query_aaaa_result] | None
+    if ip_version == 4:
+        query_results = await dns_resolver.a(name)
+    elif ip_version == 6:
+        query_results = await dns_resolver.aaaa(name)
+
+    if not query_results:
+        return []
+
+    for qres in query_results:
+        print(f"{qres.host}/{cidr=}")
+        ip_networks.append(ipaddress.ip_network(qres.host + (cidr or ""), False))
+
+    return ip_networks
+
+
+async def check_host(ip: str, sender: str) -> tuple[Result, str]:
+    parsed_ip = ipaddress.ip_address(ip)
+    if "@" not in sender:
+        sender = f"postmaster@{sender}"
+    domain = sender.split("@", maxsplit=1)[-1]
+
+    dns_resolver = DNSResolver()
+
+    try:
+        res, explanation = await _rec_check_host(
+            dns_resolver, parsed_ip, sender, domain
+        )
+    except errors.Permerror as error:
+        return Result.PERMERROR, error.args[0]
+    except errors.Temperror as error:
+        return Result.TEMPERROR, error.args[0]
+    else:
+        return res, explanation
+
+
+async def _rec_check_host(
+    dns_resolver: DNSResolver,
+    parsed_ip: ipaddress.IPv4Address | ipaddress.IPv6Address,
+    sender: str,
+    domain: str,
+    recursion=0,
+) -> tuple[Result, str]:
+    if recursion > 10:
+        raise errors.Permerror("Too much recursion")
+
+    end_result = None
+
+    expander = Expander(str(parsed_ip), sender, domain=domain)
+
+    spfs = []
+    txt_records = await dns_resolver.txt(domain)
+    if not txt_records:
+        return Result.NONE, ""
+    for txt_record in txt_records:
+        if txt_record.text.lower().startswith("v=spf1 "):
+            spfs.append(txt_record.text)
+    print(spfs)
+    if len(spfs) > 1:
+        raise errors.Permerror("Too many SPF records")
+
+    try:
+        parsed_spf = parse_record(spfs[0])
+    except ValueError:
+        raise errors.Permerror(f"Failed to parse SPF record {spfs[0]!r}")
+
+    modifiers = {}
+    for mechanism in parsed_spf:
+        match mechanism:
+            case parser.Modifier(name=name, value=value):
+                modifiers[name] = value
+
+            case parser.All(qualifier=qualifier):
+                end_result = Result.from_qualifier(qualifier)
+                break
+
+            case parser.Include():
+                target_name = expander.expand(mechanism.domain_spec)
+                # Recursive evaluation
+                # https://datatracker.ietf.org/doc/html/rfc7208#section-5.2
+                rec_result, _ = await _rec_check_host(
+                    dns_resolver=dns_resolver,
+                    parsed_ip=parsed_ip,
+                    sender=sender,
+                    domain=target_name,
+                    recursion=recursion + 1,
+                )
+                match rec_result:
+                    case Result.PASS:
+                        end_result = rec_result
+                        break
+                    case Result.FAIL | Result.SOFTFAIL | Result.NEUTRAL:
+                        continue
+                    case Result.TEMPERROR | Result.PERMERROR | Result.NONE:
+                        end_result = Result.PERMERROR
+                        break
+
+            case parser.Exists():
+                target_name = expander.expand(mechanism.domain_spec)
+                if await dns_resolver.a(target_name):
+                    end_result = Result.from_qualifier(mechanism.qualifier)
+                    break
+
+            case parser.A():
+                target_name = (
+                    expander.expand(mechanism.domain_spec)
+                    if mechanism.domain_spec
+                    else domain
+                )
+                ip_networks = await _ip_networks_from_a_records(
+                    dns_resolver, target_name, parsed_ip.version, cidr=mechanism.cidr
+                )
+                if any(parsed_ip in ip_network for ip_network in ip_networks):
+                    end_result = Result.from_qualifier(mechanism.qualifier)
+                    break
+
+            case parser.IP4() | parser.IP6():
+                if parsed_ip in mechanism.ip_network:
+                    end_result = Result.from_qualifier(mechanism.qualifier)
+                    break
+
+            case parser.MX():
+                target_name = (
+                    expander.expand(mechanism.domain_spec)
+                    if mechanism.domain_spec
+                    else domain
+                )
+                for mx_record in (await dns_resolver.mx(target_name)) or []:
+                    ip_networks = await _ip_networks_from_a_records(
+                        dns_resolver,
+                        mx_record.host,
+                        parsed_ip.version,
+                        cidr=mechanism.cidr,
+                    )
+                    print(
+                        f"MX {parsed_spf=} {mx_record=}/{target_name=}/{ip_networks=}/{parsed_ip=}"
+                    )
+                    if any(parsed_ip in ip_network for ip_network in ip_networks):
+                        end_result = Result.from_qualifier(mechanism.qualifier)
+                        break
+
+                if end_result:
+                    break
+
+            case parser.PTR():
+                target_name = (
+                    expander.expand(mechanism.domain_spec)
+                    if mechanism.domain_spec
+                    else domain
+                )
+                ptr_record = await dns_resolver.ptr(parsed_ip.reverse_pointer)
+                if not ptr_record:
+                    continue
+                validated_domains = []
+                for alias in ptr_record.aliases[:10]:
+                    ip_networks = await _ip_networks_from_a_records(
+                        dns_resolver, alias, parsed_ip.version
+                    )
+                    if any(parsed_ip in ip_network for ip_network in ip_networks):
+                        validated_domains.append(alias)
+
+                if target_name in validated_domains or any(
+                    target_name.endswith(validated_domain)
+                    for validated_domain in validated_domains
+                ):
+                    end_result = Result.from_qualifier(mechanism.qualifier)
+                    break
+
+    if end_result is None and "redirect" in modifiers:
+        # At this point, there's no "all" mechanism or it would have returned
+        # while processing it
+        rec_result, _ = await _rec_check_host(
+            dns_resolver=dns_resolver,
+            parsed_ip=parsed_ip,
+            sender=sender,
+            domain=expander.expand(modifiers["redirect"]),
+            recursion=recursion + 1,
+        )
+
+    explanation = ""
+    if end_result is Result.FAIL and "exp" in modifiers:
+        target_name = expander.expand(modifiers["exp"])
+        try:
+            txt_records = await dns_resolver.txt(target_name)
+        except Exception:
+            pass
+        else:
+            if txt_records:
+                explanation = "".join(txt_record.text for txt_record in txt_records)
+
+    # TODO: if result is "fail" look for the exp modifier
+
+    if end_result:
+        return end_result, explanation
+    else:
+        return Result.NEUTRAL, ""

emailsec-0.1.0/src/emailsec/spf/expander.py

@@ -0,0 +1,98 @@
+"""Macros related helpers as defined in RFC7208:
+https://datatracker.ietf.org/doc/html/rfc7208#section-7"""
+
+import time
+import ipaddress
+import re
+
+macro_string_regex = re.compile(
+    (
+        r"%{(?P<letter>[slodipvhcrt])"
+        r"(?P<count>(\d+))?"
+        r"(?P<reverse>(r))?"
+        r"(?P<delimiter>([\.\-\+,\/_=]))?}"
+    ),
+    re.IGNORECASE,
+)
+
+
+class Expander:
+    def __init__(
+        self, ip: str, sender: str, domain: str | None = None, exp_mode: bool = False
+    ) -> None:
+        self.ip = ip
+        self.parsed_ip = ipaddress.ip_address(ip)
+        self.domain = domain if domain else sender.split("@", maxsplit=1)[-1]
+        self.sender = sender
+        self.exp_mode = exp_mode
+
+    def expand(self, value: str) -> str:
+        if "%" not in value:
+            return value
+
+        # Handle special cases first
+        value = value.replace("%_", " ").replace("%-", "%20").replace("%%", "%")
+
+        # Then look for regular macro strings
+        for match in re.finditer(macro_string_regex, value):
+            gd = match.groupdict()
+            res = self.expand_letter(gd["letter"])
+            if gd["reverse"] or gd["count"] or gd["delimiter"]:
+                delimiter = gd["delimiter"] or "."
+                parts = res.split(delimiter)
+
+                if gd["reverse"]:
+                    parts = parts[::-1]
+
+                count = int(gd["count"]) if gd["count"] else len(parts)
+                res = ".".join(parts[-count:])
+
+            value = value.replace(match.group(), res, 1)
+
+        return value
+
+    def expand_letter(self, macro: str) -> str:
+        match macro.lower():
+            case "s":
+                return self.sender
+            case "l":
+                return self.sender.split("@", maxsplit=1)[0]
+            case "o":
+                return self.sender.split("@", maxsplit=1)[1]
+            case "d":
+                return self.domain
+            case "i":
+                if self.parsed_ip.version == 4:
+                    return self.ip
+                else:
+                    return self.parsed_ip.reverse_pointer.removesuffix(".ip6.arpa")[
+                        ::-1
+                    ]
+            case "p":
+                #  p = the validated domain name of <ip> (do not use)
+                raise NotImplementedError()
+            case "v":
+                # v = the string "in-addr" if <ip> is ipv4, or "ip6" if <ip> is ipv6
+                if self.parsed_ip.version == 4:
+                    return "in-addr"
+                else:
+                    return "ip6"
+            case "h":
+                # h = HELO/EHLO domain
+                # TODO: implement
+                raise NotImplementedError()
+            case "c":
+                if not self.exp_mode:
+                    raise ValueError("c only allowed in exp mode")
+                return self.ip
+            case "r":
+                # The "r" macro expands to the name of the receiving MTA.
+                # TODO: implement
+                return "unknown"
+            case "t":
+                if not self.exp_mode:
+                    raise ValueError("c only allowed in exp mode")
+                # Timestamp
+                return str(int(time.time()))
+
+        raise RuntimeError()

emailsec-0.1.0/src/emailsec/spf/parser.py

@@ -0,0 +1,289 @@
+import typing
+from dataclasses import dataclass
+import re
+import pyparsing
+import enum
+from pyparsing import (
+    CaselessLiteral,
+    Combine,
+    Optional,
+    Literal,
+    Regex,
+    Word,
+    ZeroOrMore,
+    alphanums,
+    alphas,
+    nums,
+    printables,
+)
+from pyparsing import pyparsing_common
+import ipaddress
+
+
+class Qualifier(enum.StrEnum):
+    PASS = "+"
+    FAIL = "-"
+    SOFTFAIL = "~"
+    NEUTRAL = "?"
+
+
+@dataclass
+class Modifier:
+    name: str
+    value: str
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result.as_dict()
+        return cls(
+            name=data["name"],
+            value=data["value"],
+        )
+
+
+@dataclass(kw_only=True)
+class _BaseMechanism:
+    qualifier: Qualifier = Qualifier.PASS
+
+
+@dataclass
+class All(_BaseMechanism):
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        return cls()
+
+
+@dataclass
+class MX(_BaseMechanism):
+    domain_spec: str | None
+    cidr: str | None
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result[0].as_dict()
+        return cls(
+            domain_spec=data.get("domain_spec"),
+            cidr=data.get("cidr"),
+        )
+
+
+@dataclass
+class A(_BaseMechanism):
+    domain_spec: str | None
+    cidr: str | None
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result[0].as_dict()
+        return cls(
+            domain_spec=data.get("domain_spec"),
+            cidr=data.get("cidr"),
+        )
+
+
+@dataclass
+class _BaseIP(_BaseMechanism):
+    ip_network: ipaddress.IPv4Network | ipaddress.IPv6Network
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result.as_dict()
+        try:
+            return cls(
+                ip_network=ipaddress.ip_network(
+                    data["ip_address"] + data.get("cidr", "")
+                )
+            )
+        except (ipaddress.AddressValueError, ipaddress.NetmaskValueError):
+            raise pyparsing.ParseException(f"Invalid IP network {data=}")
+
+
+@dataclass
+class IP4(_BaseIP):
+    pass
+
+
+@dataclass
+class IP6(_BaseIP):
+    pass
+
+
+@dataclass
+class _MechanismWithRequiredDomainSpec(_BaseMechanism):
+    domain_spec: str
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result.as_dict()
+        return cls(
+            domain_spec=data["domain_spec"],
+        )
+
+
+@dataclass
+class Include(_MechanismWithRequiredDomainSpec):
+    pass
+
+
+@dataclass
+class Exists(_MechanismWithRequiredDomainSpec):
+    pass
+
+
+@dataclass
+class PTR(_BaseMechanism):
+    domain_spec: str | None
+
+    @classmethod
+    def from_parse_results(cls, parse_result: pyparsing.ParseResults) -> typing.Self:
+        data = parse_result.as_dict()
+        return cls(
+            domain_spec=data.get("domain_spec"),
+        )
+
+
+macro_string_regex = re.compile(
+    (
+        r"%{(?P<letter>[slodipvhcrt])"
+        r"(?P<count>(\d+))?"
+        r"(?P<reverse>(r))?"
+        r"(?P<delimiter>([\.\-\+,\/_=]))?}"
+    ),
+    re.IGNORECASE,
+)
+
+
+version = CaselessLiteral("v=spf1")
+qualifier = Word("+-?~", exact=1)
+name = Word(alphas, alphanums + "-_.")
+
+dual_cidr_length = Combine(Literal("/") + Word(nums))
+
+macro_literal = Word(printables, exact=1, exclude_chars="%")
+macro_expand = Regex(macro_string_regex) | Literal("%%") | Literal("%_") | Literal("%-")
+
+domain_end = (
+    Combine(Literal(".") + Word(alphanums + "-") + Optional(Literal(".")))
+    | macro_expand
+)
+
+macro_string = Combine(
+    ZeroOrMore(macro_expand | macro_literal, stop_on=dual_cidr_length)
+)
+
+
+def _check_domain_end(toks: pyparsing.ParseResults) -> None:
+    domain_end = toks[0].removesuffix(".")
+    if "." in domain_end:
+        top_label = domain_end.split(".")[-1]
+    else:
+        top_label = domain_end
+
+    if not top_label:
+        raise pyparsing.ParseException("empty label")
+
+    try:
+        # Is the top label a macro expand
+        macro_expand.parse_string(top_label, parse_all=True)
+    except pyparsing.ParseException:
+        # Or a valid RFC1035/1123 DNS label
+        if not re.match(r"^(?!-)[a-zA-Z0-9-_]{1,63}(?<!-)$", top_label):
+            raise pyparsing.ParseException("invalid top label")
+
+    return None
+
+
+domain_spec = macro_string.set_parse_action(_check_domain_end)
+
+
+all_ = CaselessLiteral("all").set_parse_action(All.from_parse_results)
+
+include = (
+    CaselessLiteral("include:").suppress() + domain_spec.set_results_name("domain_spec")
+).set_parse_action(Include.from_parse_results)
+
+ip4_cidr_length = Combine(Literal("/") + Regex("3[0-2]|2[0-9]|1[0-9]|[1-9]"))
+ip4 = (
+    CaselessLiteral("ip4:").suppress()
+    + pyparsing_common.ipv4_address.set_results_name("ip_address")
+    + Optional(ip4_cidr_length).set_results_name("cidr")
+).set_parse_action(IP4.from_parse_results)
+
+ip6_cidr_length = Literal("/") + Word(nums)
+ip6 = (
+    CaselessLiteral("ip6:").suppress()
+    + pyparsing_common.ipv6_address.set_results_name("ip_address")
+    + Optional(ip6_cidr_length).set_results_name("cidr")
+).set_parse_action(IP6.from_parse_results)
+
+a = pyparsing.Group(
+    CaselessLiteral("a").suppress()
+    + Optional(
+        pyparsing.ungroup(Literal(":").suppress() + domain_spec)
+    ).set_results_name("domain_spec")
+    + Optional(dual_cidr_length).set_results_name("cidr")
+).set_parse_action(A.from_parse_results)
+
+
+mx = pyparsing.Group(
+    CaselessLiteral("mx").suppress()
+    + Optional(
+        pyparsing.ungroup(Literal(":").suppress() + domain_spec)
+    ).set_results_name("domain_spec")
+    + Optional(dual_cidr_length).set_results_name("cidr")
+).set_parse_action(MX.from_parse_results)
+
+ptr = (
+    CaselessLiteral("ptr").suppress()
+    + Optional(
+        pyparsing.ungroup(Literal(":").suppress() + domain_spec)
+    ).set_results_name("domain_spec")
+).set_parse_action(PTR.from_parse_results)
+
+exists = (
+    CaselessLiteral("exists:").suppress() + domain_spec.set_results_name("domain_spec")
+).set_parse_action(lambda toks: Exists(toks))
+
+unknown_modifier = (
+    name.set_results_name("name")
+    + Literal("=").suppress()
+    + name.set_results_name("value")
+)
+redirect = (
+    CaselessLiteral("redirect").set_results_name("name")
+    + Literal("=").suppress()
+    + domain_spec.set_results_name("value")
+)
+exp = (
+    CaselessLiteral("exp").set_results_name("name")
+    + Literal("=").suppress()
+    + domain_spec.set_results_name("value")
+)
+modifiers = (redirect | exp | unknown_modifier).set_parse_action(
+    Modifier.from_parse_results
+)
+
+
+def _merge_qualifier(toks):
+    group = toks[0]
+    if len(group) == 2:
+        group[1].qualifier = Qualifier(group[0])
+        return group[1]
+    return toks
+
+
+mechanism = pyparsing.ungroup(
+    pyparsing.Group(
+        Optional(qualifier) + (all_ | include | ip4 | ip6 | a | mx | ptr | exists)
+    ).set_parse_action(_merge_qualifier)
+)
+record = version.suppress() + ZeroOrMore(mechanism | modifiers)
+
+Mechanism = typing.TypeVar("Mechanism", bound=_BaseMechanism)
+
+
+def parse_record(rec: str) -> list[Mechanism | Modifier]:
+    try:
+        return record.parse_string(rec, parse_all=True).as_list()
+    except pyparsing.ParseException as parse_error:
+        raise ValueError(f"Invalid record {rec!r}") from parse_error