mailauth 7.1.1 → 7.3.0

package/docs/bimi.md

@@ -12,7 +12,7 @@ Before looking up a BIMI record, mailauth checks the requirements of section 7.1
 - DMARC passed, with an effective policy other than `none` and without `t=y`.
 - Neither the DMARC record of the author domain nor the one of its Organizational Domain has `p=none` or `sp=none`, or `p=quarantine` with a `pct` other than 100. A record found at the author domain itself does not hide a lax record of the Organizational Domain. `dmarc()` passes both records to `bimi()`, for a DMARC result built elsewhere `bimi()` looks up the Organizational Domain's record itself.
 
-The record is looked up at `<selector>._bimi.<author domain>` and then at `<selector>._bimi.<organizational domain>`, where the selector comes from the `BIMI-Selector` header and defaults to `default`. A custom selector does not fall back to `default`. TXT records that do not start with `v=BIMI1` are ignored, several BIMI records are a failure.
+The record is looked up at `<selector>._bimi.<author domain>` and then at `<selector>._bimi.<organizational domain>`, where the selector comes from the `BIMI-Selector` header and defaults to `default`. A `BIMI-Selector` header without `v=BIMI1` or without a valid `s=` selector is ignored, and `default` is used (sections 5.1 and 7.2). A custom selector does not fall back to `default`. TXT records that do not start with `v=BIMI1` are ignored, several BIMI records are a failure.
 
 ```javascript
 const { authenticate } = require('mailauth');
@@ -26,14 +26,29 @@ const { bimi } = await authenticate(message, {
 
 ## Result Object Fields
 
-| Field        | Type     | Presence          | Description                                           |
-| ------------ | -------- | ----------------- | ----------------------------------------------------- |
-| `status`     | `object` | Always            | Resolution status object (see below)                  |
-| `location`   | `string` | Found             | HTTPS URL for the logo SVG file (from `l=` tag)       |
-| `authority`  | `string` | Found             | HTTPS URL for the VMC/CMC certificate (from `a=` tag) |
-| `preference` | `string` | When `p=` present | Logo preference value from DNS record                 |
-| `rr`         | `string` | Found             | Raw BIMI DNS TXT record                               |
-| `info`       | `string` | Always            | Formatted Authentication-Results header value         |
+| Field        | Type     | Presence             | Description                                                                                       |
+| ------------ | -------- | -------------------- | ------------------------------------------------------------------------------------------------- |
+| `status`     | `object` | Always               | Resolution status object (see below)                                                              |
+| `location`   | `string` | Found                | HTTPS URL for the logo SVG file (from `l=` tag)                                                   |
+| `authority`  | `string` | Found                | HTTPS URL for the VMC/CMC certificate (from `a=` tag)                                             |
+| `preference` | `string` | When `avp=` is valid | Avatar preference from the `avp=` tag, `personal` or `brand`. Other values are ignored            |
+| `rr`         | `string` | Found                | Raw BIMI DNS TXT record                                                                           |
+| `warnings`   | `array`  | When there are any   | Assertion Record deviations accepted because `strict` is not set, see [Strict Mode](#strict-mode) |
+| `info`       | `string` | Always               | Formatted Authentication-Results header value                                                     |
+
+## Strict Mode
+
+The Assertion Record uses the DKIM tag-list syntax, and the draft says that receivers must not fix syntax or capitalization errors (section 4.3). By default mailauth accepts the deviations below in the record and in the `BIMI-Selector` header, and lists them in `warnings`. With `strict: true` they are handled exactly:
+
+| Input                                                                                        | Default                                                    | `strict: true`                                                     |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| `v=` value in another case, such as `v=bimi1`                                                | used, warning `record-version-case`                        | record ignored (`none` if it is the only one)                      |
+| Upper case tag names, such as `L=`                                                           | used as the lower case tag, warning `record-tag-case`      | unknown tag, ignored                                               |
+| Duplicate tags or other tag-list syntax errors                                               | last duplicate wins, warning `record-syntax`               | `fail` (`invalid syntax in dns record`)                            |
+| Unencoded comma in `l=` or `a=`                                                              | used, warning `uri-comma`                                  | `fail` (`invalid location value...`, `invalid authority value...`) |
+| `l=` URI ending in another image format suffix, such as `.png`                               | used, warning `location-format`                            | `fail` (`unsupported image format in location value`)              |
+| `BIMI-Selector` header with `v=` in another case, `v=` not first, or a tag-list syntax error | used, warning `selector-version-case` or `selector-syntax` | header ignored, `default` is used                                  |
+| `BIMI-Selector` selector with underscores                                                    | used, warning `selector-syntax`                            | header ignored, `default` is used                                  |
 
 ## status Object
 
@@ -53,10 +68,10 @@ const { bimi } = await authenticate(message, {
 
 ### status.policy Object
 
-| Field           | Type     | Description                                        |
-| --------------- | -------- | -------------------------------------------------- |
-| `authority`     | `string` | VMC validation status (`"none"` before validation) |
-| `authority-uri` | `string` | URL of the authority evidence document             |
+| Field           | Type     | Description                                                                              |
+| --------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `authority`     | `string` | VMC validation status, `"none"` from `bimi()`, `"pass"` or `"fail"` from `validateVMC()` |
+| `authority-uri` | `string` | URL of the authority evidence document                                                   |
 
 ## Result Values
 
@@ -89,15 +104,16 @@ The `status.comment` field explains why BIMI was skipped:
 
 ## Fail Reasons
 
-| Comment                                     | Description                                                              |
-| ------------------------------------------- | ------------------------------------------------------------------------ |
-| `"multiple BIMI-Selector headers"`          | Message has more than one BIMI-Selector header                           |
-| `"missing bimi version in selector header"` | BIMI-Selector header missing `v=BIMI1`                                   |
-| `"missing bimi version in dns record"`      | DNS record missing `v=BIMI1`                                             |
-| `"missing location value in dns record"`    | Record has no `l=` value (and is not a declination), even if it has `a=` |
-| `"invalid location value in dns record"`    | `l=` value is not a valid HTTPS URL                                      |
-| `"invalid authority value in dns record"`   | `a=` value is not a valid HTTPS URL                                      |
-| `"multiple BIMI records for {name}"`        | More than one `v=BIMI1` record at the name                               |
+| Comment                                        | Description                                                                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `"multiple BIMI-Selector headers"`             | Message has more than one BIMI-Selector header                                                                             |
+| `"missing bimi version in dns record"`         | DNS record missing `v=BIMI1`                                                                                               |
+| `"missing location value in dns record"`       | Record has no `l=` value (and is not a declination), even if it has `a=`                                                   |
+| `"invalid location value in dns record"`       | `l=` value is not a valid HTTPS URL with a domain name (IP addresses, `localhost` and single-label hosts are not accepted) |
+| `"invalid authority value in dns record"`      | `a=` value is not a valid HTTPS URL with a domain name                                                                     |
+| `"invalid syntax in dns record"`               | Tag-list syntax error, such as a duplicate tag (strict mode)                                                               |
+| `"unsupported image format in location value"` | `l=` ends with an image format suffix other than SVG or SVGZ (strict mode)                                                 |
+| `"multiple BIMI records for {name}"`           | More than one `v=BIMI1` record at the name                                                                                 |
 
 ## Temperror Reasons
 
@@ -117,24 +133,44 @@ const bimiResult = await bimi(data);
 const vmcResult = await validateVMC(bimiResult, options);
 ```
 
+### Options
+
+| Option            | Type         | Default  | Description                                                                                                      |
+| ----------------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| `strict`          | `boolean`    | `false`  | Validate the logo files exactly against the SVG Tiny PS profile, see [Logo SVG Validation](#logo-svg-validation) |
+| `now`             | `Date`       | now      | Time used for the certificate validity checks (passed to `@postalsys/vmc`)                                       |
+| `maxLogoSize`     | `number`     | `65536`  | Maximum size of the logo file in bytes, also the limit for an uncompressed SVGZ file                             |
+| `maxEvidenceSize` | `number`     | `262144` | Maximum size of the evidence document in bytes                                                                   |
+| `timeout`         | `number`     | `30000`  | Time limit in milliseconds for each download, including redirects and the response body                          |
+| `dispatcher`      | `Dispatcher` |          | undici dispatcher for the downloads, for example to use a proxy                                                  |
+
+Downloads only use HTTPS URLs whose host is a domain name. Redirects are followed up to 3 times when the target is such a URL as well, and the body is read up to the size limit only (section 7.6 of the draft allows a retrieval limit). The limits also apply to `locationPath` and `authorityPath` buffers.
+
 ### VMC Result Object
 
-| Field       | Type     | Description                                             |
-| ----------- | -------- | ------------------------------------------------------- |
-| `location`  | `object` | Logo file fetch result                                  |
-| `authority` | `object` | VMC/CMC fetch and validation result                     |
-| `headers`   | `object` | Ready-to-use email headers (only on validation success) |
+| Field       | Type     | Description                                                       |
+| ----------- | -------- | ----------------------------------------------------------------- |
+| `location`  | `object` | Logo file fetch result                                            |
+| `authority` | `object` | VMC/CMC fetch and validation result                               |
+| `headers`   | `object` | Ready-to-use email headers (only on validation success)           |
+| `status`    | `object` | Updated BIMI status, when `bimiData.status.result` was `pass`     |
+| `info`      | `string` | Updated Authentication-Results entry, along with `status`         |
+| `warnings`  | `array`  | Accepted SVG Tiny PS profile deviations of the logo files, if any |
+
+The `info` of `bimi()` covers record discovery only, it reports `bimi=pass policy.authority=none` before anything is downloaded. When `validateVMC()` is used, use its `info` for the Authentication-Results header instead (section 7.7 of the draft): the result is `fail` when the indicator can not be retrieved (`failed to retrieve indicator`), fails SVG validation (`invalid SVG indicator`), the evidence document does not validate (`evidence document validation failed`) or its logo does not match the indicator (`indicator does not match evidence document`). When the record has `a=`, `policy.authority` is `pass` if the evidence document validated and its logo matches, and `fail` otherwise. `authenticate()` does not download anything, so its `bimi.info` is the discovery result.
 
 ### location Object
 
-| Field       | Type      | Description                          |
-| ----------- | --------- | ------------------------------------ |
-| `url`       | `string`  | Logo URL                             |
-| `success`   | `boolean` | Whether fetch succeeded              |
-| `logoFile`  | `string`  | Base64-encoded logo SVG (on success) |
-| `error`     | `object`  | Error details (on failure)           |
-| `hashAlgo`  | `string`  | Hash algorithm used for verification |
-| `hashValue` | `string`  | Calculated hash of the logo file     |
+| Field       | Type      | Description                                                    |
+| ----------- | --------- | -------------------------------------------------------------- |
+| `url`       | `string`  | Logo URL                                                       |
+| `success`   | `boolean` | Whether the logo was fetched and passed SVG validation         |
+| `logoFile`  | `string`  | Base64-encoded logo SVG, uncompressed if it was SVGZ (success) |
+| `error`     | `object`  | Error details (on failure)                                     |
+| `hashAlgo`  | `string`  | Hash algorithm used for verification                           |
+| `hashValue` | `string`  | Calculated hash of the logo file                               |
+
+The logo downloaded from `l=` is always checked with the SVG validator (section 7.6 of the draft), also when the record has no `a=` evidence document. An SVGZ file is uncompressed first. A logo that fails validation gives `success: false` with the error code `SVG_VALIDATION_FAILED`, and no headers are generated.
 
 ### authority Object
 
@@ -149,13 +185,13 @@ const vmcResult = await validateVMC(bimiResult, options);
 
 ### headers Object
 
-Present only when VMC validation succeeds. Contains ready-to-use email headers.
+Present only when the logo passes SVG validation and, if the record has an `a=` tag, the evidence document validates and its logo hash matches. Contains ready-to-use email headers.
 
-| Field        | Type     | Presence         | Description                                        |
-| ------------ | -------- | ---------------- | -------------------------------------------------- |
-| `indicator`  | `string` | Always           | BIMI-Indicator header with base64-encoded SVG logo |
-| `location`   | `string` | Always           | BIMI-Location header with logo URL                 |
-| `preference` | `string` | `p=` tag present | BIMI-Logo-Preference header                        |
+| Field        | Type     | Presence                              | Description                                                                                     |
+| ------------ | -------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `indicator`  | `string` | Always                                | BIMI-Indicator header with base64-encoded SVG logo                                              |
+| `location`   | `string` | Always                                | BIMI-Location header with the logo URL, and the `a=` evidence document URL when it was verified |
+| `preference` | `string` | `preference` is `personal` or `brand` | BIMI-Logo-Preference header, for example `BIMI-Logo-Preference: avp=brand`                      |
 
 These headers should be added to messages after successful BIMI validation. The MTA should:
 
@@ -164,14 +200,65 @@ These headers should be added to messages after successful BIMI validation. The
 
 ### VMC Error Codes
 
-| Code                    | Description                            |
-| ----------------------- | -------------------------------------- |
-| `HTTP_REQUEST_FAILED`   | HTTP request failed                    |
-| `MISSING_VMC_LOGO`      | VMC does not contain a logo file       |
-| `INVALID_MEDIATYPE`     | Logo media type is not `image/svg+xml` |
-| `INVALID_LOGO_HASH`     | Logo hash does not match certificate   |
-| `SVG_VALIDATION_FAILED` | SVG file failed validation             |
-| `VMC_DOMAIN_MISMATCH`   | Domain not found in certificate SAN    |
+| Code                        | Description                                                                                                                              |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `HTTP_REQUEST_FAILED`       | HTTP request failed                                                                                                                      |
+| `HTTP_REQUEST_TIMEOUT`      | The download took longer than `timeout`                                                                                                  |
+| `HTTP_REDIRECT_NOT_ALLOWED` | A redirect to a URL that is not HTTPS with a domain name, or more than 3 redirects. `redirect` has the target                            |
+| `INVALID_URL`               | The URL is not HTTPS, or its host is an IP address, `localhost` or a single label                                                        |
+| `FILE_TOO_LARGE`            | The file, or the uncompressed SVGZ logo, is larger than the size limit                                                                   |
+| `MISSING_VMC_LOGO`          | VMC does not contain a logo file                                                                                                         |
+| `INVALID_MEDIATYPE`         | Logo media type is not `image/svg+xml`                                                                                                   |
+| `INVALID_LOGO_HASH`         | Logo hash does not match certificate                                                                                                     |
+| `SVG_VALIDATION_FAILED`     | SVG file failed validation, `details` has the validator's error code (`INVALID_SVGZ_FILE` for an SVGZ file that can not be uncompressed) |
+| `VMC_DOMAIN_MISMATCH`       | Domain not found in certificate SAN                                                                                                      |
+
+## Logo SVG Validation
+
+`validateBimiSvg(logo, options)` (also `validateSvg` in `mailauth/lib/bimi/validate-svg`) checks a logo against the SVG Tiny Portable/Secure profile of [draft-svg-tiny-ps-abrotman](https://datatracker.ietf.org/doc/html/draft-svg-tiny-ps-abrotman). It returns `true` or throws an error with one of the codes below. `validateVMC()` runs it on the logo from `l=` and on the logo embedded in the evidence document, with the `strict` option of `validateVMC()`, and lists the warnings in `warnings` of its result.
+
+```javascript
+const { validateBimiSvg } = require('mailauth');
+
+const warnings = [];
+validateBimiSvg(logo, { strict: false, warnings }); // throws if the logo is not valid
+```
+
+The root element must be `svg` in the `http://www.w3.org/2000/svg` namespace. Some rules of the profile do not make a logo unsafe. By default a logo that breaks them is accepted and a marker is added to the `warnings` array, with `strict: true` it is rejected:
+
+| Warning                | Rule                                                                                                                                                                             |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `svg-version`          | The root element has `version="1.2"` (`INVALID_SVG_VERSION`)                                                                                                                     |
+| `svg-title-count`      | Only one `title` child of the root element (`LOGO_MULTIPLE_TITLES`)                                                                                                              |
+| `svg-title-position`   | `title` is the first child of the root element, and not used elsewhere (`LOGO_INVALID_ELEMENT`)                                                                                  |
+| `svg-attribute-value`  | `zoomAndPan`, `externalResourcesRequired`, `focusable`, `snapshotTime`, `playbackOrder`, `timelineBegin` and `editable` have their only allowed value (`LOGO_INVALID_ATTRIBUTE`) |
+| `svg-empty-desc`       | A `desc` element is not empty (`LOGO_INVALID_CONTENT`)                                                                                                                           |
+| `svg-element`          | Only the elements of the validation schema, not the other static SVG elements listed below (`LOGO_INVALID_ELEMENT`)                                                              |
+| `svg-foreign-element`  | No elements in other namespaces outside `metadata` (`LOGO_INVALID_ELEMENT`)                                                                                                      |
+| `svg-metadata-content` | `metadata` has text content only (`LOGO_INVALID_ELEMENT`)                                                                                                                        |
+
+The rules below apply in both modes. Namespaces are resolved, and elements are checked against an allowlist: the element set of the validation schema in section 7 of the profile, plus static SVG 1.1 rendering elements found in published logos (`style`, `clipPath`, `mask`, `pattern`, `symbol`, `marker`, `tspan`, `textPath`, filter primitives other than `feImage`, and a few font elements). Script, interactivity, linking, multimedia, `image`, `switch`, `foreignObject` and animation elements are rejected, as are XHTML and MathML elements and SVG elements inside `metadata`. Elements in other namespaces, such as RDF metadata, are allowed by default.
+
+These are rejected in every element and namespace:
+
+- event handler attributes (any attribute whose local name starts with `on`)
+- `href` in any namespace (XLink, no namespace, or another prefix) unless it is a same-document `#fragment` reference
+- `url()` references that are not `#fragment`, `@import`, CSS image functions and CSS escapes, in `style` elements, `style` attributes and presentation attributes
+- a non-empty `xml:base`
+- processing instructions such as `xml-stylesheet`, DTDs with an internal subset, and entity references other than the predefined ones and character references
+- markup that an HTML parser would read differently: `<` inside CDATA sections, comments that contain `<`, `>` or `--`, and a `font` element with `color`, `face` or `size` attributes
+
+| Code                      | Description                                                              |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `INVALID_XML_FILE`        | Not well-formed XML, or XML features that are not allowed (DTD, entity)  |
+| `INVALID_SVG_FILE`        | The root element is not `svg` in the SVG namespace                       |
+| `INVALID_BASE_PROFILE`    | `baseProfile` is not `tiny-ps`                                           |
+| `LOGO_MISSING_TITLE`      | No `title` child of the root element, or it is empty                     |
+| `LOGO_INVALID_ROOT_ATTRS` | The root element has `x` or `y` attributes                               |
+| `LOGO_INVALID_ELEMENT`    | An element that is not allowed, `details.element` names it               |
+| `LOGO_INVALID_ATTRIBUTE`  | An event handler attribute or `xml:base`, `details.attribute` names it   |
+| `LOGO_INCLUDES_REFERENCE` | An external reference, `details.link` has the value                      |
+| `LOGO_INVALID_CONTENT`    | A processing instruction, unexpected markup in text or comments, nesting |
 
 ## Example Output
 
@@ -192,8 +279,8 @@ These headers should be added to messages after successful BIMI validation. The
     },
     "location": "https://example.com/bimi/logo.svg",
     "authority": "https://example.com/bimi/vmc.pem",
-    "preference": "self",
-    "rr": "v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem; p=self",
+    "preference": "brand",
+    "rr": "v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem; avp=brand",
     "info": "bimi=pass header.selector=default header.d=example.com policy.authority=none policy.authority-uri=https://example.com/bimi/vmc.pem"
 }
 ```
@@ -283,8 +370,20 @@ These headers should be added to messages after successful BIMI validation. The
     },
     "headers": {
         "indicator": "BIMI-Indicator: PHN2ZyB4bWxucz0i...",
-        "location": "BIMI-Location: v=BIMI1; l=https://example.com/bimi/logo.svg",
-        "preference": "BIMI-Logo-Preference: self"
-    }
+        "location": "BIMI-Location: v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem",
+        "preference": "BIMI-Logo-Preference: avp=brand"
+    },
+    "status": {
+        "result": "pass",
+        "header": {
+            "selector": "default",
+            "d": "example.com"
+        },
+        "policy": {
+            "authority": "pass",
+            "authority-uri": "https://example.com/bimi/vmc.pem"
+        }
+    },
+    "info": "bimi=pass policy.authority=pass policy.authority-uri=\"https://example.com/bimi/vmc.pem\" header.selector=default header.d=example.com"
 }
 ```

package/docs/dkim.md

@@ -67,7 +67,7 @@ Each entry in the `results` array has the following structure:
 | ------------ | --------------- | --------------- | ----------------------------------------------------------------------------------------------------- |
 | `result`     | `string`        | Always          | Verification result code (see below)                                                                  |
 | `comment`    | `string`        | On error/info   | Human-readable explanation                                                                            |
-| `aligned`    | `string\|false` | DKIM signatures | DMARC-aligned domain, or false                                                                        |
+| `aligned`    | `string\|false` | DKIM signatures | DMARC-aligned domain, or false (also when From does not yield a single Author Domain)                 |
 | `header`     | `object`        | Always          | Signature header info                                                                                 |
 | `policy`     | `object`        | Policy result   | Policy violation details                                                                              |
 | `underSized` | `number`        | Body limited    | Number of unsigned bytes                                                                              |
@@ -99,46 +99,47 @@ Each entry in the `results` array has the following structure:
 
 Common values for `status.comment`:
 
-| Comment                                             | Description                                                                                          |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `"body hash did not verify"`                        | Calculated body hash does not match `bh=` tag                                                        |
-| `"bad signature"`                                   | Cryptographic signature verification failed                                                          |
-| `"invalid expiration"`                              | Expiration timestamp is before signing timestamp                                                     |
-| `"expired"`                                         | Signature has expired (past `x=` timestamp)                                                          |
-| `"no key"`                                          | No DKIM key found in DNS                                                                             |
-| `"unknown key version"`                             | Unsupported key version in DNS record                                                                |
-| `"unknown key type"`                                | Unsupported key type in DNS record                                                                   |
-| `"invalid public key"`                              | Public key in DNS record is malformed, or revoked (empty `p=`)                                       |
-| `"inappropriate hash algorithm"`                    | The key record `h=` tag does not list the hash algorithm of the signature (both modes)               |
-| `"key not for email"`                               | The key record `s=` tag does not list `email` or `*` (both modes)                                    |
-| `"From field not signed"`                           | The `h=` tag does not include From (both modes, RFC 6376 section 6.1.1)                              |
-| `"weak algorithm"`                                  | Strict mode or `rejectRsaSha1`: rsa-sha1 signature (RFC 8301)                                        |
-| `"signature syntax error"`                          | Strict mode: the signature is not valid RFC 6376 syntax                                              |
-| `"signature missing required tag"`                  | Strict mode: `v=`, `a=`, `b=`, `bh=`, `d=`, `h=` or `s=` is missing                                  |
-| `"incompatible version"`                            | Strict mode: `v=` is not 1                                                                           |
-| `"domain mismatch"`                                 | Strict mode: the `i=` domain is not `d=` or its subdomain, or is a subdomain while the key has `t=s` |
-| `"unsupported query method"`                        | Strict mode: `q=` does not list `dns/txt`                                                            |
-| `"inappropriate key algorithm"`                     | Strict mode: the key type does not match the signature algorithm                                     |
-| `"unknown algorithm"`, `"unknown canonicalization"` | Strict mode: the signature can not be processed                                                      |
-| `"DNS failure: {code}"`                             | DNS lookup failed with error code                                                                    |
-| `"message not signed"`                              | No DKIM-Signature headers found                                                                      |
+| Comment                                             | Description                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `"body hash did not verify"`                        | Calculated body hash does not match `bh=` tag                                                                                                                      |
+| `"bad signature"`                                   | Cryptographic signature verification failed                                                                                                                        |
+| `"invalid expiration"`                              | Expiration timestamp is before signing timestamp                                                                                                                   |
+| `"expired"`                                         | Signature has expired (past `x=` timestamp)                                                                                                                        |
+| `"no key"`                                          | No DKIM key found in DNS, or the key record name can not exist in the DNS (an empty label, a label over 63 octets or a name over 253 octets), which is not queried |
+| `"unknown key version"`                             | Unsupported key version in DNS record                                                                                                                              |
+| `"unknown key type"`                                | Unsupported key type in DNS record                                                                                                                                 |
+| `"invalid public key"`                              | Public key in DNS record is malformed, or revoked (empty `p=`)                                                                                                     |
+| `"inappropriate hash algorithm"`                    | The key record `h=` tag does not list the hash algorithm of the signature (both modes)                                                                             |
+| `"key not for email"`                               | The key record `s=` tag does not list `email` or `*` (both modes)                                                                                                  |
+| `"From field not signed"`                           | The `h=` tag does not include From (both modes, RFC 6376 section 6.1.1)                                                                                            |
+| `"weak algorithm"`                                  | Strict mode or `rejectRsaSha1`: rsa-sha1 signature (RFC 8301)                                                                                                      |
+| `"signature syntax error"`                          | Strict mode: the signature is not valid RFC 6376 syntax. Both modes: `d=` has a character that can not be in a host name, such as `/`, `?`, `#`, `@` or `:`        |
+| `"signature missing required tag"`                  | Strict mode: `v=`, `a=`, `b=`, `bh=`, `d=`, `h=` or `s=` is missing                                                                                                |
+| `"incompatible version"`                            | Strict mode: `v=` is not 1                                                                                                                                         |
+| `"domain mismatch"`                                 | Strict mode: the `i=` domain is not `d=` or its subdomain, or is a subdomain while the key has `t=s`                                                               |
+| `"unsupported query method"`                        | Strict mode: `q=` does not list `dns/txt`                                                                                                                          |
+| `"inappropriate key algorithm"`                     | The key type does not match the signature algorithm (both modes)                                                                                                   |
+| `"unknown algorithm"`, `"unknown canonicalization"` | Strict mode: the signature can not be processed                                                                                                                    |
+| `"DNS failure: {code}"`                             | DNS lookup failed with error code                                                                                                                                  |
+| `"message not signed"`                              | No DKIM-Signature headers found                                                                                                                                    |
 
 ## Warnings
 
 In the default mode `status.warnings` lists what was accepted although strict mode would have rejected it. The array is only present when there is something to report, and it is never written into the Authentication-Results text.
 
-| Warning                                              | Meaning                                                                                                                                                       |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rsa-sha1`                                           | The signature uses rsa-sha1, which RFC 8301 section 3.1 does not allow. A domain can refuse it with `h=sha256` in its key record, which applies in both modes |
-| `tag-syntax`                                         | Duplicate tags, upper case tag names, a malformed `t=`, `x=` or `l=` value, or a `d=` or `s=` that is not a domain name                                       |
-| `missing-v`, `missing-h` (and the other `missing-*`) | A required tag is missing. Without `h=` the default header list is used, which includes From                                                                  |
-| `invalid-v`                                          | `v=` is not `1`                                                                                                                                               |
-| `identity-domain`                                    | The `i=` domain is not `d=` or its subdomain, or it is a subdomain while the key record has `t=s`                                                             |
-| `invalid-expiration`                                 | `x=` is equal to `t=`. An `x=` before `t=` is `neutral (invalid expiration)` in both modes                                                                    |
-| `query-method`                                       | `q=` does not list `dns/txt`                                                                                                                                  |
-| `key-syntax`                                         | The key record is not valid tag-list syntax                                                                                                                   |
-| `key-v-syntax`                                       | The key record `v=` is not the first tag, or not exactly `DKIM1`                                                                                              |
-| `key-type-inferred`                                  | An Ed25519 key was recognized from its length, the key record has no `k=ed25519`                                                                              |
+| Warning                                              | Meaning                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rsa-sha1`                                           | The signature uses rsa-sha1, which RFC 8301 section 3.1 does not allow. A domain can refuse it with `h=sha256` in its key record, which applies in both modes                                                                                                                                                                                   |
+| `tag-syntax`                                         | Duplicate tags, upper case tag names, a malformed `c=`, `t=`, `x=` or `l=` value, an `l=` larger than the canonicalized body, or a `d=` or `s=` that is not a domain name, or that makes the key record name longer than 253 octets. A `d=` with a character that can not be in a host name is `neutral (signature syntax error)` in both modes |
+| `missing-v`, `missing-h` (and the other `missing-*`) | A required tag is missing. Without `h=` the default header list is used, which includes From                                                                                                                                                                                                                                                    |
+| `invalid-v`                                          | `v=` is not `1`                                                                                                                                                                                                                                                                                                                                 |
+| `identity-domain`                                    | The `i=` domain is not `d=` or its subdomain, or it is a subdomain while the key record has `t=s`                                                                                                                                                                                                                                               |
+| `invalid-expiration`                                 | `x=` is equal to `t=`. An `x=` before `t=` is `neutral (invalid expiration)` in both modes                                                                                                                                                                                                                                                      |
+| `query-method`                                       | `q=` does not list `dns/txt`                                                                                                                                                                                                                                                                                                                    |
+| `key-syntax`                                         | The key record is not valid tag-list syntax, or a `k=`, `s=` or `t=` value has whitespace inside it, which is removed                                                                                                                                                                                                                           |
+| `key-v-syntax`                                       | The key record `v=` is not the first tag, or not exactly `DKIM1`                                                                                                                                                                                                                                                                                |
+| `key-type-inferred`                                  | An Ed25519 key was recognized from its length, the key record has no `k=ed25519`                                                                                                                                                                                                                                                                |
+| `key-ed25519-spki`                                   | An Ed25519 key record has the key as a SubjectPublicKeyInfo structure instead of the bare 32 octet key (RFC 8463 section 4.2). Strict mode reports `invalid public key`                                                                                                                                                                         |
 
 A negative `l=` value is read as no limit in the default mode, so the whole body is covered and nothing is left unsigned. Strict mode reports it as a syntax error.
 

package/docs/dkim2.md

@@ -0,0 +1,154 @@
+# DKIM2 Result Reference
+
+This document describes the result object returned by `dkim2Verify()` and how mailauth reads the parts of the DKIM2 drafts that are open to interpretation.
+
+> [!WARNING]
+> DKIM2 support is experimental. It is built against these Internet-Drafts, which are not finished and can change:
+>
+> - [draft-ietf-dkim-dkim2-spec-06](https://www.ietf.org/archive/id/draft-ietf-dkim-dkim2-spec-06.txt) (28 August 2026), the protocol
+> - [draft-ietf-dkim-dkim2-dns-00](https://www.ietf.org/archive/id/draft-ietf-dkim-dkim2-dns-00.txt) (20 July 2026), the key records. The specification cites its predecessor, draft-chuang-dkim2-dns-04, mailauth follows the working group version
+> - [draft-ietf-dkim-dkim2-bcp-01](https://www.ietf.org/archive/id/draft-ietf-dkim-dkim2-bcp-01.txt) (9 September 2026), best practices
+> - [draft-gondwana-dkim2-authres-00](https://datatracker.ietf.org/doc/html/draft-gondwana-dkim2-authres-00) (3 September 2026, not adopted by the working group), the `dkim2` Authentication-Results method
+>
+> Section numbers below refer to draft-ietf-dkim-dkim2-spec-06 unless noted otherwise.
+
+## Overview
+
+```javascript
+const { dkim2Verify } = require('mailauth');
+
+const result = await dkim2Verify(message, {
+    mailFrom: 'bounce@list.example.org',
+    rcptTo: ['member@example.net']
+});
+```
+
+The whole message gets one result (section 11.1):
+
+| Result      | Meaning                                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------------------- |
+| `pass`      | Every instance, signature and chain of custody check passed                                                |
+| `fail`      | A hash or signature was not correct, or a `donotmodify`, `donotexplode` or replay check failed             |
+| `permerror` | The message could not be verified: malformed or missing header fields, missing keys, an envelope mismatch… |
+| `temperror` | A public key could not be fetched because of a temporary DNS failure                                       |
+| `none`      | The message has no DKIM2 header fields                                                                     |
+
+When there are several problems, `fail` wins over `permerror`, and `permerror` over `temperror`, so that a cryptographic failure is never reported as temporary (section 10.4: such failures "MUST NOT provoke 4xx SMTP replies").
+
+## Top-Level Result Object
+
+| Field        | Type       | Description                                                                                               |
+| ------------ | ---------- | --------------------------------------------------------------------------------------------------------- |
+| `status`     | `object`   | `{ result, comment, header }`, see below                                                                  |
+| `info`       | `string`   | Authentication-Results resinfo, such as `dkim2=pass (i=1 example.com pass) header.d=example.com`          |
+| `errors`     | `object[]` | Every problem found, in the order the checks ran: `{ result, message, i, m }`                             |
+| `instances`  | `object[]` | One entry per `Message-Instance`, see below                                                               |
+| `signatures` | `object[]` | One entry per `DKIM2-Signature`, see below                                                                |
+| `replay`     | `object`   | `{ key, exploded }`: the `m=1` hashes that identify the message, and whether a signature has `f=exploded` |
+
+### status
+
+| Field      | Type       | Description                                                                                                                                         |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `result`   | `string`   | One of the results above                                                                                                                            |
+| `comment`  | `string`   | The human-readable string of the reported problem, as specified in section 11, such as `DKIM2-Signature i=1 rsa incorrect signature`                |
+| `header.d` | `string`   | `d=` of the `i=1` signature, the originator (draft-gondwana-dkim2-authres-00 section 3.2.1)                                                         |
+| `header.i` | `number`   | `i=` of the signature the problem is reported against. Not set for `pass`, or for a problem of the whole message                                    |
+| `warnings` | `string[]` | `mail-from-not-checked` and/or `rcpt-to-not-checked` when that part of the SMTP envelope was not given, see [Envelope Warnings](#envelope-warnings) |
+
+`header.d` is an authenticated identity only when the result is `pass`.
+
+### Envelope Warnings
+
+The chain of custody is what stops DKIM2 replay: the highest `DKIM2-Signature` names the MAIL FROM and RCPT TO the message was delivered with (section 11.4). A library does not see the SMTP transaction, so this check only runs for the parts of the envelope you pass as `mailFrom` and `rcptTo`. When one is missing, `status.warnings` says so:
+
+- `mail-from-not-checked`: `mailFrom` was not given (`""` counts as given, it is the null sender)
+- `rcpt-to-not-checked`: `rcptTo` was not given
+
+Without them an unchanged copy of the message, sent to anyone, passes as well. The warnings do not change the result and are never written into `info`, in the same way as the DKIM1 warnings. `authenticate()` passes its `sender` and `rcptTo` options on, so set `rcptTo` there to have the recipients checked.
+
+### instances
+
+| Field    | Type       | Description                                                                                                                                                      |
+| -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `m`      | `number`   | Revision number                                                                                                                                                  |
+| `hashes` | `object[]` | `{ algorithm, header, body }` for every supported hash algorithm. `body` is `unknown` when a later hop declared that the body can not be recreated (`"b": null`) |
+| `recipe` | `object`   | When the instance has a Recipe: `{ headers, body }`, the header field names it recreates, and `unchanged`, `recipe` or `unrecoverable` for the body              |
+
+### signatures
+
+| Field           | Type       | Description                                                                  |
+| --------------- | ---------- | ---------------------------------------------------------------------------- |
+| `i`             | `number`   | Sequence number                                                              |
+| `m`             | `number`   | Highest `Message-Instance` covered                                           |
+| `signingDomain` | `string`   | `d=`                                                                         |
+| `timestamp`     | `number`   | `t=`, seconds since the epoch, and `signTime` as an ISO 8601 string          |
+| `mailFrom`      | `string`   | Decoded `mf=`, with angle brackets                                           |
+| `rcptTo`        | `string[]` | Decoded `rt=`                                                                |
+| `nextDomain`    | `string`   | `nd=`                                                                        |
+| `nonce`         | `string`   | `n=`                                                                         |
+| `flags`         | `string[]` | `f=`, including flags mailauth does not know                                 |
+| `status`        | `object`   | `{ result, comment }` for this hop, including the errors reported against it |
+| `values`        | `object[]` | One entry per signature value in `s=`, see below                             |
+
+Each entry of `values` has `selector`, `algorithm`, `result` (`pass`, `fail`, `permerror`, `temperror`, or `none` for an algorithm that is not supported and so ignored, section 3.4), and when available `comment`, `rr` (the key record), `modulusLength` and `testing` (the key record has `t=y`; draft-ietf-dkim-dkim2-dns-00 says a signer in testing mode must be treated like unsigned mail, which is up to you).
+
+## What Is Checked
+
+1. **Syntax and numbering (section 11.2).** Every `Message-Instance` and `DKIM2-Signature` is parsed. `m=` and `i=` start at 1 with no gaps, no instance is above the highest `m=` of a signature, no hash algorithm or selector repeats, and no signing algorithm is used more than twice.
+2. **Recipes (sections 5 and 11).** Starting from the message as it is, the Recipe of every instance is applied to recreate the one before it.
+3. **Hashes (section 11.7).** The header and body hashes of every instance are compared with the recreated message.
+4. **Timestamps (sections 8.4 and 11.3).** A signature older than `maxSignatureAge` (14 days), or more than `maxFutureTime` (5 minutes) in the future, is a PERMERROR.
+5. **Chain of custody (sections 8.7, 8.8, 9.4 and 11.4).** `d=` matches the `mf=` domain of every signature, `nd=` names the next signer exactly, the MAIL FROM of every hop matches a RCPT TO of the hop before it, and, for the parts of the envelope given as `mailFrom` and `rcptTo`, the highest signature matches the delivery. A missing part is reported in `status.warnings`.
+6. **Signatures (sections 9.6, 11.5 and 11.6).** Every signature value with a supported algorithm is checked with its key.
+7. **Requests (section 11.8).** `donotmodify` and `donotexplode` were honored by the later hops.
+8. **Replay (section 11.9).** When `checkReplay` is given and reports a duplicate, the message fails unless a signature has `f=exploded`.
+
+## How the Drafts Are Read
+
+The drafts leave some questions open. mailauth answers them like this:
+
+- **Unknown keys in a Recipe step.** Section 2 says unrecognised JSON fields "MUST be ignored", while the JSON schema of section 5 sets `additionalProperties: false` for steps. Unknown keys are ignored, but a step still needs exactly one of `c` and `d`.
+- **Recipe validity.** A Recipe that does not follow the schema (no `h` and no `b`, an empty `h`, an upper case header field name, a `c` range that is out of order or past the last line or header field, a `d` string with CR or LF) is reported as `Message-Instance m=<x> contains invalid JSON: <reason>`. Recipes for header fields that are not signed (section 4) are ignored.
+- **Only unknown signature algorithms.** A `DKIM2-Signature` whose `s=` has no signature value with a supported algorithm is a PERMERROR, `DKIM2-Signature i=<x> has no supported signature algorithm`. Section 3.4 has the unknown algorithms ignored, so nothing could be verified and nothing was found incorrect, which section 11.1 defines as PERMERROR. The FAIL of section 11.6 step 3 is about the signatures that can be checked. The turscar vectors, written for spec-02, expect FAIL here, croessner/dkim2, written for spec-06, reports PERMERROR.
+- **Signature values that can not be checked.** Section 11.6 requires every signature value that can be checked to pass. A value whose key is missing or broken can not be checked: when at least one other value passes and none fails, the signature passes and the key problem is reported in its `values` entry. When no value could be checked, the key problem is the result.
+- **Chain of custody between hops.** Section 9.4 matches the MAIL FROM of a hop with a RCPT TO of the hop before it. A signature with `nd=` has no MAIL FROM, and the null MAIL FROM `<>` has no domain, so for those the `d=` is matched instead (section 9.3 says the signer of such a hop holds a key "associated with a domain in the RCPT TO entry"). Section 8.8 waives only the `d=` and `mf=` match for the null MAIL FROM, not the chain of custody, so a hop with `mf=<>` can not be added by a domain the message was never sent to.
+- **`d=` and `mf=`.** Section 8.8 requires every signature's `d=` to match its `mf=` domain, so this is checked for every signature, not only the highest as section 11.4 describes.
+- **Envelope.** The chain of custody against the SMTP envelope is only checked for the parts given as `mailFrom` and `rcptTo`, a missing part gives a warning. When either is given and the highest signature has `nd=`, the result is `DKIM2-Signature i=<x> unexpected nd= tag`, since the delivery can then only be accepted on out-of-band arrangements (section 9.3).
+- **Future timestamps.** Section 8.4 allows ignoring signatures with a timestamp in the future, and draft-ietf-dkim-dkim2-bcp-01 section 3.6 lets verifiers treat them with suspicion. A timestamp more than `maxFutureTime` seconds ahead (default 300, as croessner/dkim2 does) is a PERMERROR, `DKIM2-Signature i=<x> signature timestamp is in the future`. `maxFutureTime: false` turns the check off.
+- **RSA key size.** Verifiers have to handle 1024 to 2048 bits and may handle more (section 3.2). mailauth accepts up to 8192 bits, a longer key is `public key <selector> is too long`.
+- **`donotmodify`.** Section 8.10 allows adding header fields. A message passes when every signed header field of the instance the request was made on is still present, in the same order, and the body hash is unchanged. A null body Recipe after the request counts as a change.
+- **Key records.** Records are read with the tag-list rules of draft-ietf-dkim-dkim2-dns-00: tag names are case sensitive, `v=`, when present, is exactly `DKIM1` and the first tag, duplicate tags and other syntax errors make the record unusable, several TXT records are an error, and `k=` has to match the algorithm (`rsa` for `rsa-sha256`, `ed25519` for `ed25519-sha256`). The retired `h=`, `n=` and `s=` tags are ignored, and so is the `t=s` flag, as DKIM2 has no `i=` identity. Ed25519 keys are published as the bare 32 byte key (RFC 8463). RSA keys need at least 1024 bits and the public exponent 65537 (section 3.2).
+- **Leading whitespace in Recipe data.** The header hash removes the whitespace after the colon, so `{"d": [" value"]}` and `{"d": ["value"]}` recreate the same header field.
+
+### Error Strings Not in the Specification
+
+Section 11 lists the human-readable strings to use. These cases have no string there, so mailauth adds its own:
+
+- `Message-Instance m=<x> appears more than once` and `DKIM2-Signature i=<x> appears more than once`
+- `Message-Instance m=<x> has no supported hash algorithm` and `DKIM2-Signature i=<x> has no supported signature algorithm`
+- `Message has more than <n> Message-Instance or DKIM2-Signature header fields` (draft-ietf-dkim-dkim2-bcp-01 section 7.5)
+- `DKIM2-Signature i=<x> public key <selector> is too short`, `... is too long` and `... has an unsupported exponent`
+- `DKIM2-Signature i=<x> signature timestamp is in the future`
+
+The strings of section 11 are used as written, including their inconsistencies (`Message Instance` without the hyphen in section 11.7, `MAIL nd= does not match` in section 11.4).
+
+## Interoperability
+
+mailauth has been checked against three independent DKIM2 implementations. Where an implementation built for an earlier revision of the specification disagrees with draft-ietf-dkim-dkim2-spec-06, mailauth follows spec-06.
+
+- **[croessner/dkim2](https://github.com/croessner/dkim2)** (draft-ietf-dkim-dkim2-spec-06 and draft-ietf-dkim-dkim2-dns-00, the same drafts as mailauth). Its public verification vectors are part of the test suite (`test/fixtures/dkim2-croessner`), and its header, body and section 9.6 canonicalization, Recipe application, chain of custody, DNS record and crypto vectors give the same results. The differences are choices outside the protocol:
+    - a message with no DKIM2 header fields is `none` in mailauth (draft-gondwana-dkim2-authres-00 section 3.1, and draft-ietf-dkim-dkim2-bcp-01 section 6.1.3 says the absence alone is not a reason to reject), a PERMERROR in croessner/dkim2, which also refuses messages with bare LF line endings
+
+- **[turscar/dkim2](https://forge.turscar.ie/Turscar/dkim2)** (draft-ietf-dkim-dkim2-spec-02). The 42 vectors of [turscar/dkim2tests](https://forge.turscar.ie/turscar/dkim2tests) give the expected result, except `algorithm_only_future` (only unknown signature algorithms), which is FAIL in the vector and PERMERROR by spec-06 (see above). They also give the same section 9.6 canonical form, and the same Message-Instance hashes when mailauth signs the original messages. The vectors are part of the test suite (`test/fixtures/dkim2tests`). One vector, `flags_whitespace`, expects flags that its signed message does not have.
+- **[stalwartlabs/mail-auth](https://github.com/stalwartlabs/mail-auth)** (draft-ietf-dkim-dkim2-spec-04). Messages signed by each implementation verify with the other: originators with Ed25519, and with RSA and Ed25519 together, flags, nonce and several recipients, the null reverse-path, forwarders with and without a Recipe, and hops with `nd=`. The messages signed by mail-auth are part of the test suite (`test/fixtures/dkim2-stalwart`). The differences:
+    - mail-auth fails a message whose body was declared unrecoverable with a null body Recipe (`{"b": null}`). mailauth passes it and reports the earlier body as `unknown`, as croessner/dkim2 does, since section 5.2 makes accepting such a declaration local policy, section 9.1 allows the null Recipe, and draft-ietf-dkim-dkim2-bcp-01 sections 5.7 and 7.6 recommend it.
+    - The interop vectors in the mail-auth corpus that were made by an implementation for an earlier draft encode `mf=` and `rt=` without angle brackets, which sections 8.5 and 8.6 of spec-06 require (mail-auth rejects them too, outside its tests), and sign `Received-SPF`, which section 4 of spec-06 leaves unsigned. With those two rules relaxed, mailauth verifies all of them, including a chain of six hops with header and body Recipes.
+
+## Signing
+
+`dkim2Sign()` follows section 9:
+
+- A `Message-Instance` is added when the message has none, or when its hashes differ from the highest one. A changed message needs a `recipe`, which is applied before signing to make sure it recreates the highest instance.
+- The new signature continues the chain of custody: its signing domain has to equal the `nd=` of the previous signature, or its MAIL FROM domain (or, with `nextDomain`, its signing domain) has to match a RCPT TO of the previous signature.
+- Long tag values are folded inside base64 values, where section 2.14 allows FWS.

package/docs/dmarc.md

@@ -18,7 +18,7 @@ const { dmarc } = await authenticate(message, {
 });
 ```
 
-The author domain is the domain of the addr-spec in the From header (RFC 9989 5.3.1, RFC 5322 3.4.1). An "@" inside a quoted local-part (`"ceo@x"@bank.example`) or an obsolete source route (`<@relay.example:ceo@bank.example>`) does not change it. It is lower-cased, converted to an A-label, and a trailing dot is ignored. Several From addresses are evaluated when they all have the same domain. When there is no domain, or more than one, or a mailbox has no usable domain, or the message has more than one From header field, DMARC validation is not possible: `dmarc()` returns `false` and `authenticate()` returns `dmarc: false`, as for a message without a From address. The lower level `evaluateDmarc()` from `mailauth/lib/dmarc` also returns `reason` (`"no-author-domain"`, `"multiple-author-domains"`, `"invalid-author-domain"` or `"multiple-from-fields"`) and `authorDomains` in that case. RFC 9989 11.5 warns that such messages are often abusive, so a receiver should handle them by local policy instead of treating them as mail without DMARC.
+The author domain is the domain of the addr-spec in the From header (RFC 9989 5.3.1, RFC 5322 3.4.1). An "@" inside a quoted local-part (`"ceo@x"@bank.example`) or an obsolete source route (`<@relay.example:ceo@bank.example>`) does not change it. The From header is parsed by the RFC 5322 grammar, including the obsolete syntax of section 4, so whitespace or a comment between the atoms of the domain is removed (`ceo@bank (x).example` is `bank.example`). A From header that does not follow the grammar, for example text after the angle-addr or two addresses without a comma between them (`<bob@evil.example> alice@bank.example`), has no reliable author domain and gives `invalid-author-domain`. The default mode accepts a few common deviations and lists `"from-syntax"` in `warnings`: an unquoted comma in a display name (`Doe, John <john@example.com>`), a group without the closing `;`, a domain with a trailing dot, a domain literal in a display name, and an address used as a display name (`john@example.com <john@example.com>`, where both addresses count as author addresses). Strict mode treats these as `invalid-author-domain`. It is lower-cased, converted to an A-label, and a trailing dot is ignored. A domain with whitespace, a control character or an invisible format character (such as U+200B or the soft hyphen, but not the U+200C and U+200D joiners) is not a valid domain name and gives `invalid-author-domain`. Several From addresses are evaluated when they all have the same domain. When there is no domain, or more than one, or a mailbox has no usable domain, or the message has more than one From header field, DMARC validation is not possible: `dmarc()` returns `false` and `authenticate()` returns `dmarc: false`, as for a message without a From address. The lower level `evaluateDmarc()` from `mailauth/lib/dmarc` also returns `reason` (`"no-author-domain"`, `"multiple-author-domains"`, `"invalid-author-domain"` or `"multiple-from-fields"`) and `authorDomains` in that case. RFC 9989 11.5 warns that such messages are often abusive, so a receiver should handle them by local policy instead of treating them as mail without DMARC.
 
 ```javascript
 const { dmarc } = require('mailauth/lib/dmarc');
@@ -27,6 +27,7 @@ const result = await dmarc({
     headerFrom: 'user@example.com', // or a list of From addresses
     spfDomains: ['example.com'], // the MAIL FROM domain, if SPF passed
     dkimDomains: [{ domain: 'example.com' }], // signing domains of passing DKIM signatures
+    fromSyntax: 'valid', // optional, the From header syntax ('valid', 'lax' or 'invalid'), see above
     strict: false, // true for the RFC tag-list rules and no header.d, see below
     resolver // optional, defaults to dns.promises.resolve
 });
@@ -37,6 +38,8 @@ const result = await dmarc({
 With `strict: true`, which `authenticate(message, { strict: true })` passes on:
 
 - Records are parsed by the tag-list rules of RFC 6376 3.2 that DMARC uses (RFC 9989 4.7). Tag names are case sensitive, so `P=reject` is an unknown tag (only the version tag may be `V`, which the DMARC ABNF allows), and a record with a duplicated tag is invalid and ignored, as if it was not published. By default tag names are case-folded and the last of duplicated tags wins, and the result lists `"tag-case"` or `"duplicate-tag"` in `warnings`.
+- A record must start with the `v` tag (RFC 9989 4.10), so one with whitespace before it is discarded. The default mode uses it and lists `"record-whitespace"` in `warnings`.
+- A From header that only the lenient parsing accepts (see above) gives `invalid-author-domain` instead of the `"from-syntax"` warning.
 - `status.header.d` is not set and `header.d` is left out of the Authentication-Results entry, because it is not a registered property for `dmarc` (RFC 9989 9.1). `policyDomain` still has the domain.
 
 ## Result Object Fields