@spec discover(Sovite.DNS.resolver(), String.t()) ::
  {:ok, id :: String.t()}
  | {:error, record_error() | {:dns, Sovite.DNS.Resolver.error()}}

Looks up the TXT records at _mta-sts.<domain> and returns the policy id, as parse_record/1 does.

A name that does not exist and a name without TXT records both give {:error, :no_record}. Other DNS errors give {:error, {:dns, reason}}: a sender then keeps using any cached policy (RFC 8461 §5.1).

@spec fetch(String.t(), keyword()) ::
  {:ok, Sovite.TLS.MTASTS.Policy.t()} | {:error, fetch_error()}

Fetches and parses the policy for domain (RFC 8461 §3.3).

Sends GET /.well-known/mta-sts.txt over HTTPS to mta-sts.<domain>. The server's certificate must be valid for that name (PKIX, with SNI). Only a 200 response with Content-Type text/plain is accepted: redirects are not followed. The body may be sent with Content-Length, chunked, or until the connection closes.

Options

• :timeout - milliseconds for the whole fetch: connecting, the TLS handshake, and reading the response. Defaults to 60 seconds.
• :max_size - the largest body accepted, in bytes. Defaults to 65536.
• :cacerts - trusted CA certificates (DER). Defaults to the system's (:public_key.cacerts_get/0).
• :port - the TCP port. Defaults to 443.
• :connect_to - an {ip, port} tuple or a host name (charlist) to connect to instead of mta-sts.<domain>, for tests and proxies. SNI and the certificate check still use mta-sts.<domain>.

See fetch_error/0 for the errors.

@spec match?(Sovite.TLS.MTASTS.Policy.t(), String.t()) :: boolean()

Returns whether the MX host host is allowed by policy (RFC 8461 §4.1).

Names are compared case-insensitively, ignoring a trailing dot. A *.example.com pattern matches any name with exactly one more label on the left: mx1.example.com, but neither example.com nor a.b.example.com.

iex> policy = %Sovite.TLS.MTASTS.Policy{mode: :enforce, mx: ["*.example.com"], max_age: 86400, text: ""}
iex> Sovite.TLS.MTASTS.match?(policy, "MX1.example.com.")
true
iex> Sovite.TLS.MTASTS.match?(policy, "a.b.example.com")
false

@spec parse_policy(binary()) ::
  {:ok, Sovite.TLS.MTASTS.Policy.t()} | {:error, policy_error()}

Parses a policy body (RFC 8461 §3.2).

Lines end with LF or CRLF, and are key: value with optional whitespace around the colon and at the ends. Blank lines and unknown keys are ignored. Keys and the version and mode values are case-sensitive.

• version must be STSv1.
• mode must be enforce, testing, or none.
• max_age must be a number of seconds; values above 31557600 are lowered to it.
• mx may appear several times, and at least once unless the mode is none. Each is a host name, or *. and a host name.

Only mx may repeat: for the other keys the first line counts.

iex> {:ok, policy} = Sovite.TLS.MTASTS.parse_policy("version: STSv1\nmode: enforce\nmx: MX.example.com\nmax_age: 86400\n")
iex> {policy.mode, policy.mx, policy.max_age}
{:enforce, ["mx.example.com"], 86400}

@spec parse_record([String.t()]) :: {:ok, id :: String.t()} | {:error, record_error()}

Finds the policy id in the TXT records at _mta-sts.<domain>.

Records that do not start with v=STSv1 are ignored. Exactly one must be left, and it must be valid (RFC 8461 §3.1):

• fields are key=value, separated by ; with optional whitespace, and a trailing ; is allowed;
• v=STSv1 comes first;
• id is 1 to 32 letters and digits;
• other fields are ignored, but no key may appear twice.

Otherwise the domain has no usable policy.

iex> Sovite.TLS.MTASTS.parse_record(["v=spf1 -all", "v=STSv1; id=20260101"])
{:ok, "20260101"}
iex> Sovite.TLS.MTASTS.parse_record(["v=STSv1; id=a", "v=STSv1; id=b"])
{:error, :multiple_records}

@spec policy_host(String.t()) :: String.t()

Returns the host that serves the policy for domain.

iex> Sovite.TLS.MTASTS.policy_host("example.com")
"mta-sts.example.com"

@spec policy_id(String.t()) :: String.t()

Returns an id for the policy text, for the id= field of the _mta-sts record: the first 20 hex digits of its SHA-256. It changes exactly when the policy does, so senders refetch only then.

@spec policy_text(Sovite.TLS.MTASTS.Policy.mode(), [String.t()], non_neg_integer()) ::
  String.t()

Builds a policy body, with CRLF line endings.

iex> Sovite.TLS.MTASTS.policy_text(:testing, ["mx.example.com"], 604800)
"version: STSv1\r\nmode: testing\r\nmx: mx.example.com\r\nmax_age: 604800\r\n"

@spec policy_url(String.t()) :: String.t()

Returns the URL of the policy for domain.

iex> Sovite.TLS.MTASTS.policy_url("example.com")
"https://mta-sts.example.com/.well-known/mta-sts.txt"