mailauth 6.0.0 → 7.1.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "6.0.0"
+    ".": "7.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [7.1.0](https://github.com/postalsys/mailauth/compare/v7.0.0...v7.1.0) (2026-09-27)
+
+
+### Features
+
+* **cli:** add --reject-rsa-sha1 to the report command ([#140](https://github.com/postalsys/mailauth/issues/140)) ([fc8e965](https://github.com/postalsys/mailauth/commit/fc8e9651e304ff6d9f3249e2f3c1db7e481c7d8c))
+* **dkim:** add rejectRsaSha1 to reject rsa-sha1 signatures without the strict mode ([#138](https://github.com/postalsys/mailauth/issues/138)) ([92d2c23](https://github.com/postalsys/mailauth/commit/92d2c23027d443dc62dc93a49b54d561beb3f2ed))
+
+
+### Bug Fixes
+
+* **dmarc:** count a subdomain with a dangling CNAME as existing for np ([#137](https://github.com/postalsys/mailauth/issues/137)) ([b38ecef](https://github.com/postalsys/mailauth/commit/b38ecef53b56e479863dd96cae1a6fe24c970353))
+
+## [7.0.0](https://github.com/postalsys/mailauth/compare/v6.0.0...v7.0.0) (2026-09-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* **dmarc:** the DMARC result no longer has pct, which is historic in RFC 9989, and BIMI no longer reads it. policy can differ from before for non-existent subdomains (np), for t=y records, and for records with an invalid p, sp or np.
+
+### Features
+
+* **dmarc:** apply np, t and the RFC 9989 rules for invalid policies ([c11740c](https://github.com/postalsys/mailauth/commit/c11740c0c9b18a9329e82c5eacfb63cfb3a3420a))
+* fix RFC compliance findings and add a strict mode ([#136](https://github.com/postalsys/mailauth/issues/136)) ([62e0dd1](https://github.com/postalsys/mailauth/commit/62e0dd16359b3964cb579230035a980bf054a06f))
+
 ## [6.0.0](https://github.com/postalsys/mailauth/compare/v5.0.3...v6.0.0) (2026-09-26)
 
 

package/README.md

@@ -26,6 +26,7 @@ mailauth is a pure JavaScript implementation, requiring no external applications
 2. [Command-Line Usage](#command-line-usage)
 3. [Library Usage](#library-usage)
     - [Authentication](#authentication)
+        - [Strict mode](#strict-mode)
     - [DKIM](#dkim)
         - [Signing](#dkim-signing)
         - [Verification](#dkim-verification)
@@ -71,7 +72,7 @@ Use the `authenticate` function to validate DKIM signatures, SPF, DMARC, ARC, an
 
 ```javascript
 await authenticate(message [, options])
-// Returns: { dkim, spf, arc, dmarc, bimi, receivedChain, headers }
+// Returns: { dkim, spf, arc, dmarc, bimi, receivedChain, headers [, dmarcSkipReason] }
 ```
 
 #### Parameters
@@ -81,9 +82,10 @@ await authenticate(message [, options])
     - **sender** (`string`): Email address from the MAIL FROM command. Defaults to the `Return-Path` header if not set.
     - **ip** (`string`): IP address of the remote client that sent the message.
     - **helo** (`string`): Hostname from the HELO/EHLO command.
-    - **trustReceived** (`boolean`): If `true`, parses `ip` and `helo` from the latest `Received` header if not provided. Defaults to `false`.
-    - **mta** (`string`): Hostname of the server performing the authentication. Defaults to `os.hostname()`. Included in Authentication headers.
+    - **trustReceived** (`boolean`): If `true`, parses `ip` and `helo` from the latest `Received` header if not provided. The IP address is the connecting address from the TCP-info comment of the `from` clause (RFC 5321 section 4.4), never an address literal the client sent in its HELO. Postfix, Sendmail, Exim (including its `from [ip] (helo=...)` form) and similar formats are understood. Defaults to `false`.
+    - **mta** (`string`): Hostname of the server performing the authentication. Defaults to `os.hostname()`. Used as the authserv-id of the Authentication headers, so it should be a host name: an internationalized name is converted to A-labels, and a value that is not a valid token (for example one with a space or a semicolon) is written as a quoted string. With `strict` such a value throws an error with the code `EINVALIDAUTHSERVID` instead.
     - **minBitLength** (`number`): Minimum allowed bits for RSA public keys. Defaults to `1024`. Keys with fewer bits will fail validation.
+    - **rejectRsaSha1** (`boolean`): If `true`, an rsa-sha1 DKIM signature gives `dkim=policy` with `policy.dkim-rules=weak-algorithm`, as in strict mode, and is not counted for DMARC. Every other check keeps the lenient default. It only affects verification. Defaults to `false`, and `strict` implies it.
     - **disableArc** (`boolean`): If `true`, skips ARC checks.
     - **disableDmarc** (`boolean`): If `true`, skips DMARC checks, also disabling dependent checks like BIMI.
     - **disableBimi** (`boolean`): If `true`, skips BIMI checks.
@@ -94,6 +96,7 @@ await authenticate(message [, options])
     - **resolver** (`async function`): Custom DNS resolver function. Defaults to [`dns.promises.resolve`](https://nodejs.org/api/dns.html#dns_dnspromises_resolve_hostname_rrtype).
     - **maxResolveCount** (`number`): DNS lookup limit for SPF. Defaults to `10` as per [RFC7208](https://datatracker.ietf.org/doc/html/rfc7208#section-4.6.4).
     - **maxVoidCount** (`number`): DNS lookup limit for SPF producing empty results. Defaults to `2` as per [RFC7208](https://datatracker.ietf.org/doc/html/rfc7208#section-4.6.4).
+    - **strict** (`boolean`): If `true`, every check follows its RFC exactly instead of the lenient defaults. Passed on to DKIM, SPF, ARC, DMARC, BIMI and ARC sealing (BIMI only uses it for the format of its Authentication-Results entry). Defaults to `false`. See [Strict mode](#strict-mode).
 
 #### Example
 
@@ -141,6 +144,38 @@ You can see the full output, including structured data for DKIM, SPF, DMARC, and
 
 **Note:** The `receivedChain` property is an array of parsed representations of the `Received:` headers.
 
+**Note:** `dmarc` is `false` when DMARC can not be evaluated because the From header has no domain or more than one (RFC 9989 section 5.3.1). `dmarcSkipReason` then says why: `no-author-domain`, `multiple-author-domains`, `invalid-author-domain` (a From mailbox has no usable domain) or `multiple-from-fields` (the message has more than one From header field, which RFC 5322 does not allow). RFC 9989 section 11.5 suggests treating such a message as suspicious.
+
+**Note:** An ARC set is only added while the chain has fewer than 50 sets (RFC 8617 section 4.2.1). Otherwise the message is not sealed and `arc.sealErrors` says why.
+
+#### Strict mode
+
+By default mailauth is lenient where accepting non-conforming input costs little security, mostly weak signatures that still bind the signing domain to the content. With `strict: true` every check follows its RFC exactly.
+
+Whatever the default mode accepts that strict mode would reject is marked in a `warnings` array on the affected result (for example `dkim.results[0].status.warnings` is `['rsa-sha1']`), so that you can apply your own policy without switching modes. The markers are never written into the generated headers. For rsa-sha1 verification the `rejectRsaSha1` option applies the strict rule on its own, which also keeps such a signature out of DMARC in `authenticate()`.
+
+Some rules apply in both modes, because breaking them is a defect and not leniency. For DKIM these are: a signature must sign the From header, the key record's `h=` (hash algorithms) and `s=` (service types) restrictions are honored, `ed25519-sha1` is not an algorithm, and signing refuses a domain, selector or identity that would break out of its tag.
+
+DKIM differences between the modes:
+
+| Input                                                              | Default                                               | `strict: true`                                                             |
+| ------------------------------------------------------------------ | ----------------------------------------------------- | -------------------------------------------------------------------------- |
+| rsa-sha1 signature (RFC 8301)                                      | `pass`, warning `rsa-sha1`                            | `policy` (`policy.dkim-rules=weak-algorithm`)                              |
+| Missing `v=` or `h=`, `v=` other than 1                            | verified, warning `missing-v`/`missing-h`/`invalid-v` | `neutral` (`signature missing required tag`, `incompatible version`)       |
+| Duplicate tags, upper case tag names, malformed `t=`/`x=`/`l=`     | verified, warning `tag-syntax`                        | `neutral` (`signature syntax error`)                                       |
+| `i=` domain outside `d=`, or a subdomain with a key that has `t=s` | verified, warning `identity-domain`                   | `neutral` (`domain mismatch`)                                              |
+| `x=` equal to `t=`                                                 | verified, warning `invalid-expiration`                | `neutral` (`invalid expiration`)                                           |
+| Key record syntax errors, `v=` not first or not exactly `DKIM1`    | used, warning `key-syntax`/`key-v-syntax`             | key ignored                                                                |
+| Ed25519 key record without `k=ed25519`                             | used, warning `key-type-inferred`                     | key ignored                                                                |
+| Body hash mismatch                                                 | `neutral`                                             | `fail`                                                                     |
+| Signature with an unknown algorithm or no `d=`/`s=`                | left out of the results                               | `neutral`                                                                  |
+| `header.i` in Authentication-Results                               | always `@d`                                           | the AUID (`i=` or `@d`), plus `header.d`                                   |
+| Email identities in Authentication-Results                         | a value that needs quoting is quoted as a whole       | `local-part@domain` with only the local-part quoted (RFC 8601 section 2.2) |
+| Header order                                                       | Received-SPF above Authentication-Results             | Authentication-Results on top (RFC 8601 section 5)                         |
+| Signing with rsa-sha1 or an RSA key under 1024 bits                | signed, warning `rsa-sha1`/`weak-key`                 | error                                                                      |
+
+See the [DKIM result reference](docs/dkim.md) for every DKIM warning, and the SPF, DMARC, ARC and MTA-STS documentation for theirs.
+
 ### DKIM
 
 #### DKIM Signing
@@ -153,24 +188,29 @@ Use the `dkimSign` function to sign an email message with DKIM.
 const { dkimSign } = require('mailauth/lib/dkim/sign');
 
 const signResult = await dkimSign(message, options);
-// Returns: { signatures: String, errors: Array }
+// Returns: { signatures: String, errors: Array, warnings: Array }
 ```
 
+`signatures` holds the `DKIM-Signature` header lines, each ending with a line break. It is an empty string when no signature could be created, in which case `errors` says why. Each entry of `errors` is an object with an `err` property (an `Error` with a `code`, such as `ENOFROM`, `EINVALIDALGO`, `ESHORTKEY` or `EINVALIDDOMAIN`) and the `signingDomain` and `selector` it applies to. `warnings` lists what was signed although `strict` mode would have refused it (`rsa-sha1`, `weak-key`, `invalid-expiration`, `invalid-signtime`, `d-syntax`, `s-syntax`, `identity-domain`).
+
 ##### Parameters
 
 - **message**: A `String`, `Buffer`, or `Readable` stream representing the email message.
 - **options**:
     - **canonicalization** (`string`): Canonicalization method. Defaults to `'relaxed/relaxed'`.
-    - **algorithm** (`string`): Signing and hashing algorithm. Defaults to `'rsa-sha256'`.
+    - **algorithm** (`string`): Signing and hashing algorithm. Defaults to `'rsa-sha256'` for an RSA key and `'ed25519-sha256'` for an Ed25519 key. `'rsa-sha1'` is historic (RFC 8301) and adds a warning.
     - **signTime** (`Date`): Signing time. Defaults to current time.
-    - **expires** (`Date`): Signature expiration time (`x=` tag). Optional.
-    - **headerList** (`Array`): List of header field names to sign. Optional; uses default set if not specified.
+    - **expires** (`Date`): Signature expiration time (`x=` tag). Optional. It must be later than the signing time.
+    - **headerList** (`Array` or `string`): Header field names to sign, as an array or a colon separated string. Optional; uses default set if not specified. `From` must be included.
+    - **strict** (`boolean`): If `true`, refuses to sign with `rsa-sha1`, with an RSA key shorter than 1024 bits, with an expiration that is not after the signing time, and with a domain, selector or identity that is not valid RFC 6376 syntax. Defaults to `false`, which signs these and lists them in `warnings`. A value that would break out of its tag (a semicolon, whitespace or a line break in the domain, selector or identity) is refused in both modes.
     - **signatureData** (`Array`): Array of signature objects. Each object may contain:
-        - **signingDomain** (`string`): DKIM key domain name.
+        - **signingDomain** (`string`): DKIM key domain name. An internationalized domain name is converted to A-labels.
         - **selector** (`string`): DKIM key selector.
         - **privateKey** (`string` or `Buffer`): Private key for signing (RSA or Ed25519).
         - **algorithm** (`string`, optional): Overrides parent `algorithm`.
         - **canonicalization** (`string`, optional): Overrides parent `canonicalization`.
+        - **headerList** (`Array` or `string`, optional): Overrides parent `headerList`.
+        - **identity** (`string`, optional): Agent or User Identifier for the `i=` tag, such as `user@mail.example.com`. Its domain must be the signing domain or one of its subdomains.
         - **maxBodyLength** (`number`, optional): Maximum number of canonicalized body bytes to sign (`l=` tag). Not recommended for general use.
 
 ##### Example
@@ -239,6 +279,8 @@ const dkimSignStream = new DkimSignStream({
 process.stdin.pipe(dkimSignStream).pipe(process.stdout);
 ```
 
+When no signature can be created the message is passed through unchanged. Once the stream has ended, `dkimSignStream.errors` and `dkimSignStream.warnings` hold the same values as the `dkimSign` result.
+
 #### DKIM Verification
 
 Use the `dkimVerify` function to verify DKIM signatures in an email message.
@@ -248,10 +290,20 @@ Use the `dkimVerify` function to verify DKIM signatures in an email message.
 ```javascript
 const { dkimVerify } = require('mailauth/lib/dkim/verify');
 
-const result = await dkimVerify(message);
+const result = await dkimVerify(message [, options]);
 // Returns an object containing verification results
 ```
 
+- **options** (optional):
+    - **resolver** (`async function`): Custom DNS resolver function. Defaults to `dns.promises.resolve`. A U-label signing domain is converted to A-labels before it is looked up (RFC 8616).
+    - **minBitLength** (`number`): Minimum allowed bits for RSA public keys. Defaults to `1024`. A shorter key gives `dkim=policy` with `policy.dkim-rules=weak-key`.
+    - **rejectRsaSha1** (`boolean`): If `true`, an rsa-sha1 signature gives `dkim=policy` with `policy.dkim-rules=weak-algorithm`, as in strict mode, while every other check keeps the lenient default. Signing is not affected. Defaults to `false`, and `strict` implies it.
+    - **sender** (`string`): Envelope sender. Defaults to the `Return-Path` header.
+    - **curTime** (`Date`): The time to check `t=` and `x=` against. Defaults to now.
+    - **strict** (`boolean`): If `true`, follows RFC 6376, RFC 8301 and RFC 8463 exactly. Defaults to `false`. See [Strict mode](#strict-mode).
+
+Whatever the mode, a signature that does not sign the From header is reported as `dkim=neutral (From field not signed)`, and a key record whose `h=` does not list the hash algorithm of the signature, or whose `s=` does not include `email`, is not used. A key record with `t=y` (testing) sets `status.testing`.
+
 See [DKIM Result Reference](docs/dkim.md) for details on the result object structure.
 
 ##### Example
@@ -300,6 +352,13 @@ See [SPF Result Reference](docs/spf.md) for details on the result object structu
     - **ip** (`string`): SMTP client IP.
     - **helo** (`string`): HELO/EHLO hostname.
     - **mta** (`string`): Hostname of the MTA performing the check.
+    - **resolver** (`function`): Custom DNS resolver, same signature as `dns.promises.resolve`.
+    - **maxResolveCount** (`number`): Maximum DNS lookups, defaults to `10`.
+    - **maxVoidCount** (`number`): Maximum void DNS lookups, defaults to `2`.
+    - **maxElapsedTime** (`number`): Time limit in milliseconds for the whole evaluation. If exceeded, the result is `temperror`. No limit by default.
+    - **strict** (`boolean`): If `true`, follow RFC 7208 exactly: the whole record is validated before evaluation, void lookups are counted as the RFC does, and Authentication-Results reports only the checked identity. Defaults to `false`. See [Strict Mode](docs/spf.md#strict-mode).
+
+In the default mode, input that strict mode would reject is listed in the `warnings` array of the result. For a `fail` result, the `explanation` property holds the text published with the `exp` modifier, if any.
 
 ##### Example
 
@@ -319,9 +378,8 @@ console.log(result.header);
 **Sample Output:**
 
 ```
-Received-SPF: pass (mx.myhost.com: domain of andris@wildduck.email
- designates 217.146.76.20 as permitted sender) client-ip=217.146.76.20;
- envelope-from="andris@wildduck.email";
+Received-SPF: pass (mx.myhost.com: domain of andris@wildduck.email designates 217.146.76.20 as permitted sender) client-ip=217.146.76.20;
+ envelope-from="andris@wildduck.email"; helo=foo;
 ```
 
 ### ARC
@@ -344,7 +402,7 @@ const { arc } = await authenticate(message, {
 console.log(arc);
 ```
 
-See [ARC Result Reference](docs/arc.md) for details on the result object structure.
+See [ARC Result Reference](docs/arc.md) for details on the result object structure, and for what `strict: true` changes.
 
 **Sample Output:**
 
@@ -387,6 +445,8 @@ process.stdout.write(headers); // Includes terminating line break
 process.stdout.write(message);
 ```
 
+The sealing algorithm follows the key type (`rsa-sha256` or `ed25519-sha256`). A message whose newest ARC-Seal already says `cv=fail`, or whose chain already has 50 sets, is not sealed (RFC 8617 sections 5.1 and 4.2.1), and `arc.sealErrors` says why a requested seal was not added.
+
 ##### Sealing After Modifications
 
 If you need to modify the message before sealing, first authenticate it, modify as needed, then seal using the authentication results.
@@ -417,6 +477,8 @@ const sealHeaders = await sealMessage(message, {
   cv: arc.status.result,
 });
 
+// sealHeaders is empty when no ARC set could be created, use createSeal() to get the errors
+
 // Output the sealed message
 process.stdout.write(sealHeaders); // ARC headers
 process.stdout.write(headers);     // Authentication results
@@ -427,11 +489,15 @@ process.stdout.write(message);
 
 DMARC is verified during the authentication process. Although the `dmarc` handler is exported, it requires input from previous steps like SPF and DKIM.
 
+The author domain is the domain of the From address, also when the local-part is quoted and contains "@" or the address has an obsolete source route. Several From addresses are evaluated if they share one domain. With no domain or several domains, DMARC validation is not possible and the result is `false`.
+
+The Authentication-Results entry includes `policy.dmarc` with the evaluated policy on `pass` and `fail`. With `strict: true`, records follow the RFC 6376 tag-list rules (case sensitive tag names, a duplicated tag invalidates the record) and the unregistered `header.d` is left out. The default mode keeps `header.d` and case-folds tag names, letting the last duplicate win, and lists such records in `warnings`.
+
 See [DMARC Result Reference](docs/dmarc.md) for details on the result object structure.
 
 #### DMARC Helpers
 
-##### `getDmarcRecord(domain [, resolver])`
+##### `getDmarcRecord(domain [, resolver [, options]])`
 
 Fetches and parses the DMARC record that applies to a domain, found with the DNS Tree Walk of RFC 9989 section 4.10. That is the domain's own record, or else the record of its Organizational Domain, or else a record published with `psd=y` above it. Returns `false` if no record applies.
 
@@ -440,7 +506,7 @@ Fetches and parses the DMARC record that applies to a domain, found with the DNS
 ```javascript
 const getDmarcRecord = require('mailauth/lib/dmarc/get-dmarc-record');
 
-const dmarcRecord = await getDmarcRecord(domain [, resolver]);
+const dmarcRecord = await getDmarcRecord(domain [, resolver [, { strict }]]);
 // Returns an object with DMARC record details or `false` if not found
 ```
 
@@ -448,6 +514,7 @@ const dmarcRecord = await getDmarcRecord(domain [, resolver]);
 
 - **domain** (`string`): The domain to check for a DMARC record.
 - **resolver** (`function`, optional): Custom DNS resolver function. Defaults to `dns.resolve`.
+- **options.strict** (`boolean`, optional): Parse records by the RFC 6376 tag-list rules, so a record with a duplicated tag is ignored. Defaults to `false`.
 
 ###### Example
 
@@ -479,7 +546,7 @@ console.log(dmarcRecord);
 
 ### BIMI
 
-Brand Indicators for Message Identification (BIMI) support is based on [draft-blank-ietf-bimi-02](https://tools.ietf.org/html/draft-blank-ietf-bimi-02). BIMI information is resolved during the authentication step, provided the message passes DMARC validation with a policy other than "none".
+Brand Indicators for Message Identification (BIMI) support is based on [draft-brand-indicators-for-message-identification-14](https://datatracker.ietf.org/doc/html/draft-brand-indicators-for-message-identification). BIMI information is resolved during the authentication step, provided the message has a single From address and passes DMARC validation with an enforcing policy: neither the author domain's DMARC record nor the one of its Organizational Domain may have `p=none` or `sp=none`. A declination record (`v=BIMI1; l=;`) gives `bimi=declined`, and a DNS error gives `bimi=temperror` (earlier versions used `temperr`).
 
 See [BIMI Result Reference](docs/bimi.md) for details on the result object structure.
 
@@ -506,7 +573,7 @@ if (bimi?.location) {
 **Note:**
 
 - The `BIMI-Location` header is ignored by mailauth.
-- The `BIMI-Selector` header can be used for selector selection if available.
+- The `BIMI-Selector` header can be used for selector selection if available. A selector that is not found at the author domain is looked up at the Organizational Domain, it does not fall back to `default`.
 
 #### Verified Mark Certificate (VMC)
 
@@ -530,7 +597,7 @@ Use the `getPolicy` function to fetch the MTA-STS policy for a domain.
 ```javascript
 const { getPolicy } = require('mailauth/lib/mta-sts');
 
-const { policy, status } = await getPolicy(domain [, knownPolicy]);
+const { policy, status, warnings } = await getPolicy(domain [, knownPolicy [, options]]);
 // Returns an object with the policy and status
 ```
 
@@ -538,33 +605,39 @@ See [MTA-STS Result Reference](docs/mta-sts.md) for details on the result object
 
 ##### Parameters
 
-- **domain** (`string`): The domain to retrieve the policy for.
-- **knownPolicy** (`object`, optional): Previously cached policy for the domain.
+- **domain** (`string`): The domain to retrieve the policy for. An email address is also accepted.
+- **knownPolicy** (`object`, optional): Previously cached policy for the domain, the `policy` value of an earlier result.
+- **options** (`object`, optional):
+    - **resolver** (`function`): Custom DNS resolver with the `dns.promises.resolve` signature.
+    - **strict** (`boolean`, default `false`): Apply the RFC 8461 rules exactly (TXT record and policy syntax, HTTP 200 only, `text/plain` only, no CN fallback or partial wildcards in the policy host certificate, expired cached policies are not applied). In the default lax mode these are accepted and listed in `warnings`.
+    - **timeout** (`number`, default `60000`): Overall time limit for the HTTPS policy request in milliseconds.
+    - **maxPolicySize** (`number`, default `65536`): Maximum size of the policy file in bytes.
 
 ##### Example
 
 ```javascript
 const { getPolicy } = require('mailauth/lib/mta-sts');
 
-const knownPolicy = /* Retrieve from your cache if available */;
+const knownPolicy = await cache.get('gmail.com'); // undefined if not cached
 const { policy, status } = await getPolicy('gmail.com', knownPolicy);
 
-if (policy.id !== knownPolicy?.id) {
-  // Update your cache with the new policy
-}
+// Always store the returned policy. If no live policy can be found, getPolicy returns
+// the still valid cached policy, so a DNS or HTTPS failure does not erase it.
+await cache.set('gmail.com', policy);
 
 if (policy.mode === 'enforce') {
-  // TLS must be used when sending to this domain
+    // TLS must be used when sending to this domain
 }
 ```
 
+Keep cache entries at least until `policy.expires`. A cached policy that has not expired is used as long as the policy ID in DNS stays the same, and it is kept when the TXT record or the policy file can not be retrieved (RFC 8461 3.3 and 5.1).
+
 **Possible Status Values:**
 
-- `"not_found"`: No policy was found.
-- `"cached"`: Existing policy is still valid.
-- `"found"`: New or updated policy found.
-- `"renew"`: Existing policy is valid; renew cache.
-- `"errored"`: Policy discovery failed due to a temporary error.
+- `"found"`: A new or updated policy was fetched.
+- `"renewed"`: The cached policy is still valid and its ID matches DNS; it is returned unchanged without fetching the policy file.
+- `"not_found"`: No policy was found, and there is no valid cached policy.
+- `"errored"`: No live policy could be discovered or fetched; `policy.error` holds the reason. `policy` is the valid cached policy if there is one, otherwise a policy with mode `"none"`.
 
 #### MX Validation
 
@@ -575,7 +648,7 @@ Use the `validateMx` function to check if an MX hostname is valid according to t
 ```javascript
 const { validateMx } = require('mailauth/lib/mta-sts');
 
-const validation = validateMx(mx, policy);
+const validation = validateMx(mx, policy [, options]);
 // Returns an object indicating if the MX is valid
 ```
 
@@ -583,6 +656,9 @@ const validation = validateMx(mx, policy);
 
 - **mx** (`string`): The resolved MX hostname.
 - **policy** (`object`): The MTA-STS policy object.
+- **options** (`object`, optional): `{ strict }` is accepted for consistency; the matching rules are the same in both modes.
+
+A wildcard pattern such as `*.example.com` matches exactly one left-most label (`mail.example.com`, but not `example.com` or `foo.bar.example.com`). `validateMx` does not check `policy.expires`.
 
 ##### Example
 
@@ -605,20 +681,18 @@ mailauth uses the following test suites:
 
 ### SPF Test Suite
 
-Based on the [OpenSPF test suite](http://www.openspf.org/Test_Suite), with some differences:
+Based on the [OpenSPF test suite](http://www.openspf.org/Test_Suite). Every test is run in both modes:
 
-- Less strict whitespace checks.
-- Some macro tests are skipped.
-- Some tests are skipped where the invalid component is after a matching part.
-- All other tests pass.
+- With `strict: true`, all tests pass, including the explanation (`exp`) results.
+- In the default mode, 7 tests give a different result: syntax errors after the matching term are not detected, the `c`, `r` and `t` macros are accepted outside of explanation text, and a name that is invalid after macro expansion gives `permerror` instead of not matching.
 
 ### ARC Test Suite from ValiMail
 
-Based on ValiMail's [arc_test_suite](https://github.com/ValiMail/arc_test_suite):
+Based on ValiMail's [arc_test_suite](https://github.com/ValiMail/arc_test_suite). Every test is run in both modes:
 
-- mailauth is less strict on header tags and casing.
+- With `strict: true`, all validation tests pass except two where the suite, written against the ARC drafts, disagrees with RFC 8617: an ARC-Message-Signature with an empty `h=` (RFC 6376 requires a non-empty `h=` that includes From, so mailauth fails it in both modes), and one without `c=` that was signed `relaxed/relaxed` (the RFC default is `simple/simple`).
+- In the default mode, the four ARC-Seal tag syntax tests (duplicate tags, tag name case, an invalid tag name and an empty tag-spec) are accepted with a warning instead of failing, and the ARC-Message-Signature without `c=` passes through a `relaxed/relaxed` fallback.
 - Signing test suite is used for input; mailauth validates signatures and checks for the same `cv=` output.
-- All tests pass, aside from minor differences.
 
 ## License
 

package/bin/mailauth.js

@@ -103,6 +103,8 @@ program
     )
     .option('-x, --max-lookups <number>', 'Maximum allowed DNS lookups during SPF checks. Defaults to 10.', numberArg, 10)
     .option('-z, --max-void-lookups <number>', 'Maximum allowed DNS lookups that return no data (void lookups) during SPF checks. Defaults to 2.', numberArg, 2)
+    .option('--strict', 'Follow the RFCs exactly instead of the lenient defaults (for example, reject rsa-sha1 DKIM signatures).')
+    .option('--reject-rsa-sha1', 'Report rsa-sha1 DKIM signatures as dkim=policy and do not count them for DMARC, while keeping the other lenient defaults.')
     .action(runCommand(commandReport, 'Failed to generate report for the input message.'));
 
 program
@@ -113,7 +115,9 @@ program
     .requiredOption('-k, --private-key <file>', 'Path to the private key file used for signing.')
     .requiredOption('-d, --domain <domain>', 'Domain name to use in the DKIM signature (d= tag).')
     .requiredOption('-s, --selector <selector>', 'Selector to use in the DKIM signature (s= tag).')
-    .option('-a, --algo <algorithm>', 'Signing algorithm. Defaults to "rsa-sha256" or "ed25519-sha256" depending on the private key type.', 'rsa-sha256')
+    // no default value: without one the algorithm follows the key type, so an ed25519 key
+    // signs with ed25519-sha256 as the description says
+    .option('-a, --algo <algorithm>', 'Signing algorithm. Defaults to "rsa-sha256" or "ed25519-sha256" depending on the private key type.')
     .option('-c, --canonicalization <method>', 'Canonicalization method (c= tag). Defaults to "relaxed/relaxed".', 'relaxed/relaxed')
     .option('-t, --time <timestamp>', 'Signing time as a UNIX timestamp (t= tag). Defaults to the current time.', numberArg)
     .option(
@@ -123,6 +127,7 @@ program
     )
     .option('-h, --header-fields <fields>', 'Colon-separated list of header field names to include in the signature (h= tag).')
     .option('-o, --headers-only', 'If set, outputs only the DKIM signature headers without the message body.')
+    .option('--strict', 'Follow the RFCs exactly (for example, refuse to sign with rsa-sha1 or with an RSA key shorter than 1024 bits).')
     .action(runCommand(commandSign, 'Failed to sign the input message.'));
 
 program
@@ -133,11 +138,8 @@ program
     .requiredOption('-k, --private-key <file>', 'Path to the private key file used for sealing.')
     .requiredOption('-d, --domain <domain>', 'Domain name to use in the ARC seal (d= tag).')
     .requiredOption('-s, --selector <selector>', 'Selector to use in the ARC seal (s= tag).')
-    .option(
-        '-a, --algo <algorithm>',
-        'Sealing algorithm. Defaults to "rsa-sha256" or "ed25519-sha256" depending on the private key type. Note: RFC8617 only allows "rsa-sha256" (a= tag).',
-        'rsa-sha256'
-    )
+    // no default value: without one the algorithm follows the key type
+    .option('-a, --algo <algorithm>', 'Sealing algorithm. Defaults to "rsa-sha256" or "ed25519-sha256" depending on the private key type.')
     .option('-c, --canonicalization <method>', 'Canonicalization method. Note: RFC8617 only allows "relaxed/relaxed" (c= tag).', 'relaxed/relaxed')
     .option('-t, --time <timestamp>', 'Sealing time as a UNIX timestamp (t= tag). Defaults to the current time.', numberArg)
     .option('-h, --header-fields <fields>', 'Colon-separated list of header field names to include in the seal (h= tag).')
@@ -154,6 +156,7 @@ program
         'Path to a JSON file with cached DNS responses. When provided, DNS queries use these cached responses instead of performing actual DNS lookups.'
     )
     .option('-o, --headers-only', 'If set, outputs only the ARC seal headers without the message body.')
+    .option('--strict', 'Follow the RFCs exactly instead of the lenient defaults.')
     .addOption(
         rejectRepeated(
             new Option(
@@ -231,6 +234,12 @@ program
     .option('-o, --headers-only', 'If set, outputs only the SPF authentication header.')
     .option('-x, --max-lookups <number>', 'Maximum allowed DNS lookups during SPF checks. Defaults to 10.', numberArg, 10)
     .option('-z, --max-void-lookups <number>', 'Maximum allowed DNS lookups that return no data (void lookups) during SPF checks. Defaults to 2.', numberArg, 2)
+    .option(
+        '--max-elapsed-time <ms>',
+        'Maximum time in milliseconds for the whole SPF evaluation, after which the result is temperror. Not limited by default.',
+        numberArg
+    )
+    .option('--strict', 'Follow RFC 7208 exactly instead of the lenient defaults.')
     .action(runCommand(commandSpf, 'Failed to verify SPF for the email address.'));
 
 program

package/cli.md

@@ -78,7 +78,7 @@ mailauth report [options] [email]
 
 #### Options
 
-- `--client-ip x.x.x.x`, `-i x.x.x.x`: IP address of the remote client that sent the email. If not provided, it's parsed from the latest `Received` header.
+- `--client-ip x.x.x.x`, `-i x.x.x.x`: IP address of the remote client that sent the email. If not provided, it's parsed from the latest `Received` header: the connecting address in the TCP-info comment of its `from` clause (RFC 5321 section 4.4), never an address the client gave in its HELO.
 - `--sender user@example.com`, `-f user@example.com`: Email address from the MAIL FROM command. If not provided, it's parsed from the latest `Return-Path` header.
 - `--helo hostname`, `-e hostname`: Hostname from the HELO/EHLO command. Used in some SPF validations.
 - `--mta hostname`, `-m hostname`: Hostname of the server performing validations. Defaults to the local hostname.
@@ -86,6 +86,8 @@ mailauth report [options] [email]
 - `--verbose`, `-v`: Enables verbose output, displaying debugging information.
 - `--max-lookups number`, `-x number`: Sets the maximum number of DNS lookups for SPF checks. Defaults to `10`.
 - `--max-void-lookups number`, `-z number`: Sets the maximum number of void DNS lookups for SPF checks. Defaults to `2`.
+- `--strict`: Follows the RFCs exactly instead of the lenient defaults, for example an `rsa-sha1` DKIM signature is reported as `dkim=policy`. See [Strict mode](README.md#strict-mode).
+- `--reject-rsa-sha1`: Reports an `rsa-sha1` DKIM signature as `dkim=policy` and does not count it for DMARC, as `--strict` does, while every other check keeps the lenient default.
 
 #### Example
 
@@ -125,12 +127,13 @@ mailauth sign [options] [email]
 - `--private-key /path/to/private.key`, `-k /path/to/private.key`: Path to the private key used for signing.
 - `--domain example.com`, `-d example.com`: Domain name for the DKIM signature (`d=` tag).
 - `--selector selector`, `-s selector`: Selector for the DKIM key (`s=` tag).
-- `--algo algorithm`, `-a algorithm`: Signing algorithm (e.g., `rsa-sha256`). Defaults based on the private key type.
+- `--algo algorithm`, `-a algorithm`: Signing algorithm (e.g., `rsa-sha256`). Defaults to `rsa-sha256` for an RSA key and `ed25519-sha256` for an Ed25519 key.
 - `--canonicalization method`, `-c method`: Canonicalization method (e.g., `relaxed/relaxed`). Defaults to `relaxed/relaxed`.
 - `--time timestamp`, `-t timestamp`: Signing time as a Unix timestamp (`t=` tag).
-- `--header-fields "field1:field2"`, `-h "field1:field2"`: Colon-separated list of header fields to include in the signature (`h=` tag).
+- `--header-fields "field1:field2"`, `-h "field1:field2"`: Colon-separated list of header fields to include in the signature (`h=` tag). It must include `From`.
 - `--body-length length`, `-l length`: Maximum length of the body to include in the signature (`l=` tag).
 - `--headers-only`, `-o`: Outputs only the DKIM signature headers without the entire message.
+- `--strict`: Refuses to sign with `rsa-sha1` or with an RSA key shorter than 1024 bits (RFC 8301), and with a domain or selector that is not valid RFC 6376 syntax. Without it these are signed, and `--verbose` prints a warning.
 
 #### Example
 
@@ -176,6 +179,7 @@ mailauth seal [options] [email]
 - `--time timestamp`, `-t timestamp`: Sealing time as a Unix timestamp (`t=` tag).
 - `--header-fields "field1:field2"`, `-h "field1:field2"`: Colon-separated list of header fields to include in the seal (`h=` tag).
 - `--headers-only`, `-o`: Outputs only the ARC seal headers without the entire message.
+- `--strict`: Follows the RFCs exactly instead of the lenient defaults.
 
 **Seal-Only Options:**
 
@@ -244,6 +248,8 @@ mailauth spf [options]
 - `--headers-only`, `-o`: Outputs only the SPF authentication header.
 - `--max-lookups number`, `-x number`: Sets the maximum number of DNS lookups. Defaults to `10`.
 - `--max-void-lookups number`, `-z number`: Sets the maximum number of void DNS lookups. Defaults to `2`.
+- `--max-elapsed-time ms`: Maximum time in milliseconds for the whole SPF evaluation, after which the result is `temperror`. Not limited by default.
+- `--strict`: Follows RFC 7208 exactly instead of the lenient defaults.
 
 #### Example