spftrace 0.1.0__tar.gz

spftrace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott McKeown
+
+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.

spftrace-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: spftrace
+Version: 0.1.0
+Summary: RFC 7208 SPF evaluator that returns a full evaluation trace
+Project-URL: Homepage, https://github.com/smck83/spftrace
+Project-URL: Source, https://github.com/smck83/spftrace
+Project-URL: Issues, https://github.com/smck83/spftrace/issues
+Author: Scott McKeown
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,dns,email,rfc7208,spf,trace
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: dnspython>=2.6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: pyyaml>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# spftrace
+
+An RFC 7208 SPF evaluator that shows its working.
+
+Most SPF libraries answer `pass` or `fail` and throw the reasoning away. spftrace
+returns the reasoning: every DNS query with its rcode and timing, every macro
+expansion before and after, every mechanism with its qualifier and why it did or
+did not match, the running DNS-term and void-lookup counters, and the exact term
+that broke a limit.
+
+It is a library. There is no web UI here, and no framework dependency. Build your
+own CLI, API or service on top.
+
+- Own implementation of `check_host()`, not a wrapper around another evaluator
+- Passes all 203 cases of the official openspf.org RFC 7208 test suite
+- Async core with a blocking convenience wrapper
+- One runtime dependency: dnspython
+- Reads no environment variables and no system resolver config. Configuration is
+  explicit, so the consuming application stays in charge
+
+## Install
+
+```
+pip install spftrace
+```
+
+## Use
+
+```python
+import spftrace
+
+result = spftrace.check("203.0.113.1", "user@example.com")
+
+print(result.verdict)          # pass, fail, softfail, neutral, none,
+                               # permerror or temperror
+print(result.dns_terms_used)   # against the RFC limit of 10
+print(result.to_dict())        # JSON-safe, with the full event trace
+```
+
+From async code, await the async form instead. Calling `check()` inside a running
+event loop raises `SpfUsageError` telling you so, rather than a confusing asyncio
+error from several frames down.
+
+```python
+result = await spftrace.acheck("203.0.113.1", "user@example.com")
+```
+
+### In FastAPI
+
+```python
+from fastapi import FastAPI
+import spftrace
+
+app = FastAPI()
+
+@app.get("/check")
+async def check(ip: str, sender: str):
+    result = await spftrace.acheck(
+        ip, sender, nameservers=["1.1.1.1"], max_queries=75
+    )
+    return result.to_dict()
+```
+
+Do not let users pass arbitrary resolver addresses through to `nameservers`. That
+turns your service into an SSRF-ish DNS proxy. Offer a fixed set of resolvers and
+map the user's choice to one server side.
+
+### Options
+
+```python
+await spftrace.acheck(
+    ip,
+    sender,
+    helo="mail.example.net",     # defaults to the sender domain
+    policy="v=spf1 -all",        # evaluate this instead of looking one up
+    nameservers=["192.0.2.53"],  # defaults to 8.8.8.8
+    timeout=5.0,                 # per-query DNS timeout
+    max_queries=75,              # hard cap on real lookups
+    time_limit=20.0,             # overall deadline, checked between terms
+    receiver="mta01",            # value of the %{r} macro
+    audit=False,                 # see below
+)
+```
+
+`policy=` evaluates a record you paste in rather than one published in DNS, which
+is how you test a change before shipping it.
+
+### Bring your own resolver
+
+Pass a `resolver` instead of `nameservers` to add caching, share a resolver across
+checks, or test with no network at all.
+
+```python
+from spftrace import Evaluator, Limits, ZoneResolver
+
+zone = {"e.com": [("TXT", "v=spf1 ip4:1.2.3.0/24 -all")]}
+result = await Evaluator(ZoneResolver(zone), Limits()).evaluate("1.2.3.4", "a@e.com")
+```
+
+Subclass `BaseResolver` and implement `async _lookup(name, rtype) -> (rcode, answers)`
+for anything else. Query recording, caching, the void count and the budget are all
+handled in the base class.
+
+## Errors are verdicts
+
+RFC outcomes are never exceptions. A malformed record, a lookup-limit breach, an
+exhausted query budget and a DNS timeout all come back as a `permerror` or
+`temperror` verdict with the reason in the trace. You do not have to wrap a check
+in `try` just to survive a hostile zone.
+
+`SpfUsageError` is the exception you may see, and it always means the calling code
+is wrong: `check()` from inside an event loop, or `resolver` and `nameservers`
+supplied together.
+
+## Audit mode
+
+The 10-term limit means evaluation stops at the eleventh lookup, so neither a real
+MTA nor a normal check can tell you how many lookups an over-limit record actually
+needs. `audit=True` keeps counting past the limit and reports the true figure.
+
+The verdict is still forced to `permerror`. Visibility changes; the answer never
+does. A matching mechanism sitting past the limit does not become a `pass`.
+
+## Command line
+
+```
+spftrace 203.0.113.1 user@example.com
+spftrace 203.0.113.1 user@example.com --json
+spftrace 203.0.113.1 user@example.com --policy "v=spf1 include:_spf.example.net -all"
+spftrace 203.0.113.1 user@example.com --dns 1.1.1.1 --audit
+```
+
+`--dns` also reads `SPFTRACE_DNS`. That environment variable is a CLI convenience
+only; the library itself never reads it.
+
+## Result
+
+| Attribute | Meaning |
+| --- | --- |
+| `verdict` (alias `result`) | the RFC 7208 result string |
+| `explanation` | expanded `exp=` text, on `fail` only |
+| `trace` | ordered `Event` log with recursion depth |
+| `queries` | every DNS query: name, type, rcode, answers, ms, void, source |
+| `dns_terms_used` | terms consumed against the limit of 10 |
+| `void_lookups_used` | void lookups against the limit of 2 |
+| `elapsed_ms` | wall time for the evaluation |
+| `warnings` | non-fatal notes about the record |
+
+`to_dict()` is the stable JSON contract and carries `schema_version`. Additive keys
+will not bump it; a change consumers must notice will.
+
+## Limits enforced
+
+- 10 DNS terms over `include`, `a`, `mx`, `ptr`, `exists` and `redirect`, not
+  `ip4`, `ip6` or `all`
+- 2 void lookups, counted once at the resolver. Counting per term double counts:
+  every enclosing `include` re-counts its children, and a single void three
+  includes deep became a false `permerror`
+- 10 MX records per `mx`, 10 PTR names per `ptr`
+- `exp` and `%{p}` do DNS but do not count against the term limit
+- A separate hard cap on real queries, 75 by default, because the term limit
+  counts terms and not lookups: ten `mx` terms with ten MX records each is 10
+  terms but 111 queries
+
+## Tests
+
+```
+pip install -e ".[test]"
+pytest
+```
+
+The RFC 7208 corpus is fetched from a pinned commit and its sha256 is verified, so
+the gate cannot shift underneath you. It is not vendored. `pytest --rfc-strict`
+fails rather than skips when the corpus cannot be fetched; CI uses it.
+`SPFTRACE_RFC_CORPUS=/path/to/rfc7208-tests.yml` runs the suite offline, still
+hash-checked.
+
+## Licence
+
+MIT.

spftrace-0.1.0/README.md

@@ -0,0 +1,180 @@
+# spftrace
+
+An RFC 7208 SPF evaluator that shows its working.
+
+Most SPF libraries answer `pass` or `fail` and throw the reasoning away. spftrace
+returns the reasoning: every DNS query with its rcode and timing, every macro
+expansion before and after, every mechanism with its qualifier and why it did or
+did not match, the running DNS-term and void-lookup counters, and the exact term
+that broke a limit.
+
+It is a library. There is no web UI here, and no framework dependency. Build your
+own CLI, API or service on top.
+
+- Own implementation of `check_host()`, not a wrapper around another evaluator
+- Passes all 203 cases of the official openspf.org RFC 7208 test suite
+- Async core with a blocking convenience wrapper
+- One runtime dependency: dnspython
+- Reads no environment variables and no system resolver config. Configuration is
+  explicit, so the consuming application stays in charge
+
+## Install
+
+```
+pip install spftrace
+```
+
+## Use
+
+```python
+import spftrace
+
+result = spftrace.check("203.0.113.1", "user@example.com")
+
+print(result.verdict)          # pass, fail, softfail, neutral, none,
+                               # permerror or temperror
+print(result.dns_terms_used)   # against the RFC limit of 10
+print(result.to_dict())        # JSON-safe, with the full event trace
+```
+
+From async code, await the async form instead. Calling `check()` inside a running
+event loop raises `SpfUsageError` telling you so, rather than a confusing asyncio
+error from several frames down.
+
+```python
+result = await spftrace.acheck("203.0.113.1", "user@example.com")
+```
+
+### In FastAPI
+
+```python
+from fastapi import FastAPI
+import spftrace
+
+app = FastAPI()
+
+@app.get("/check")
+async def check(ip: str, sender: str):
+    result = await spftrace.acheck(
+        ip, sender, nameservers=["1.1.1.1"], max_queries=75
+    )
+    return result.to_dict()
+```
+
+Do not let users pass arbitrary resolver addresses through to `nameservers`. That
+turns your service into an SSRF-ish DNS proxy. Offer a fixed set of resolvers and
+map the user's choice to one server side.
+
+### Options
+
+```python
+await spftrace.acheck(
+    ip,
+    sender,
+    helo="mail.example.net",     # defaults to the sender domain
+    policy="v=spf1 -all",        # evaluate this instead of looking one up
+    nameservers=["192.0.2.53"],  # defaults to 8.8.8.8
+    timeout=5.0,                 # per-query DNS timeout
+    max_queries=75,              # hard cap on real lookups
+    time_limit=20.0,             # overall deadline, checked between terms
+    receiver="mta01",            # value of the %{r} macro
+    audit=False,                 # see below
+)
+```
+
+`policy=` evaluates a record you paste in rather than one published in DNS, which
+is how you test a change before shipping it.
+
+### Bring your own resolver
+
+Pass a `resolver` instead of `nameservers` to add caching, share a resolver across
+checks, or test with no network at all.
+
+```python
+from spftrace import Evaluator, Limits, ZoneResolver
+
+zone = {"e.com": [("TXT", "v=spf1 ip4:1.2.3.0/24 -all")]}
+result = await Evaluator(ZoneResolver(zone), Limits()).evaluate("1.2.3.4", "a@e.com")
+```
+
+Subclass `BaseResolver` and implement `async _lookup(name, rtype) -> (rcode, answers)`
+for anything else. Query recording, caching, the void count and the budget are all
+handled in the base class.
+
+## Errors are verdicts
+
+RFC outcomes are never exceptions. A malformed record, a lookup-limit breach, an
+exhausted query budget and a DNS timeout all come back as a `permerror` or
+`temperror` verdict with the reason in the trace. You do not have to wrap a check
+in `try` just to survive a hostile zone.
+
+`SpfUsageError` is the exception you may see, and it always means the calling code
+is wrong: `check()` from inside an event loop, or `resolver` and `nameservers`
+supplied together.
+
+## Audit mode
+
+The 10-term limit means evaluation stops at the eleventh lookup, so neither a real
+MTA nor a normal check can tell you how many lookups an over-limit record actually
+needs. `audit=True` keeps counting past the limit and reports the true figure.
+
+The verdict is still forced to `permerror`. Visibility changes; the answer never
+does. A matching mechanism sitting past the limit does not become a `pass`.
+
+## Command line
+
+```
+spftrace 203.0.113.1 user@example.com
+spftrace 203.0.113.1 user@example.com --json
+spftrace 203.0.113.1 user@example.com --policy "v=spf1 include:_spf.example.net -all"
+spftrace 203.0.113.1 user@example.com --dns 1.1.1.1 --audit
+```
+
+`--dns` also reads `SPFTRACE_DNS`. That environment variable is a CLI convenience
+only; the library itself never reads it.
+
+## Result
+
+| Attribute | Meaning |
+| --- | --- |
+| `verdict` (alias `result`) | the RFC 7208 result string |
+| `explanation` | expanded `exp=` text, on `fail` only |
+| `trace` | ordered `Event` log with recursion depth |
+| `queries` | every DNS query: name, type, rcode, answers, ms, void, source |
+| `dns_terms_used` | terms consumed against the limit of 10 |
+| `void_lookups_used` | void lookups against the limit of 2 |
+| `elapsed_ms` | wall time for the evaluation |
+| `warnings` | non-fatal notes about the record |
+
+`to_dict()` is the stable JSON contract and carries `schema_version`. Additive keys
+will not bump it; a change consumers must notice will.
+
+## Limits enforced
+
+- 10 DNS terms over `include`, `a`, `mx`, `ptr`, `exists` and `redirect`, not
+  `ip4`, `ip6` or `all`
+- 2 void lookups, counted once at the resolver. Counting per term double counts:
+  every enclosing `include` re-counts its children, and a single void three
+  includes deep became a false `permerror`
+- 10 MX records per `mx`, 10 PTR names per `ptr`
+- `exp` and `%{p}` do DNS but do not count against the term limit
+- A separate hard cap on real queries, 75 by default, because the term limit
+  counts terms and not lookups: ten `mx` terms with ten MX records each is 10
+  terms but 111 queries
+
+## Tests
+
+```
+pip install -e ".[test]"
+pytest
+```
+
+The RFC 7208 corpus is fetched from a pinned commit and its sha256 is verified, so
+the gate cannot shift underneath you. It is not vendored. `pytest --rfc-strict`
+fails rather than skips when the corpus cannot be fetched; CI uses it.
+`SPFTRACE_RFC_CORPUS=/path/to/rfc7208-tests.yml` runs the suite offline, still
+hash-checked.
+
+## Licence
+
+MIT.

spftrace-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spftrace"
+version = "0.1.0"
+description = "RFC 7208 SPF evaluator that returns a full evaluation trace"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Scott McKeown" }]
+keywords = ["spf", "rfc7208", "email", "dns", "authentication", "trace"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Email",
+  "Topic :: Internet :: Name Service (DNS)",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = ["dnspython>=2.6"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pyyaml>=6"]
+
+[project.scripts]
+spftrace = "spftrace.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/smck83/spftrace"
+Source = "https://github.com/smck83/spftrace"
+Issues = "https://github.com/smck83/spftrace/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spftrace"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/spftrace", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

spftrace-0.1.0/src/spftrace/__init__.py

@@ -0,0 +1,199 @@
+"""spftrace: an RFC 7208 SPF evaluator that shows its working.
+
+The trace is the product, not a side effect. Every DNS query, macro expansion,
+mechanism evaluation and limit decision is recorded and returned.
+
+Quick use:
+
+    import spftrace
+    r = spftrace.check("203.0.113.1", "user@example.com")
+    print(r.verdict)                 # pass | fail | softfail | neutral | none |
+                                     # permerror | temperror
+    print(r.to_dict())               # stable JSON-safe structure
+
+Inside an async application (FastAPI and friends), await the async form:
+
+    r = await spftrace.acheck("203.0.113.1", "user@example.com")
+
+For full control over DNS, build the resolver and evaluator yourself:
+
+    from spftrace import Evaluator, Limits, LiveResolver
+    resolver = LiveResolver(["192.0.2.53"], timeout=3.0, max_queries=75)
+    result = await Evaluator(resolver, Limits()).evaluate(ip, sender, helo)
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Iterable
+
+from .errors import (
+    SpfError,
+    SpfNoneError,
+    SpfPermError,
+    SpfTempError,
+    SpfUsageError,
+)
+from .evaluator import (
+    DEFAULT_TIME_LIMIT,
+    MAX_DNS_TERMS,
+    MAX_MX_RECORDS,
+    MAX_PTR_NAMES,
+    MAX_VOID_LOOKUPS,
+    Evaluator,
+    Limits,
+)
+from .parser import Term, parse
+from .resolver import BaseResolver, DnsError, LiveResolver, ZoneResolver
+from .trace import DnsQueryRecord, Event, Result, Trace
+
+__version__ = "0.1.0"
+
+#: Used only when no resolver and no nameservers are supplied. Callers that care
+#: which resolver answers should pass their own; this library never reads the
+#: system resolver configuration or any environment variable.
+DEFAULT_NAMESERVERS: tuple[str, ...] = ("8.8.8.8",)
+
+#: Hard cap on real DNS queries per evaluation. This is not the RFC's 10-term
+#: limit: that counts terms, not lookups, and ten `mx` terms with ten MX records
+#: each is 10 terms but 111 queries. This cap stops a hostile zone from turning
+#: one check into unbounded traffic.
+DEFAULT_MAX_QUERIES = 75
+
+__all__ = [
+    "__version__",
+    "acheck",
+    "check",
+    "BaseResolver",
+    "DEFAULT_MAX_QUERIES",
+    "DEFAULT_NAMESERVERS",
+    "DEFAULT_TIME_LIMIT",
+    "DnsError",
+    "DnsQueryRecord",
+    "Evaluator",
+    "Event",
+    "Limits",
+    "LiveResolver",
+    "MAX_DNS_TERMS",
+    "MAX_MX_RECORDS",
+    "MAX_PTR_NAMES",
+    "MAX_VOID_LOOKUPS",
+    "Result",
+    "SpfError",
+    "SpfNoneError",
+    "SpfPermError",
+    "SpfTempError",
+    "SpfUsageError",
+    "Term",
+    "Trace",
+    "ZoneResolver",
+    "parse",
+]
+
+
+async def acheck(
+    ip: str,
+    sender: str,
+    helo: str = "",
+    *,
+    policy: str | None = None,
+    resolver: BaseResolver | None = None,
+    nameservers: Iterable[str] | None = None,
+    timeout: float = 5.0,
+    max_queries: int | None = DEFAULT_MAX_QUERIES,
+    time_limit: float = DEFAULT_TIME_LIMIT,
+    receiver: str = "spftrace",
+    audit: bool = False,
+) -> Result:
+    """Evaluate SPF for `ip` sending as `sender`, returning a traced Result.
+
+    RFC outcomes are never exceptions. A malformed record, a blown lookup limit
+    or an exhausted query budget all come back as a `permerror` verdict with the
+    reason in the trace, so a caller never has to wrap this in try/except just to
+    survive a hostile zone. Exceptions are reserved for caller mistakes.
+
+    Args:
+        ip: the connecting IP. IPv4-mapped IPv6 is normalised to IPv4.
+        sender: MAIL FROM address. A bare domain is treated as postmaster@domain.
+        helo: HELO/EHLO name. Defaults to the sender domain.
+        policy: evaluate this record instead of looking one up in DNS. Useful for
+            testing a record you have not published yet.
+        resolver: a ready-made resolver. Mutually exclusive with `nameservers`.
+            Supply your own to add caching, or a ZoneResolver to test offline.
+        nameservers: resolver addresses to query. Defaults to DEFAULT_NAMESERVERS.
+        timeout: per-query DNS timeout in seconds.
+        max_queries: hard cap on real DNS queries, or None for no cap.
+        time_limit: overall deadline in seconds, checked between terms.
+        receiver: value of the %{r} macro.
+        audit: keep counting past the 10-term limit to report what a record
+            really needs. The verdict is still forced to permerror, so this
+            changes visibility and never the answer.
+
+    Raises:
+        SpfUsageError: both `resolver` and `nameservers` were supplied.
+    """
+    if resolver is not None and nameservers is not None:
+        raise SpfUsageError(
+            "pass either resolver or nameservers, not both: a supplied resolver "
+            "already carries its own nameservers, timeout and query budget"
+        )
+    if resolver is None:
+        resolver = LiveResolver(
+            nameservers if nameservers is not None else DEFAULT_NAMESERVERS,
+            timeout=timeout,
+            max_queries=max_queries,
+        )
+    evaluator = Evaluator(
+        resolver,
+        Limits(time_limit=time_limit, audit=audit),
+        receiver=receiver,
+        policy_override=policy,
+    )
+    return await evaluator.evaluate(ip, sender, helo)
+
+
+def check(
+    ip: str,
+    sender: str,
+    helo: str = "",
+    *,
+    policy: str | None = None,
+    resolver: BaseResolver | None = None,
+    nameservers: Iterable[str] | None = None,
+    timeout: float = 5.0,
+    max_queries: int | None = DEFAULT_MAX_QUERIES,
+    time_limit: float = DEFAULT_TIME_LIMIT,
+    receiver: str = "spftrace",
+    audit: bool = False,
+) -> Result:
+    """Blocking form of `acheck`, for scripts and sync code.
+
+    Raises:
+        SpfUsageError: called from inside a running event loop. The evaluator is
+            async underneath; from async code, await `acheck` instead. Without
+            this check asyncio raises a confusing "cannot be called from a
+            running event loop" from several frames down.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        raise SpfUsageError(
+            "spftrace.check() cannot be called from a running event loop. "
+            "Use 'await spftrace.acheck(...)' instead."
+        )
+    return asyncio.run(
+        acheck(
+            ip,
+            sender,
+            helo,
+            policy=policy,
+            resolver=resolver,
+            nameservers=nameservers,
+            timeout=timeout,
+            max_queries=max_queries,
+            time_limit=time_limit,
+            receiver=receiver,
+            audit=audit,
+        )
+    )