#!/bin/bash
# spf - Resolve and inspect SPF DNS records
#
# Usage:
#   spf [options] show    <domain>                  Print the published SPF record (or just: spf <domain>)
#   spf [options] find    <domain> {<ip>|a:<host>}  Is an IP covered, or an a:<host> present? (and how)
#   spf [options] has     <domain> <token>          Is a token present in the expanded record? (and where)
#   spf [options] flatten <domain>                  Print all IPs authorized by an SPF record
#   spf [options] check   <domain>                  Check SPF health (lookups, includes, etc.)
#   spf [options] tree    <domain>                  Print SPF include tree
#   spf [options] ir      <domain>                  Print the raw resolver IR (tab-delimited)
#   spf <verb> -h
#
# Options:
#   -s, --server <ip>   DNS server to query (default: 8.8.8.8)
#   -d, --domain <dom>  Anchor %{d} macros when input is a raw record
#   -t, --tcp           Force TCP instead of UDP for dig queries
#   -q, --quiet         Errors only (suppress warnings)
#   -v, --verbose       Show the resolution trace
#   -h, --help          Show help message (or per-verb: spf <verb> -h)

_spf() (
    local SCRIPT_NAME; SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"
    case "${BASH_SOURCE[0]}" in /dev/*|/proc/*) SCRIPT_NAME="" ;; esac
    case "$SCRIPT_NAME" in ""|bash|sh|zsh|dash) SCRIPT_NAME="spf" ;; esac

    # ANSI palette for diagnostics, computed once (no per-call _color subshell):
    # empty unless stderr is a TTY (or CLICOLOR_FORCE is set) and NO_COLOR is
    # unset, so pipes/redirects and the test harness stay plain by default while
    # CLICOLOR_FORCE=1 lets a capture keep color. NO_COLOR wins when both are set.
    # https://no-color.org/
    local C_BRK=""    # brackets: dim, so the punctuation recedes
    local C_INF=""    # INF severity token: dim
    local C_WRN=""    # WRN severity token: yellow
    local C_ERR=""    # ERR severity token: red
    local C_NAME=""   # script name: cyan
    local C_SRC=""    # trace subject (the domain being resolved): green
    local C_RST=""
    if { [ -t 2 ] || [ -n "${CLICOLOR_FORCE:-}" ]; } && [ -z "${NO_COLOR:-}" ]; then
        C_BRK=$'\033[2m'
        C_INF=$'\033[2m'
        C_WRN=$'\033[33m'
        C_ERR=$'\033[31m'
        C_NAME=$'\033[36m'
        C_SRC=$'\033[32m'
        C_RST=$'\033[0m'
    fi
    # Severity prefixes assembled once. The cyan name and the ERR/WRN SEV tokens
    # stand out against the dim brackets; INF's token is itself dim (by design --
    # routine -v trace recedes), so on those lines only the name carries color.
    # The message (default fg) follows the reset.
    # Each colored span is closed with C_RST before the next begins: SGR color and
    # intensity are orthogonal and cumulative, so re-emitting C_BRK (dim) does NOT
    # clear the prior span's color -- without the reset the SEV hue bleeds through
    # the middle ][ brackets and the name. Every C_RST here is load-bearing
    local PFX_ERR="${C_BRK}[${C_RST}${C_ERR}ERR${C_RST}${C_BRK}][${C_RST}${C_NAME}${SCRIPT_NAME}${C_RST}${C_BRK}]${C_RST} "
    local PFX_WRN="${C_BRK}[${C_RST}${C_WRN}WRN${C_RST}${C_BRK}][${C_RST}${C_NAME}${SCRIPT_NAME}${C_RST}${C_BRK}]${C_RST} "
    local PFX_INF="${C_BRK}[${C_RST}${C_INF}INF${C_RST}${C_BRK}][${C_RST}${C_NAME}${SCRIPT_NAME}${C_RST}${C_BRK}]${C_RST} "

    # Trailing C_RST closes any unclosed color a message carries, so an accent
    # that runs to end-of-line can't bleed onto the next line. Empty when color
    # is off, so plain output is unchanged
    _error() { printf '%s%s%s\n' "$PFX_ERR" "$*" "$C_RST" >&2; }
    _warn()  { if [ "$VERBOSITY" -ge 1 ]; then printf '%s%s%s\n' "$PFX_WRN" "$*" "$C_RST" >&2; fi; }
    _info()  { if [ "$VERBOSITY" -ge 2 ]; then printf '%s%s%s\n' "$PFX_INF" "$*" "$C_RST" >&2; fi; }

    # _show_help [verb] -- top-level menu when no (or unknown) verb; per-verb detail otherwise
    _show_help() {
        local verb="$1"
        local s; [ -t 1 ] && s=$'\033[4m'
        local r; [ -t 1 ] && r=$'\033[24m'
        case "$verb" in
            show)
                cat <<EOF
NAME
  $SCRIPT_NAME show - print the published SPF record
SYNOPSIS
  $SCRIPT_NAME show ${s}domain${r}
  $SCRIPT_NAME ${s}domain${r}
DESCRIPTION
  Fetches the domain's TXT records and prints the published v=spf1
  record verbatim: character-strings reassembled, quotes stripped, on a
  single line. This is the record as published, NOT the recursively
  resolved tree -- use the tree verb to expand the includes. A bare
  $SCRIPT_NAME ${s}domain${r} (no verb) is shorthand for $SCRIPT_NAME show ${s}domain${r}.
  Pass -v to note when the record spans multiple character-strings.
EXIT STATUS
  0  Record printed
  1  Runtime failure / no SPF record found
  2  Usage error
  3  dig is not installed
EOF
                ;;
            find)
                cat <<EOF
NAME
  $SCRIPT_NAME find - check whether an IP is covered or an a:<host> directive is present
SYNOPSIS
  $SCRIPT_NAME find ${s}domain${r} ${s}ip${r}
  $SCRIPT_NAME find ${s}domain${r} a:${s}host${r}
DESCRIPTION
  With an IP: reports whether it is covered/listed by the record and how.
  With a:${s}host${r}: reports whether the directive is present literally
  (expected), only as a covering range or other directive (fragile), or
  absent. Resolves ${s}host${r} via dig.
EXIT STATUS
  0  IP covered, or a:host present literally
  1  Runtime failure
  2  Usage error
  3  dig is not installed
  4  Not found / absent
  5  a:host present only as covered-by-range or via another directive (fragile)
EOF
                ;;
            has)
                cat <<EOF
NAME
  $SCRIPT_NAME has - is a mechanism token present in the expanded record?
SYNOPSIS
  $SCRIPT_NAME has ${s}domain${r} ${s}token${r}
DESCRIPTION
  Recursively resolves the record and reports every occurrence of the
  exact ${s}token${r} (e.g. include:_spf.example.com) with its source record,
  depth, and qualifier. Token-aware: include:site.com does not match
  include:site.com.attacker.example. For a:${s}host${r}, find is the richer check.
EXIT STATUS
  0  Present
  1  Runtime failure
  2  Usage error
  3  dig is not installed
  4  Absent
EOF
                ;;
            ir)
                cat <<EOF
NAME
  $SCRIPT_NAME ir - print the raw resolver IR (tab-delimited)
SYNOPSIS
  $SCRIPT_NAME ir ${s}domain${r}
DESCRIPTION
  Emits one row per mechanism: depth, source_domain, qualifier,
  mechanism, value, lookup_cost (tab-separated). Stable column layout
  for piping: $SCRIPT_NAME ir example.com | awk -F'\t' '\$4=="include"'
EXIT STATUS
  0  Rendered
  1  Runtime failure
  2  Usage error
  3  dig is not installed
EOF
                ;;
            flatten)
                cat <<EOF
NAME
  $SCRIPT_NAME flatten - print every IP/CIDR the record authorizes
SYNOPSIS
  $SCRIPT_NAME flatten ${s}domain${r} [-r|--record]
DESCRIPTION
  Resolves the full include tree and prints each ip4/ip6 address, sorted
  and deduped, one per line. --record emits a single quoted TXT record
  string instead. See $SCRIPT_NAME -h for the staleness caveat.
EXIT STATUS
  0  Rendered
  1  Runtime failure
  2  Usage error
  3  dig is not installed
EOF
                ;;
            check)
                cat <<EOF
NAME
  $SCRIPT_NAME check - RFC 7208 health report
SYNOPSIS
  $SCRIPT_NAME check ${s}domain${r}
DESCRIPTION
  Counts DNS lookups (limit 10) and void lookups (limit 2), and flags
  +all, multiple all in the record, and deprecated ptr usage.
EXIT STATUS
  0  Clean
  1  Runtime failure
  2  Usage error
  3  dig is not installed
  4  Problems found
EOF
                ;;
            tree)
                cat <<EOF
NAME
  $SCRIPT_NAME tree - indented structural view of the include tree
SYNOPSIS
  $SCRIPT_NAME tree ${s}domain${r}
DESCRIPTION
  Prints each mechanism indented by include depth, so delegation
  boundaries and nesting are visible at a glance.
EXIT STATUS
  0  Rendered
  1  Runtime failure
  2  Usage error
  3  dig is not installed
EOF
                ;;
            *)
                cat <<EOF
NAME
  $SCRIPT_NAME - resolve and inspect SPF DNS records
SYNOPSIS
  $SCRIPT_NAME [${s}options${r}] show    ${s}domain${r}
  $SCRIPT_NAME [${s}options${r}] find    ${s}domain${r} {${s}ip${r}|a:${s}host${r}}
  $SCRIPT_NAME [${s}options${r}] has     ${s}domain${r} ${s}token${r}
  $SCRIPT_NAME [${s}options${r}] flatten ${s}domain${r}
  $SCRIPT_NAME [${s}options${r}] check   ${s}domain${r}
  $SCRIPT_NAME [${s}options${r}] tree    ${s}domain${r}
  $SCRIPT_NAME [${s}options${r}] ir      ${s}domain${r}
  $SCRIPT_NAME ${s}domain${r}
  $SCRIPT_NAME ${s}verb${r} -h
DESCRIPTION
  Fetches and recursively resolves SPF TXT records. A bare
  $SCRIPT_NAME ${s}domain${r} (no verb) prints the published record (show). Verbs:
    show     print the published SPF record verbatim
    find     is an IP covered, or an a:host directive present? (and how)
    has      is a token present in the expanded record? (and where)
    flatten  print all authorized IPs/CIDRs
    check    RFC 7208 health report
    tree     indented structural view
    ir       raw tab-delimited resolver output
OPTIONS
  -s, --server ${s}ip${r}   DNS server to query (default: 8.8.8.8)
  -d, --domain ${s}dom${r}  Anchor %{d} macros when input is a raw record
  -t, --tcp         Force TCP instead of UDP for dig queries
  -r, --record      (flatten only) Emit a single quoted TXT record
  -q, --quiet       Errors only (suppress warnings)
  -v, --verbose     Show the resolution trace ([INF] lines)
  -h, --help        Show this help message (or per-verb: $SCRIPT_NAME ${s}verb${r} -h)
DEPENDENCIES
  dig
  python3 (IPv6 matching only)
EXIT STATUS
  0  Success (affirmative)
  1  Runtime failure (network error, dig returned unexpected output)
  2  Usage error (missing arg, unknown flag, bad flag value)
  3  dig is not installed
  4  Negative predicate result (not found / problems found)
  5  find a:host present only as covered-by-range (fragile)
EOF
                ;;
        esac
    }

    _expand_short_opts() {
        # $1 = string of short-opt letters that take a value (e.g. "nXHd"); "" for flag-only scripts
        # $2..$N = "$@"
        # Populates _EXPANDED; caller does: set -- "${_EXPANDED[@]}"; unset _EXPANDED
        local value_opts="$1"; shift
        _EXPANDED=()
        local passthru=""
        local arg
        local rest
        local c
        for arg in "$@"; do
            if [ -n "$passthru" ]; then _EXPANDED+=("$arg"); continue; fi
            case "$arg" in
                --)          passthru=1; _EXPANDED+=("$arg") ;;
                --*|-|"")    _EXPANDED+=("$arg") ;;
                -[a-zA-Z]?*)
                    rest="${arg#-}"
                    while [ -n "$rest" ]; do
                        c="${rest%"${rest#?}"}"; rest="${rest#?}"
                        _EXPANDED+=("-$c")
                        case "$value_opts" in *"$c"*)
                            [ -n "$rest" ] && _EXPANDED+=("$rest")
                            rest="" ;;
                        esac
                    done ;;
                *)           _EXPANDED+=("$arg") ;;
            esac
        done
    }

    # --- resolver engine ---

    # Reassemble dig TXT output into a single SPF record: join the " " boundaries
    # between character-strings (a string caps at 255 bytes, so long records are
    # split), drop the surrounding quotes, keep only the v=spf1 record. Reads
    # stdin, writes one line. A record with no quotes (already-clean input) passes
    # the sed through unchanged, so this is safe to apply to bare records too
    _normalize_txt() {
        sed 's/" "//g; s/"//g' \
          | grep -i '^v=spf1' \
          | head -n1
    }

    _dig_txt() {
        local name="$1"
        local tcp; [ "$USE_TCP" ] && tcp="+tcp"
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; the split is intentional
        dig @"$SERVER" $tcp +short TXT "$name" 2>/dev/null | _normalize_txt
    }

    _spf_input() {
        local a="$1"
        case "$a" in
            "v=spf1"*) printf '%s\n' "$a" ;;
            # stdin: normalize like the domain path, so piping raw `dig +short TXT`
            # output (quoted, possibly multi-string) into any verb works the same
            # as a domain lookup. A clean record passes through untouched
            -)         _normalize_txt ;;
            *)         _dig_txt "$a" ;;
        esac
    }

    # Print one IR row
    _ir_row() { printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" "$5" "$6"; }

    # Print a host's A then AAAA addresses, one per line (empty if none)
    _resolve_host() {
        local host="$1"
        local tcp; [ "$USE_TCP" ] && tcp="+tcp"
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; splitting dig short output on whitespace is intended
        dig @"$SERVER" $tcp +short A "$host" 2>/dev/null
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; splitting dig short output on whitespace is intended
        dig @"$SERVER" $tcp +short AAAA "$host" 2>/dev/null
    }

    # _emit_host_ips <token> <mech> <src> <depth> <qual>
    _emit_host_ips() {
        local token="$1"
        local mech="$2"
        local src="$3"
        local depth="$4"
        local qual="$5"
        local host
        case "$token" in
            "$mech")      host="$src" ;;        # bare a / mx -> the current domain
            "$mech":*)    host="${token#"$mech":}"; host="${host%%/*}" ;;
            "$mech"/*)    host="$src" ;;         # a/24 dual-cidr on current domain
        esac
        # cost row for the mechanism itself (1 lookup)
        _ir_row "$depth" "$src" "$qual" "$mech" "$host" 1
        local ip
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting dig short output on whitespace is intended
        for ip in $(_resolve_host "$host"); do
            case "$ip" in
                *:*) _ir_row "$depth" "$src" "$qual" ip6 "$ip" 0 ;;
                *)   _ir_row "$depth" "$src" "$qual" ip4 "$ip" 0 ;;
            esac
        done
    }

    # _resolve_rec <record-string> <source_domain> <depth> <ancestor-path>
    _resolve_rec() {
        local record="$1"
        local src="$2"
        local depth="$3"
        local ancestors="$4"
        _info "${C_SRC}${src}${C_RST}: $record"

        local token
        local qual
        local target
        # strip leading "v=spf1" by splitting the record on spaces (intentional word-split)
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting an SPF record on whitespace is intended
        set -- $record
        shift   # drop v=spf1
        for token in "$@"; do
            # split qualifier
            qual="+"
            case "$token" in [+~?-]*) qual="${token%%[!+~?-]*}"; token="${token#?}" ;; esac
            case "$token" in
                ip4:*)      _ir_row "$depth" "$src" "$qual" ip4 "${token#ip4:}" 0 ;;
                ip6:*)      _ir_row "$depth" "$src" "$qual" ip6 "${token#ip6:}" 0 ;;
                all)        _ir_row "$depth" "$src" "$qual" all "" 0 ;;
                include:*)  target="${token#include:}"
                            _ir_row "$depth" "$src" "$qual" include "$target" 1
                            _walk_into "$target" "$depth" "$ancestors" ;;
                redirect=*) target="${token#redirect=}"
                            _ir_row "$depth" "$src" "$qual" redirect "$target" 1
                            _walk_into "$target" "$depth" "$ancestors" ;;
                a|a:*|a/*)      _emit_host_ips "$token" a  "$src" "$depth" "$qual" ;;
                mx|mx:*|mx/*)   _emit_host_ips "$token" mx "$src" "$depth" "$qual" ;;
                exists:*)   _ir_row "$depth" "$src" "$qual" exists "${token#exists:}" 1 ;;
                ptr)        _ir_row "$depth" "$src" "$qual" ptr "" 1 ;;
                ptr:*)      _ir_row "$depth" "$src" "$qual" ptr "${token#ptr:}" 1 ;;
                v=spf1)     ;;   # already shifted, but be safe
                *)          ;;   # unknown token: ignore (verify's job, not ours)
            esac
        done
    }

    # follow include/redirect with cycle + cap guards
    _walk_into() {
        local target="$1"
        local parent_depth="$2"
        local ancestors="$3"
        case " $ancestors " in *" $target "*) return 0 ;; esac   # cycle: skip
        if [ "$parent_depth" -ge 20 ]; then return 0; fi          # depth cap
        local sub; sub="$(_dig_txt "$target")"
        [ "$sub" ] || {
            _info "no SPF record for ${C_SRC}${target}${C_RST}"
            # void lookup: a queried name returned no SPF record. check counts these
            _ir_row "$((parent_depth + 1))" "$target" "+" void "$target" 0
            return 0
        }
        _resolve_rec "$sub" "$target" "$((parent_depth + 1))" "$ancestors $target"
    }

    _resolve() {
        local arg="$1"
        local anchor="${2:-$DOMAIN_ANCHOR}"
        local root; root="$(_spf_input "$arg")"
        if [ -z "$root" ]; then
            _error "No SPF record found for $arg"
            return 1
        fi
        local rootsrc="$arg"
        case "$arg" in "v=spf1"*|-) rootsrc="${anchor:-<record>}" ;; esac
        _resolve_rec "$root" "$rootsrc" 0 "$rootsrc"
    }

    # --- IPv4 and IPv6 CIDR helpers ---

    _ip4_to_int() {
        local IFS=.
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- intentional split of dotted-quad on '.'
        set -- $1
        [ $# -eq 4 ] || return 2
        local o
        for o in "$@"; do
            case "$o" in ''|*[!0-9]*) return 2 ;; esac
            [ "$o" -le 255 ] || return 2
        done
        printf '%s\n' "$(( ($1 << 24) | ($2 << 16) | ($3 << 8) | $4 ))"
    }

    _ip4_in_cidr() {
        local ip="$1"
        local cidr="$2"
        local net="${cidr%/*}"
        local prefix
        case "$cidr" in */*) prefix="${cidr#*/}" ;; *) prefix=32 ;; esac
        case "$prefix" in ''|*[!0-9]*) return 2 ;; esac
        [ "$prefix" -le 32 ] || return 2

        local ipi; ipi="$(_ip4_to_int "$ip")" || return 2
        local neti; neti="$(_ip4_to_int "$net")" || return 2

        local mask
        if [ "$prefix" -eq 0 ]; then
            mask=0
        else
            mask=$(( (0xFFFFFFFF << (32 - prefix)) & 0xFFFFFFFF ))
        fi
        [ $(( ipi & mask )) -eq $(( neti & mask )) ]
    }

    _ip6_in_cidr() {
        local ip="$1"
        local cidr="$2"
        command -v python3 >/dev/null 2>&1 || return 2
        python3 -c 'import ipaddress,sys
try:
    sys.exit(0 if ipaddress.ip_address(sys.argv[1]) in ipaddress.ip_network(sys.argv[2], strict=False) else 4)
except ValueError:
    sys.exit(2)' "$ip" "$cidr"
    }

    # _find_hit <ip> <src> <qual> <mech> <value> -- print a mechanism-appropriate match line
    _find_hit() {
        local ip="$1"
        local src="$2"
        local qual="$3"
        local mech="$4"
        local val="$5"
        local verb
        case "$mech" in
            ip4|ip6)
                # exact host (no prefix, or /32 v4, or /128 v6) -> "listed in"; a shorter prefix -> "covered by"
                case "$val" in
                    */32|*/128) verb="is listed in" ;;
                    */*)        verb="is covered by" ;;
                    *)          verb="is listed in" ;;
                esac ;;
            a|mx)     verb="matches" ;;
            exists)   verb="matches" ;;
            *)        verb="matches" ;;
        esac
        printf '%s %s %s:%s in %s (qualifier: %s)\n' "$ip" "$verb" "$mech" "$val" "$src" "$qual"
    }

    # Expand IP/domain-derivable macros. Returns 1 if an unsupported macro appears
    _expand_macro() {
        local s="$1"
        local qip="$2"
        local dom="$3"
        # shellcheck disable=SC1083 # "This { is literal." -- the { is intentional in the glob; case pattern matches literal %{s/l/o/h/p
        case "$s" in *%{[slohp]*) return 1 ;; esac   # sender/HELO/ptr macros: unsupported

        local i_exp
        local ir_exp
        local v_exp
        case "$qip" in
            *:*) i_exp="$qip"; v_exp="ip6"; ir_exp="$qip" ;;   # v6 nibble form omitted; v4 is the common case
            *)   i_exp="$qip"; v_exp="in-addr"
                 local IFS=.
                 # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting a dotted-quad for the %{ir} reverse transform
                 set -- $qip; ir_exp="$4.$3.$2.$1" ;;
        esac
        s="${s//%{ir\}/$ir_exp}"
        s="${s//%{i\}/$i_exp}"
        s="${s//%{d\}/$dom}"
        s="${s//%{v\}/$v_exp}"
        s="${s//%%/%}"
        s="${s//%_/ }"
        s="${s//%-/%20}"
        printf '%s\n' "$s"
    }

    # --- verb implementations and their helpers ---

    # _resolve_one <host> <fam:4|6> -- first A (fam 4) or AAAA (fam 6) address of host, or empty
    _resolve_one() {
        local host="$1"
        local fam="$2"
        local qtype; [ "$fam" = 6 ] && qtype=AAAA || qtype=A
        local tcp; [ "$USE_TCP" ] && tcp="+tcp"
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; the split is intentional
        dig @"$SERVER" $tcp +short "$qtype" "$host" 2>/dev/null | head -n1
    }

    # _find_a_host <ir> <host> <input-domain> -- evaluate an a:<host> query.
    # exit 0 literal present / 5 fragile (covered by range or other directive) / 4 absent
    _find_a_host() {
        local ir="$1"
        local host="$2"
        local input="$3"
        local rc
        local warned_py=""

        # (a) literal a:<host> row present?
        local lit; lit="$(printf '%s\n' "$ir" | awk -F'\t' -v h="$host" '$4=="a" && $5==h{print; exit}')"
        if [ -n "$lit" ]; then
            local src; src="$(printf '%s\n' "$lit" | cut -f2)"
            local qual; qual="$(printf '%s\n' "$lit" | cut -f3)"
            printf '%s matches a:%s in %s (qualifier: %s)\n' "$host" "$host" "$src" "$qual"
            # dangling check: literal present but host resolves to nothing
            if [ -z "$(_resolve_host "$host")" ]; then
                _warn "a:$host is present but the host resolves to no addresses (dead directive)"
            fi
            return 0
        fi

        # resolve the host for coverage checks (b/c)
        local addrs; addrs="$(_resolve_host "$host")"
        if [ -n "$addrs" ]; then
            local addr
            # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting the newline-separated address list is intended
            for addr in $addrs; do
                local fam; case "$addr" in *:*) fam=6 ;; *) fam=4 ;; esac
                # walk IR rows; first covering ip4/ip6 (b) or a/mx-for-other-host (c) wins
                local depth
                local src
                local qual
                local mech
                local val
                local cost
                local _row
                # IFS-whitespace (TAB) merges consecutive separators, collapsing an empty
                # value field. Peel-split each row so empty fields are preserved.
                # shellcheck disable=SC2034 # "cost appears unused. Verify use (or export if used externally)." -- cost is read from the IR to keep field alignment but not used in this consumer
                while IFS= read -r _row; do
                    depth="${_row%%$'\t'*}";  _row="${_row#*$'\t'}"
                    src="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
                    qual="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
                    mech="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
                    val="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
                    cost="${_row}"
                    case "$mech" in
                        ip4) [ "$fam" = 4 ] || continue
                             if _ip4_in_cidr "$addr" "$val"; then
                                 printf '%s is NOT present literally, but its address %s is covered by ip4:%s in %s -- fragile: a flattened range does not self-heal if the host renumbers\n' "a:$host" "$addr" "$val" "$src"
                                 return 5
                             fi ;;
                        ip6) [ "$fam" = 6 ] || continue
                             _ip6_in_cidr "$addr" "$val"
                             rc=$?
                             if [ "$rc" -eq 0 ]; then
                                 printf '%s is NOT present literally, but its address %s is covered by ip6:%s in %s -- fragile: a flattened range does not self-heal if the host renumbers\n' "a:$host" "$addr" "$val" "$src"
                                 return 5
                             elif [ "$rc" -eq 2 ]; then
                                 [ "$warned_py" ] || { _warn "python3 not found; IPv6 matching is literal-only"; warned_py=1; }
                             fi ;;
                        a|mx) # case (c): IP shared with a different directive's host
                             if [ "$val" != "$host" ] && [ "$addr" = "$(_resolve_one "$val" "$fam")" ]; then
                                 printf '%s is NOT present literally; its address %s is covered by %s:%s in %s, not your directive\n' "a:$host" "$addr" "$mech" "$val" "$src"
                                 return 5
                             fi ;;
                    esac
                done <<EOF
$ir
EOF
            done
        fi

        # (d) absent
        printf '%s not found in %s'"'"'s SPF record\n' "a:$host" "$input"
        return 4
    }

    _cmd_show() {
        local input=""
        local extra=""
        local arg
        for arg in "$@"; do
            case "$arg" in
                -)  if [ -z "$input" ]; then input="$arg"; else extra="$arg"; fi ;;  # stdin sentinel: keep it, so show's raw/stdin guard can reject it
                -*) ;;   # global opts already consumed; ignore strays
                *)  if [ -z "$input" ]; then input="$arg"; else extra="$arg"; fi ;;
            esac
        done
        if [ -z "$input" ]; then
            _error "Must provide a domain. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        # A second positional is almost certainly a find query (spf domain ip);
        # show takes exactly one domain, so steer to the verb they likely meant
        if [ -n "$extra" ]; then
            _error "show takes a single domain. Did you mean \`$SCRIPT_NAME find $input $extra\`? Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        # show prints what is *published*; a raw record or stdin has nothing to
        # fetch. Redirect to check, which exists to vet a record in hand
        case "$input" in
            "v=spf1"*|-)
                _error "show fetches a published record; pass a domain, not a record (to vet a record, use \`$SCRIPT_NAME check\`). Run \`$SCRIPT_NAME -h\` for usage"
                return 2 ;;
        esac

        local tcp; [ "$USE_TCP" ] && tcp="+tcp"
        local raw
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; the split is intentional
        raw="$(dig @"$SERVER" $tcp +short TXT "$input" 2>/dev/null)"

        # Reassemble: join multi-string boundaries, strip quotes, keep v=spf1
        # records (same transform _dig_txt applies; inlined here so the quoted
        # raw form survives for the -v character-string count below)
        local records; records="$(printf '%s\n' "$raw" | sed 's/" "//g; s/"//g' | grep -i '^v=spf1')"
        if [ -z "$records" ]; then
            _error "No SPF record found for $input"
            return 1
        fi

        # Multiple published v=spf1 records are an RFC 7208 permerror. Show the
        # first and flag the rest, rather than merging them into one mangled line
        local n; n="$(printf '%s\n' "$records" | grep -c .)"
        [ "$n" -gt 1 ] && _warn "multiple published SPF records (RFC 7208 permerror); showing the first"

        printf '%s\n' "$records" | head -n1

        # -v: note when the record was published as multiple character-strings (a
        # string caps at 255 bytes, so long records are split). The reassembled
        # form hides this; count quotes on the raw quoted line to recover it
        if [ "$VERBOSITY" -ge 2 ]; then
            local rawline; rawline="$(printf '%s\n' "$raw" | grep -i '^"v=spf1' | head -n1)"
            local nstr; nstr=$(( $(printf '%s' "$rawline" | tr -dc '"' | wc -c) / 2 ))
            # if (not &&): a false test as the function's last statement would
            # leak exit status 1 even though the record printed fine
            if [ "$nstr" -gt 1 ]; then _info "published as $nstr character-strings"; fi
        fi
    }
    _cmd_find() {
        local input=""
        local ip=""
        local arg
        for arg in "$@"; do
            case "$arg" in
                -*) ;;   # global opts already consumed; ignore strays
                *)  if [ -z "$input" ]; then input="$arg"; else ip="$arg"; fi ;;
            esac
        done
        if [ -z "$input" ]; then
            _error "Must provide a domain or record. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        if [ -z "$ip" ]; then
            _error "ip or a:<host> is required. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        # Reject ambiguous ip4:/ip6: query inputs (spec 4.4)
        case "$ip" in
            ip4:*|ip6:*)
                _error "find does not take ip4:/ip6: queries (ambiguous). Use a bare IP for membership, \`has\` for token presence, or \`ir | grep\` for a literal scan. Run \`$SCRIPT_NAME -h\` for usage"
                return 2 ;;
        esac

        local ir; ir="$(_resolve "$input")" || return 1

        # a:<host> query -> presence/coverage evaluation (spec 4.2-4.3)
        case "$ip" in
            a:*) _find_a_host "$ir" "${ip#a:}" "$input"; return $? ;;
        esac

        local family; case "$ip" in *:*) family=6 ;; *) family=4 ;; esac
        local warned_py=""

        # Walk rows in order; first containing CIDR wins
        local depth
        local src
        local qual
        local mech
        local val
        local cost
        local rc
        local _row
        # IFS-whitespace (TAB) merges consecutive separators, collapsing an empty
        # value field. Peel-split each row so empty fields are preserved.
        # shellcheck disable=SC2034 # "cost appears unused. Verify use (or export if used externally)." -- cost is read from the IR to keep field alignment but not used in this consumer
        while IFS= read -r _row; do
            depth="${_row%%$'\t'*}";  _row="${_row#*$'\t'}"
            src="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            qual="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            mech="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            val="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            cost="${_row}"
            case "$mech" in
                ip4)
                    [ "$family" = 4 ] || continue
                    if _ip4_in_cidr "$ip" "$val"; then _find_hit "$ip" "$src" "$qual" "$mech" "$val"; return 0; fi ;;
                ip6)
                    [ "$family" = 6 ] || continue
                    _ip6_in_cidr "$ip" "$val"; rc=$?
                    if [ "$rc" -eq 0 ]; then _find_hit "$ip" "$src" "$qual" "$mech" "$val"; return 0
                    elif [ "$rc" -eq 2 ]; then
                        [ "$warned_py" ] || { _warn "python3 not found; IPv6 matching is literal-only"; warned_py=1; }
                        [ "$ip" = "$val" ] && { _find_hit "$ip" "$src" "$qual" "$mech" "$val"; return 0; }
                    fi ;;
                exists)
                    local name; if name="$(_expand_macro "$val" "$ip" "$src")"; then
                        local tcp; [ "$USE_TCP" ] && tcp="+tcp"
                        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- optional +tcp flag; split is intentional
                        if [ -n "$(dig @"$SERVER" $tcp +short A "$name" 2>/dev/null)" ]; then
                            _find_hit "$ip" "$src" "$qual" exists "$val"; return 0
                        fi
                    else
                        _warn "cannot statically evaluate exists ($val)"
                    fi ;;
            esac
        done <<EOF
$ir
EOF

        printf '%s\n' "$ip not found in $input's SPF record"
        return 4
    }
    _cmd_has() {
        local input=""
        local token=""
        local arg
        for arg in "$@"; do
            case "$arg" in
                -*) ;;   # global opts already consumed; ignore strays
                *)  if [ -z "$input" ]; then input="$arg"; else token="$arg"; fi ;;
            esac
        done
        if [ -z "$input" ]; then
            _error "Must provide a domain or record. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        if [ -z "$token" ]; then
            _error "Must provide a token to search for (e.g. include:_spf.example.com). Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi

        # parse the query token: strip leading qualifier, split mech:value on first : or =
        local qtok="$token"
        case "$qtok" in [+~?-]*) qtok="${qtok#?}" ;; esac
        local qmech="${qtok%%[:=]*}"
        local qval=""
        case "$qtok" in *[:=]*) qval="${qtok#*[:=]}" ;; esac
        if [ -z "$qval" ]; then
            _error "Token must have a value (e.g. include:domain, a:host). Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi

        local ir; ir="$(_resolve "$input")" || return 1

        # scan IR for exact mech+value matches; report all with provenance
        local found=0
        local depth
        local src
        local qual
        local mech
        local val
        local cost
        local _row
        # shellcheck disable=SC2034 # "cost appears unused. Verify use (or export if used externally)." -- cost is read from the IR to keep field alignment but not used in this consumer
        while IFS= read -r _row; do
            depth="${_row%%$'\t'*}";  _row="${_row#*$'\t'}"
            src="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            qual="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            mech="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            val="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            cost="${_row}"
            [ "$mech" = void ] && continue
            if [ "$mech" = "$qmech" ] && [ "$val" = "$qval" ]; then
                if [ "$found" -eq 0 ]; then printf 'PRESENT: %s:%s\n' "$qmech" "$qval"; fi
                printf '  in %s (depth %s, qualifier: %s)\n' "$src" "$depth" "$qual"
                found=1
            fi
        done <<EOF
$ir
EOF

        if [ "$found" -eq 0 ]; then
            printf 'ABSENT: %s:%s not found in %s'"'"'s SPF tree\n' "$qmech" "$qval" "$input"
            return 4
        fi
        return 0
    }
    _cmd_check() {
        local input="$1"
        if [ -z "$input" ]; then
            _error "Must provide a domain or record. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        local raw=""; case "$input" in "v=spf1"*|-) raw=1 ;; esac

        local ir; ir="$(_resolve "$input")" || return 1
        local problems=0

        # lookup count: sum of field 6 (lookup_cost) across the resolved tree
        local lookups; lookups="$(printf '%s\n' "$ir" | awk -F'\t' '{s+=$6} END{print s+0}')"
        printf 'DNS lookups: %s/10\n' "$lookups"
        if [ "$lookups" -gt 10 ]; then
            printf '  PROBLEM: exceeds RFC 7208 limit of 10\n'; problems=1
        fi

        # void lookups: count rows whose mechanism is the resolver's void sentinel
        local voids; voids="$(printf '%s\n' "$ir" | awk -F'\t' '$4=="void"' | grep -c .)"
        printf 'Void lookups: %s/2\n' "$voids"
        if [ "$voids" -gt 2 ]; then
            printf '  PROBLEM: exceeds void-lookup limit of 2\n'; problems=1
        fi

        # +all: any all mechanism with a pass qualifier authorizes the whole internet
        if printf '%s\n' "$ir" | awk -F'\t' '$4=="all" && $3=="+"' | grep -q .; then
            printf '  PROBLEM: +all authorizes the entire internet\n'; problems=1
        fi
        # multiple all -- ROOT record only (depth 0). Counting tree-wide or
        # per-source false-flags a clean diamond: a single-all record reached
        # via two parents emits two identical all rows, and the frozen IR can't
        # tell that from a genuine two-all record. Depth 0 is walked once, so
        # it's unambiguous -- it's the record actually being checked
        local root_alln; root_alln="$(printf '%s\n' "$ir" | awk -F'\t' '$1=="0" && $4=="all"' | grep -c .)"
        [ "$root_alln" -gt 1 ] && { printf '  PROBLEM: multiple all mechanisms in the record\n'; problems=1; }
        # ptr present: deprecated by RFC 7208 (SHOULD NOT be used)
        if printf '%s\n' "$ir" | awk -F'\t' '$4=="ptr"' | grep -q .; then
            printf '  WARNING: ptr is deprecated (RFC 7208 SHOULD NOT)\n'; problems=1
        fi

        # record count: domain mode only. In raw-record mode exactly one record was
        # supplied, so the 0/>1 published-record lint is not applicable
        if [ "$raw" ]; then
            printf 'Record count: N/A (raw-record input)\n'
        else
            # Re-query TXT ourselves (the resolver's count is lost in a subshell) and
            # count v=spf1 records. 0 records can't reach here: _resolve already
            # failed above. >1 is a permerror per RFC 7208
            local tcp; [ "$USE_TCP" ] && tcp="+tcp"
            local rec_count
            # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $tcp expands to +tcp or empty; the split is intentional
            rec_count="$(dig @"$SERVER" $tcp +short TXT "$input" 2>/dev/null | sed 's/" "//g; s/"//g' | grep -ic '^v=spf1')"
            printf 'Published SPF records: %s\n' "$rec_count"
            if [ "$rec_count" -gt 1 ]; then
                printf '  PROBLEM: multiple published SPF records (RFC 7208 permerror)\n'; problems=1
            fi
        fi

        if [ "$problems" -eq 0 ]; then
            printf 'OK: no problems found\n'; return 0
        fi
        return 4
    }
    _cmd_tree() {
        local input="$1"
        if [ -z "$input" ]; then
            _error "Must provide a domain or record. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        local ir; ir="$(_resolve "$input")" || return 1

        local depth
        local src
        local qual
        local mech
        local val
        local cost
        local indent
        local label
        local _row
        # IFS-whitespace (TAB) merges consecutive separators, collapsing an empty
        # value field. Peel-split each row so empty fields are preserved.
        # shellcheck disable=SC2034 # "cost appears unused. Verify use (or export if used externally)." -- cost is read from the IR to keep field alignment but not used in this consumer
        while IFS= read -r _row; do
            depth="${_row%%$'\t'*}";  _row="${_row#*$'\t'}"
            src="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            qual="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            mech="${_row%%$'\t'*}";   _row="${_row#*$'\t'}"
            val="${_row%%$'\t'*}";    _row="${_row#*$'\t'}"
            cost="${_row}"
            [ "$mech" = void ] && continue
            indent="$(printf '%*s' "$(( depth * 4 + 2 ))" '')"
            case "$mech" in
                all)    label="${qual}all" ;;
                *)      label="$mech${val:+:$val}" ;;
            esac
            printf '%s%s\n' "$indent" "$label"
        done <<EOF
$ir
EOF
    }

    _chunk_record() {
        local full="$1"
        local out=""
        local cur=""
        local tok
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting record tokens on whitespace is intended
        for tok in $full; do
            if [ -z "$cur" ]; then
                cur="$tok"
            elif [ $(( ${#cur} + ${#tok} + 1 )) -le 255 ]; then
                cur="$cur $tok"
            else
                out="$out \"$cur\""
                cur="$tok"
            fi
        done
        [ "$cur" ] && out="$out \"$cur\""
        printf '%s\n' "${out# }"
    }

    _cmd_flatten() {
        local record_mode=""
        local input=""
        local arg
        for arg in "$@"; do
            case "$arg" in
                -r|--record) record_mode=1 ;;
                *) input="$arg" ;;
            esac
        done
        if [ -z "$input" ]; then
            _error "Must provide a domain or record. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi

        local ir; ir="$(_resolve "$input")" || return 1

        # note unevaluable mechanisms
        local exists_n; exists_n="$(printf '%s\n' "$ir" | awk -F'\t' '$4=="exists"' | grep -c .)"
        local ptr_n;    ptr_n="$(printf '%s\n' "$ir" | awk -F'\t' '$4=="ptr"' | grep -c .)"
        [ "$exists_n" -gt 0 ] && _warn "cannot statically evaluate exists ($exists_n occurrence(s))"
        [ "$ptr_n" -gt 0 ]    && _warn "cannot statically evaluate ptr ($ptr_n occurrence(s))"

        # collect addresses: ip4 then ip6, each sorted+deduped
        local v4; v4="$(printf '%s\n' "$ir" | awk -F'\t' '$4=="ip4"{print $5}' | sort -u -t. -k1,1n -k2,2n -k3,3n -k4,4n)"
        local v6; v6="$(printf '%s\n' "$ir" | awk -F'\t' '$4=="ip6"{print $5}' | sort -u)"

        if [ -z "$record_mode" ]; then
            [ "$v4" ] && printf '%s\n' "$v4"
            [ "$v6" ] && printf '%s\n' "$v6"
            return 0
        fi

        # --record: build mechanisms, find the root all qualifier, chunk <=255 bytes
        local allq; allq="$(printf '%s\n' "$ir" | awk -F'\t' '$1=="0" && $4=="all"{print $3; exit}')"
        local all_mech="${allq:-~}all"
        local mechs=""
        local ip
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting the newline/space-separated address list is intended
        for ip in $v4; do mechs="$mechs ip4:$ip"; done
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- splitting the newline/space-separated address list is intended
        for ip in $v6; do mechs="$mechs ip6:$ip"; done
        _chunk_record "v=spf1$mechs $all_mech"
    }

    # --- defaults and parse arguments ---
    local SERVER="8.8.8.8"
    local DOMAIN_ANCHOR=""
    local USE_TCP=""
    local VERBOSITY=1
    local WANT_HELP=""
    local -a args=()

    _expand_short_opts "sd" "$@"
    set -- "${_EXPANDED[@]}"; unset _EXPANDED

    while [ $# -gt 0 ]; do
        case "$1" in
            -h|--help)
                # defer: a verb may follow (spf -h find) or precede (spf find -h).
                # acting now would show top-level help before the verb is read
                case "${2-}" in
                    show|find|has|flatten|check|tree|ir) _show_help "$2"; return 0 ;;
                    *) WANT_HELP=1; shift ;;
                esac ;;
            -s|--server)
                [ -n "${2-}" ] || { _error "--server requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                SERVER="$2"; shift 2 ;;
            --server=*)
                SERVER="${1#*=}"
                [ -n "$SERVER" ] || { _error "--server requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                shift ;;
            -d|--domain)
                [ -n "${2-}" ] || { _error "--domain requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                DOMAIN_ANCHOR="$2"; shift 2 ;;
            --domain=*)
                DOMAIN_ANCHOR="${1#*=}"
                [ -n "$DOMAIN_ANCHOR" ] || { _error "--domain requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                shift ;;
            -t|--tcp) USE_TCP=1; shift ;;
            -q|--quiet)   VERBOSITY=0; shift ;;
            -v|--verbose) VERBOSITY=2; shift ;;
            --) shift; while [ $# -gt 0 ]; do args+=("$1"); shift; done ;;
            *) args+=("$1"); shift ;;
        esac
    done

    if ! command -v dig >/dev/null 2>&1; then
        _error "dig is required"
        return 3
    fi

    local verb="${args[0]}"
    local -a rest; rest=("${args[@]:1}")

    # help routing: per-verb help if a verb is in play, else top-level.
    # -h among a verb's own args (spf find -h) is treated as "show my help"
    local a
    local verb_help=""
    for a in "${rest[@]}"; do
        case "$a" in -h|--help) verb_help=1 ;; esac
    done
    if [ -n "$verb" ] && { [ -n "$verb_help" ] || [ -n "$WANT_HELP" ]; }; then
        _show_help "$verb"; return 0
    fi
    if [ -z "$verb" ]; then
        if [ -n "$WANT_HELP" ]; then _show_help; return 0; fi
        _error "Must provide a verb (show|find|has|flatten|check|tree|ir) or a domain. Run \`$SCRIPT_NAME -h\` for usage"
        return 2
    fi
    case "$verb" in
        show)    _cmd_show    "${rest[@]}" ;;
        find)    _cmd_find    "${rest[@]}" ;;
        has)     _cmd_has     "${rest[@]}" ;;
        flatten) _cmd_flatten "${rest[@]}" ;;
        check)   _cmd_check   "${rest[@]}" ;;
        tree)    _cmd_tree    "${rest[@]}" ;;
        ir)      _resolve     "${rest[@]}" ;;
        # __ip4: test-only -- exercises _ip4_in_cidr directly
        __ip4)   _ip4_in_cidr "${rest[@]}"; return $? ;;
        # Bare `spf <domain>` (no verb) is shorthand for `spf show <domain>`.
        # Route to show when the lone arg looks like an SPF *subject* -- a domain
        # (has a dot), a raw record (v=spf1...), or stdin (-) -- so plain
        # `spf example.com` works, and a bare raw/stdin call still reaches show's
        # redirect-to-check message instead of a bare "Unknown argument". A token
        # that is none of these is far likelier a mistyped verb, so keep the sharp
        # error. The whole arg (verb + rest) is forwarded so `spf domain ip` lands
        # in show's two-positional guard ("did you mean find")
        *.*|v=spf1*|-) _cmd_show "$verb" "${rest[@]}" ;;
        *) _error "Unknown argument '$verb'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
    esac
)

_spf "$@"
__spf_rc=$?
unset -f _spf
if [ -n "${BASH_SOURCE[0]}" ] && [ "${BASH_SOURCE[0]}" != "$0" ]; then
    eval "unset __spf_rc; return $__spf_rc"
fi
eval "unset __spf_rc; exit $__spf_rc"