mailauth 7.1.1 → 7.3.0

package/docs/mta-sts.md

@@ -48,15 +48,17 @@ const { policy, status, warnings } = await getPolicy('example.com', knownPolicy,
 
 ### Policy Object Fields
 
-| Field     | Type            | Presence         | Description                                                               |
-| --------- | --------------- | ---------------- | ------------------------------------------------------------------------- |
-| `id`      | `string\|false` | Always           | Policy ID from DNS TXT record, or `false` if not found                    |
-| `version` | `string`        | Policy found     | Always `"STSv1"` for valid policies                                       |
-| `mode`    | `string`        | Always           | Policy mode (see below)                                                   |
-| `mx`      | `string[]`      | Listed in policy | Array of allowed MX hostnames (may include wildcards)                     |
-| `maxAge`  | `number`        | Policy found     | Policy validity period in seconds                                         |
-| `expires` | `string`        | Policy found     | ISO 8601 expiration timestamp                                             |
-| `error`   | `Error`         | Status errored   | Error object explaining why no live policy could be discovered or fetched |
+| Field        | Type            | Presence         | Description                                                               |
+| ------------ | --------------- | ---------------- | ------------------------------------------------------------------------- |
+| `id`         | `string\|false` | Always           | Policy ID from DNS TXT record, or `false` if not found                    |
+| `version`    | `string`        | Policy found     | Always `"STSv1"` for valid policies                                       |
+| `mode`       | `string`        | Always           | Policy mode (see below)                                                   |
+| `mx`         | `string[]`      | Listed in policy | Array of allowed MX hostnames (may include wildcards)                     |
+| `maxAge`     | `number`        | Policy found     | Policy validity period in seconds                                         |
+| `expires`    | `string`        | Policy found     | ISO 8601 expiration timestamp                                             |
+| `error`      | `Error`         | Status errored   | Error object explaining why no live policy could be discovered or fetched |
+| `retryId`    | `string`        | Fetch failed     | New policy ID that could not be fetched while the cached policy is kept   |
+| `retryAfter` | `string`        | Fetch failed     | ISO 8601 timestamp before which `retryId` is not fetched again            |
 
 ### Mode Values
 
@@ -79,6 +81,7 @@ await cache.set(domain, policy); // keep the entry at least until policy.expires
 - **Valid cached policy, same ID in DNS:** the cached policy is returned as `renewed` without an HTTPS request. Its `expires` value is not extended, so the policy file is fetched again once it expires.
 - **Valid cached policy, no live policy:** if the TXT lookup fails, the TXT record is missing, unusable or duplicated, the policy host has no address, or the new policy can not be fetched or is invalid, the cached policy is returned with `status: "errored"` and the reason in `policy.error`. A valid cached policy is never replaced by `mode: "none"` because of a discovery failure. An exception is a cached policy that already has mode `none`, which may be replaced by the retry placeholder described below.
 - **Expired cached policy:** the policy file is fetched again. If the fetch fails, the default lax mode keeps returning the expired `enforce` or `testing` policy (with the `expired-cache` warning), while strict mode treats the domain as having no policy.
+- **Cached policy kept after a failed fetch:** when the policy for a new ID can not be fetched and the cached policy is returned instead, it gets `retryId` (the new ID) and `retryAfter` (one hour ahead). Storing it makes the next calls return it as `errored` without HTTPS requests while the DNS record has the same ID, so the policy host is not retried for an hour (RFC 8461 3.3). A different policy ID is fetched right away, and the fields are dropped once a policy is fetched.
 - **No usable cached policy and the fetch fails:** the result is a placeholder with the new policy ID, mode `none`, and `expires` set one hour ahead. Storing it makes the next calls return it as `renewed` without HTTPS requests, so the policy host is not retried for an hour. A changed policy ID is fetched right away.
 
 ## Strict Mode

package/docs/spf.md

@@ -19,17 +19,17 @@ const result = await spf({
 
 ## Options
 
-| Option            | Type       | Default           | Description                                                                                                    |
-| ----------------- | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
-| `sender`          | `string`   | `postmaster@helo` | MAIL FROM address. An empty value means a null reverse-path, so the HELO identity is checked                   |
-| `ip`              | `string`   | Required          | SMTP client IP address. IPv4-mapped IPv6 addresses (`::ffff:192.0.2.1`, `::ffff:c000:201`) are checked as IPv4 |
-| `helo`            | `string`   |                   | EHLO/HELO hostname                                                                                             |
-| `mta`             | `string`   | `os.hostname()`   | Hostname of the MTA performing the check                                                                       |
-| `resolver`        | `function` | `dns.resolve`     | Custom DNS resolver                                                                                            |
-| `maxResolveCount` | `number`   | `10`              | Maximum DNS lookups allowed                                                                                    |
-| `maxVoidCount`    | `number`   | `2`               | Maximum void (empty) DNS lookups allowed                                                                       |
-| `maxElapsedTime`  | `number`   | No limit          | Maximum time in milliseconds for the whole evaluation. If exceeded, the result is `temperror` (RFC 7208 4.6.4) |
-| `strict`          | `boolean`  | `false`           | Follow RFC 7208 exactly instead of the lenient default, see [Strict Mode](#strict-mode)                        |
+| Option            | Type       | Default           | Description                                                                                                                |
+| ----------------- | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `sender`          | `string`   | `postmaster@helo` | MAIL FROM address. An empty value means a null reverse-path, so the HELO identity is checked                               |
+| `ip`              | `string`   | Required          | SMTP client IP address. IPv4-mapped IPv6 addresses (`::ffff:192.0.2.1`, `::ffff:c000:201`) are checked as IPv4             |
+| `helo`            | `string`   |                   | EHLO/HELO hostname                                                                                                         |
+| `mta`             | `string`   | `os.hostname()`   | Hostname of the MTA performing the check                                                                                   |
+| `resolver`        | `function` | `dns.resolve`     | Custom DNS resolver                                                                                                        |
+| `maxResolveCount` | `number`   | `10`              | Maximum DNS lookups allowed                                                                                                |
+| `maxVoidCount`    | `number`   | `2`               | Maximum void (empty) DNS lookups allowed. `0` is a valid limit, a value that is not a non-negative number uses the default |
+| `maxElapsedTime`  | `number`   | No limit          | Maximum time in milliseconds for the whole evaluation. If exceeded, the result is `temperror` (RFC 7208 4.6.4)             |
+| `strict`          | `boolean`  | `false`           | Follow RFC 7208 exactly instead of the lenient default, see [Strict Mode](#strict-mode)                                    |
 
 A missing or invalid `ip` gives a `temperror` result with the comment `missing or invalid client IP address`.
 
@@ -68,7 +68,7 @@ In strict mode `status.smtp` holds only the identity that was checked (RFC 8601
 
 ## explanation
 
-When the result is `fail` because of a mechanism match and the record has an `exp` modifier, the explanation string is fetched and expanded as described in RFC 7208 section 6.2. Any problem with it (DNS error, no or several TXT records, syntax error, non-ASCII text) means that there is no explanation. The explanation lookup does not count toward the DNS lookup limits. The explanation of an included record is never used, and after a redirect only the explanation of the redirect target is used.
+When the result is `fail` because of a mechanism match and the record has an `exp` modifier, the explanation string is fetched and expanded as described in RFC 7208 section 6.2. Any problem with it (DNS error, no or several TXT records, syntax error, text that is not printable US-ASCII before or after macro expansion) means that there is no explanation. The explanation lookup does not count toward the DNS lookup limits. The explanation of an included record is never used, and after a redirect only the explanation of the redirect target is used.
 
 The explanation is text from the domain owner. It is not added to the generated headers. If you show it to an SMTP client, make clear that it comes from a third party, for example by prepending `"<domain> explains: "`.
 
@@ -144,7 +144,8 @@ These rules apply in both modes:
 - `%{p}` expands to a validated PTR name or `unknown`.
 - Trailing dots in domain-specs are accepted, names longer than 253 characters are truncated from the left, and uppercase macros are URL escaped.
 - An internationalized MAIL FROM domain is converted to A-labels.
-- Address lookups of MX hosts are not counted as void lookups.
+- A single trailing dot is removed from the MAIL FROM domain and the HELO name (RFC 7208 section 4.3). A zero-length label anywhere else gives `none`.
+- Address lookups of MX hosts are not counted as void lookups. The PTR lookup of a `%{p}` expansion is not counted as a void lookup either, the query of the term itself decides if the term was void.
 
 ## Example Output