# spf-checker

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Implements the SPF (RFC 7208) evaluation algorithm: parses the
record, walks each mechanism in order, follows `include:` and
`redirect=` with bounded depth and lookup limits, and matches the
candidate IPv4 / IPv6 address against `ip4:` and `ip6:` CIDR ranges.
The DNS resolver is fully injectable so the package can be embedded
in browsers, edge workers, or sandboxed runtimes that need to route
lookups through DoH or a service mesh.

## Features

- Parses every mechanism token (`ip4`, `ip6`, `a`, `mx`, `include`,
    `all`, `exists`, `redirect`) and their qualifier prefixes
    (`+ - ~ ?`).
- Bounded recursion: `MAX_INCLUDE_DEPTH = 10` and `MAX_DNS_LOOKUPS =
    10` to surface RFC 7208 §4.6.4 permerror conditions instead of
    hanging.
- IPv4 matching with `Number.parseInt` + bitmasks; IPv6 matching by
    expanding `::` shorthand and comparing bit prefixes.
- Records `email_processing.spf.result_total` attributed by `result`
    for every outcome.

## Usage: Basic

```ts
import { checkSpf } from "@suaveplan/email-processing/spf";

const out = await checkSpf(senderIp, fromDomain, async (d) => {
    const recs = await dns.resolveTxt(d);
    return recs.map((parts) => parts.join(""));
});
```

## Usage: Advanced

```ts
import { checkSpf, parseSpfRecord } from "@suaveplan/email-processing/spf";

const recs = await dnsResolver(domain);
const v = recs.find((r) => r.startsWith("v=spf1"));
if (v) {
    const mechs = parseSpfRecord(v);
    if (mechs.some((m) => m.type === "all" && m.qualifier === "+")) {
        log.warn({ domain }, "open SPF policy (+all)");
    }
}
const out = await checkSpf(ip, domain, dnsResolver);
```

## API Reference

- `parseSpfRecord(record): SpfMechanism[]`.
- `ipv4Matches(ip, cidr): boolean`.
- `ipv6Matches(ip, cidr): boolean`.
- `checkSpf(ip, domain, resolver, depth?, lookupCount?): Promise<SpfCheckResult>`.

## Implementation Notes

`a` / `mx` / `exists` mechanisms are recognised but treated as
non-matches because resolving them requires additional DNS lookups
the caller may not want to fund — most real-world SPF records lean on
`ip4:` / `ip6:` / `include:` anyway. The `lookupCount` parameter is
exposed so callers can compose `checkSpf` across multiple top-level
domains in a single run without re-instantiating the budget. The
function records the SPF outcome to the OTel counter before returning,
including the `permerror` paths, so dashboards can distinguish "bad
record" from "no record".