mailauth 7.1.1 → 7.3.0

package/cli.md

@@ -14,6 +14,9 @@ mailauth provides a command-line utility for email authentication, complementing
 - [Available Commands](#available-commands)
     - [`report`](#report) — Validate SPF, DKIM, DMARC, ARC, and BIMI
     - [`sign`](#sign) — Sign an email with DKIM
+    - [`dkim2-sign`](#dkim2-sign) — Sign an email with DKIM2 (experimental)
+    - [`dkim2-verify`](#dkim2-verify) — Verify the DKIM2 signatures of an email (experimental)
+    - [`dkim2-hash`](#dkim2-hash) — Generate the DKIM2 header and body hashes for an email
     - [`seal`](#seal) — Seal an email with ARC
     - [`spf`](#spf) — Validate SPF for an IP address and email address
     - [`vmc`](#vmc) — Validate BIMI VMC logo files
@@ -56,13 +59,19 @@ mailauth spf --help
 
 The mailauth CLI offers several commands to perform different email authentication tasks:
 
-1. [`report`](#report) — Validate SPF, DKIM, DMARC, ARC, and BIMI.
+1. [`report`](#report) — Validate SPF, DKIM, DMARC, ARC, and BIMI, and optionally DKIM2.
 2. [`sign`](#sign) — Sign an email with DKIM.
-3. [`seal`](#seal) — Seal an email with ARC.
-4. [`spf`](#spf) — Validate SPF for an IP address and email address.
-5. [`vmc`](#vmc) — Validate BIMI VMC logo files.
-6. [`bodyhash`](#bodyhash) — Generate the body hash value for an email.
-7. [`license`](#license) — Display licenses for mailauth and included modules.
+3. [`dkim2-sign`](#dkim2-sign) — Sign an email with DKIM2 (experimental).
+4. [`dkim2-verify`](#dkim2-verify) — Verify the DKIM2 signatures of an email (experimental).
+5. [`dkim2-hash`](#dkim2-hash) — Generate the DKIM2 header and body hashes for an email.
+6. [`seal`](#seal) — Seal an email with ARC.
+7. [`spf`](#spf) — Validate SPF for an IP address and email address.
+8. [`vmc`](#vmc) — Validate BIMI VMC logo files.
+9. [`bodyhash`](#bodyhash) — Generate the body hash value for an email.
+10. [`license`](#license) — Display licenses for mailauth and included modules.
+
+> [!WARNING]
+> DKIM2 is not a published RFC yet. The DKIM2 commands are experimental and built against draft-ietf-dkim-dkim2-spec-06, draft-ietf-dkim-dkim2-dns-00 and draft-ietf-dkim-dkim2-bcp-01, see [DKIM2](README.md#dkim2).
 
 ### report
 
@@ -88,6 +97,8 @@ mailauth report [options] [email]
 - `--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.
+- `--dkim2`: Verifies DKIM2 header fields as well. The result is in the `dkim2` key of the report and a `dkim2=` entry is added to Authentication-Results. DKIM2 does not take part in DMARC.
+- `--rcpt-to user@example.com`, `-r user@example.com`: RCPT TO address of the delivery, checked against the highest DKIM2-Signature together with `--sender`. Can be repeated. Without it the DKIM2 result has the `rcpt-to-not-checked` warning.
 
 #### Example
 
@@ -156,6 +167,137 @@ DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com;
  ...
 ```
 
+### dkim2-sign
+
+The `dkim2-sign` command signs an email message with DKIM2. It adds a `DKIM2-Signature` header field, and a `Message-Instance` header field when the message has none yet or has changed since its last instance. Use it as the originator of a message, or as a forwarder that adds its own hop to a message that is already DKIM2 signed.
+
+#### Usage
+
+```bash
+mailauth dkim2-sign [options] [email]
+```
+
+- **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
+
+#### Options
+
+- `--private-key /path/to/private.key`, `-k /path/to/private.key`: Path to a private key, RSA (at least 1024 bits) or Ed25519. Repeat it to sign with several keys, each with its own `--selector`.
+- `--selector selector`, `-s selector`: Selector of the private key in the same position. Can be repeated. At most two keys can use the same algorithm.
+- `--domain example.com`, `-d example.com`: Signing domain (`d=` tag). It has to be the MAIL FROM domain or a parent of it.
+- `--mail-from user@example.com`, `-f user@example.com`: MAIL FROM address the message is sent with (`mf=` tag), `<>` for the null sender.
+- `--rcpt-to user@example.net`, `-r user@example.net`: RCPT TO address the message is sent to (`rt=` tag). Can be repeated.
+- `--next-domain example.net`: For a hop across a trust boundary, the domain of the next DKIM2 signature (`nd=` tag). Used instead of `--mail-from` and `--rcpt-to`.
+- `--flag flag`: Flag to set (`f=` tag): `donotmodify`, `donotexplode`, `exploded`, `feedback` or `feedhere`. Can be repeated.
+- `--nonce value`: A value for your own use (`n=` tag), at most 64 characters.
+- `--hash algorithm`: Hash algorithm of a new `Message-Instance`, `sha256` or `sha512`. Can be repeated. Defaults to `sha256`.
+- `--recipe /path/to/recipe.json`: For a forwarder that changed the message, a JSON file with the Recipe that recreates the previous instance (`r=` tag). It is checked before signing, and the command fails if it does not recreate the previous instance.
+- `--time timestamp`, `-t timestamp`: Signing time as a Unix timestamp (`t=` tag). Defaults to the current time.
+- `--headers-only`, `-o`: Outputs only the DKIM2 header fields without the message.
+
+Either `--mail-from` and `--rcpt-to`, or `--next-domain`, is required.
+
+#### Example
+
+```bash
+mailauth dkim2-sign /path/to/message.eml \
+    -k /path/to/rsa.key -s rsa2026 -k /path/to/ed25519.key -s ed2026 \
+    -d example.com -f bounces@example.com -r user@example.net
+```
+
+**Sample Output:**
+
+```
+DKIM2-Signature: i=1; m=1; t=1791646747; d=example.com; mf=
+ PGJvdW5jZXNAZXhhbXBsZS5jb20+; rt=PHVzZXJAZXhhbXBsZS5uZXQ+; s=rsa2026:rsa-sha256:
+ MXp6X81Tuu/cwbedt/kFqdO1sE4yPkfYVnFzfBMO2ZjfAtoXuptS+G79SYEpEaAo
+ ...
+Message-Instance: m=1; h=sha256:
+ sbKYVMaA7tqVLzGg5HTTU3o95q7ufdnBincKg/jBBQc=:
+ GjyEkbey2OupCW5AKJv4dzTPsPHSaZjRDMqUSmhpTyQ=;
+From: ...
+```
+
+A mailing list that replaced the `Subject` header field, added a `List-Id` header field and appended a footer after the first 3 body lines signs its revision with a Recipe:
+
+```json
+{ "h": { "subject": [{ "d": ["Original subject"] }], "list-id": [] }, "b": [{ "c": [1, 3] }] }
+```
+
+```bash
+mailauth dkim2-sign revised.eml -k list.key -s list -d list.example.org \
+    -f bounce@list.example.org -r member@example.net --recipe recipe.json
+```
+
+### dkim2-verify
+
+The `dkim2-verify` command verifies only the DKIM2 header fields of an email message and returns a JSON report. See [DKIM2 Result Reference](docs/dkim2.md) for the structure. Use `report --dkim2` to check DKIM2 together with everything else.
+
+#### Usage
+
+```bash
+mailauth dkim2-verify [options] [email]
+```
+
+- **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
+
+#### Options
+
+- `--mail-from user@example.com`, `-f user@example.com`: MAIL FROM address the message was delivered with, `<>` for the null sender. Checked against the highest DKIM2-Signature.
+- `--rcpt-to user@example.net`, `-r user@example.net`: RCPT TO address the message was delivered to, checked against the highest DKIM2-Signature. Can be repeated.
+- `--dns-cache /path/to/dns.json`, `-n /path/to/dns.json`: Path to a DNS cache file. When provided, DNS queries use cached responses.
+- `--time timestamp`, `-t timestamp`: Time to verify against as a Unix timestamp. Defaults to the current time.
+- `--max-age seconds`: Seconds after which a signature expires, `0` to not check. Defaults to 14 days.
+- `--max-future seconds`: Seconds a signature timestamp may be ahead of the current time, `0` to not check. Defaults to `300`.
+- `--max-instances number`: The most `Message-Instance`, and the most `DKIM2-Signature`, header fields to process. Defaults to `20`.
+- `--headers-only`, `-o`: Outputs only the Authentication-Results entry (`dkim2=...`) instead of the JSON report.
+- `--verbose`, `-v`: Shows the DNS queries, and the parts of the envelope that were not checked.
+
+The chain of custody against the delivery, which is what stops DKIM2 replay, is only checked for the parts of the envelope given with `--mail-from` and `--rcpt-to`. A missing part is reported in `status.warnings`.
+
+#### Example
+
+```bash
+mailauth dkim2-verify -f bounces@example.com -r user@example.net -o /path/to/message.eml
+```
+
+**Sample Output:**
+
+```
+dkim2=pass (i=1 example.com pass) header.d=example.com
+```
+
+### dkim2-hash
+
+The `dkim2-hash` command computes the DKIM2 header and body hashes of an email message, in the `algorithm:header-hash:body-hash` form of the `h=` tag of a `Message-Instance` header field. Use it to check what a `Message-Instance` should contain, for example when writing a Recipe.
+
+#### Usage
+
+```bash
+mailauth dkim2-hash [options] [email]
+```
+
+- **email**: (Optional) Path to the EML-formatted email message file. If omitted, the email is read from standard input.
+
+#### Options
+
+- `--algo algorithm`, `-a algorithm`: Hash algorithm, `sha256` or `sha512`. Can be repeated. Defaults to `sha256`.
+- `--verbose`, `-v`: Also lists the header fields that go into the header hash. DKIM2 does not sign trace header fields, `X-` header fields, DKIM1, ARC and Authentication-Results header fields, or its own header fields.
+
+#### Example
+
+```bash
+mailauth dkim2-hash -v /path/to/message.eml
+```
+
+**Sample Output:**
+
+```
+Reading email message from /path/to/message.eml
+Hashed header fields: content-type, date, from, message-id, mime-version, subject, to
+--------
+sha256:sbKYVMaA7tqVLzGg5HTTU3o95q7ufdnBincKg/jBBQc=:GjyEkbey2OupCW5AKJv4dzTPsPHSaZjRDMqUSmhpTyQ=
+```
+
 ### seal
 
 The `seal` command adds an ARC (Authenticated Received Chain) seal to an email message.
@@ -185,7 +327,7 @@ mailauth seal [options] [email]
 
 By default, `seal` authenticates the message (SPF, DKIM, DMARC, ARC) and embeds the computed results in the `ARC-Authentication-Results` header. If the message was already authenticated elsewhere (for example at an edge MTA) and modified afterwards, you can instead provide the original `Authentication-Results` value yourself. When one of the following options is set, no authentication checks or DNS lookups are performed:
 
-- `--auth-results "authserv-id; spf=pass ..."`: `Authentication-Results` value to embed in the `ARC-Authentication-Results` header (the part after `i=N;`). Used as is.
+- `--auth-results "authserv-id; spf=pass ..."`: `Authentication-Results` value to embed in the `ARC-Authentication-Results` header (the part after `i=N;`). Used as is, except that line breaks are written as CRLF. A multi-line value must be folded: every line after the first starts with a space or a tab. A value with any other line break is refused, as it would start a new header field.
 - `--auth-results-file /path/to/value.txt`: Same as `--auth-results`, but the value is read from a file. Useful for long or multi-line values. Cannot be combined with `--auth-results`.
 - `--cv status`: Chain validation status for the `ARC-Seal` header (`cv=` tag): `none`, `pass`, or `fail`. Defaults to `none`.
 - `--instance number`: ARC instance number (`i=` tag). Defaults to the next instance number based on the existing ARC chain of the message, or `1`.
@@ -413,7 +555,7 @@ The `--dns-cache` option allows you to use a JSON-formatted DNS cache file for t
 
 The DNS cache file is a JSON object where:
 
-- **Keys**: Fully qualified domain names (e.g., `"example.com"`).
+- **Keys**: Fully qualified domain names (e.g., `"example.com"`). DKIM and DKIM2 keys are looked up as `selector._domainkey.domain`.
 - **Values**: Objects with DNS record types as keys (e.g., `"TXT"`, `"MX"`) and their corresponding values.
 
 **Example:**

package/docs/arc.md

@@ -31,13 +31,13 @@ With `strict: true` the validation and sealing follow RFC 8617 exactly, see [Str
 
 ## status Object
 
-| Field        | Type      | Presence     | Description                                                      |
-| ------------ | --------- | ------------ | ---------------------------------------------------------------- |
-| `result`     | `string`  | Always       | ARC result code (see below)                                      |
-| `comment`    | `string`  | On pass/fail | Description or error message                                     |
-| `shouldSeal` | `boolean` | On fail      | Whether to continue sealing despite failure                      |
-| `policy`     | `object`  | Policy issue | Policy violation details (e.g., `{"dkim-rules": "weak-key"}`)    |
-| `smtp`       | `object`  | Strict mode  | `{"remote-ip": "192.0.2.1"}`, the client IP (RFC 8617 section 6) |
+| Field        | Type      | Presence     | Description                                                                                              |
+| ------------ | --------- | ------------ | -------------------------------------------------------------------------------------------------------- |
+| `result`     | `string`  | Always       | ARC result code (see below)                                                                              |
+| `comment`    | `string`  | On pass/fail | Description or error message                                                                             |
+| `shouldSeal` | `boolean` | On fail      | Whether the failed chain is sealed with `cv=fail`, false when its newest ARC-Seal already says `cv=fail` |
+| `policy`     | `object`  | Policy issue | Policy violation details (e.g., `{"dkim-rules": "weak-key"}`)                                            |
+| `smtp`       | `object`  | Strict mode  | `{"remote-ip": "192.0.2.1"}`, the client IP (RFC 8617 section 6)                                         |
 
 ## authenticationResults Object
 
@@ -61,28 +61,29 @@ When ARC validation passes, the `authenticationResults` object contains parsed r
 
 ## Comment Values (on failure)
 
-| Comment Pattern                                                             | Description                                                                                                          |
-| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `"i={n} seal signature validation failed"`                                  | ARC-Seal cryptographic verification failed                                                                           |
-| `"i={n} no valid signature"`                                                | ARC-Message-Signature verification failed                                                                            |
-| `"i={n} multiple {header} values"`                                          | Duplicate ARC headers for same instance                                                                              |
-| `"chain-length={n}"`                                                        | Chain exceeds 50 instances                                                                                           |
-| `"i={n} expected={m}"`                                                      | Missing or out-of-order instance numbers                                                                             |
-| `"i={n} no {header} set"`                                                   | Missing required ARC header                                                                                          |
-| `"i=1 cv={value}"`                                                          | First instance must have `cv=none`                                                                                   |
-| `"i={n} cv={value}"`                                                        | Non-first instance must have `cv=pass`, and a newest seal with `cv=fail` fails the chain                             |
-| `"i={n} unexpected as h"`                                                   | ARC-Seal has an `h=` tag                                                                                             |
-| `"i={n} invalid ams h"`                                                     | ARC-Message-Signature signed arc-seal (forbidden)                                                                    |
-| `"i={n} as {problem}"`, `"i={n} ams {problem}"`                             | Strict mode: a tag-list syntax error, a missing required tag or a malformed `t=`/`x=`/`l=`                           |
-| `"invalid as instance"`, `"invalid ams instance"`, `"invalid aar instance"` | Strict mode: an ARC header field whose `i=` is not 1 to 50 written as 1*2DIGIT (first in ARC-Authentication-Results) |
-| `"no key for {domain}"`                                                     | DNS key not found                                                                                                    |
-| `"unknown key version for {domain}"`                                        | Key record `v=` is not `DKIM1`                                                                                       |
-| `"unknown key type for {domain}"`                                           | Unsupported key type                                                                                                 |
-| `"invalid public key for {domain}"`                                         | Malformed public key                                                                                                 |
-| `"inappropriate hash algorithm for {domain}"`                               | Key record `h=` does not list sha256                                                                                 |
-| `"key not for email for {domain}"`                                          | Key record `s=` does not list email                                                                                  |
-| `"inappropriate key algorithm for {domain}"`                                | The key type does not match the seal's `a=` algorithm                                                                |
-| `"weak key for {domain}"`                                                   | RSA key too short                                                                                                    |
+| Comment Pattern                                                             | Description                                                                                                            |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `"i={n} seal signature validation failed"`                                  | ARC-Seal cryptographic verification failed                                                                             |
+| `"i={n} no valid signature"`                                                | ARC-Message-Signature verification failed                                                                              |
+| `"i={n} multiple {header} values"`                                          | Duplicate ARC headers for same instance                                                                                |
+| `"chain-length={n}"`                                                        | Chain exceeds 50 instances                                                                                             |
+| `"i={n} expected={m}"`                                                      | Missing or out-of-order instance numbers                                                                               |
+| `"i={n} no {header} set"`                                                   | Missing required ARC header                                                                                            |
+| `"i=1 cv={value}"`                                                          | First instance must have `cv=none`                                                                                     |
+| `"i={n} cv={value}"`                                                        | Non-first instance must have `cv=pass`, and a newest seal with `cv=fail` fails the chain                               |
+| `"i={n} unexpected as h"`                                                   | ARC-Seal has an `h=` tag                                                                                               |
+| `"i={n} invalid ams h"`                                                     | ARC-Message-Signature signed arc-seal (forbidden)                                                                      |
+| `"i={n} as {problem}"`, `"i={n} ams {problem}"`                             | Strict mode: a tag-list syntax error, a missing required tag or a malformed `t=`/`x=`/`l=`                             |
+| `"i={n} as invalid d="`, `"i={n} ams invalid d="`                           | Both modes: an ARC-Seal or the newest ARC-Message-Signature has a `d=` with a character that can not be in a host name |
+| `"invalid as instance"`, `"invalid ams instance"`, `"invalid aar instance"` | Strict mode: an ARC header field whose `i=` is not 1 to 50 written as 1*2DIGIT (first in ARC-Authentication-Results)   |
+| `"no key for {domain}"`                                                     | DNS key not found                                                                                                      |
+| `"unknown key version for {domain}"`                                        | Key record `v=` is not `DKIM1`                                                                                         |
+| `"unknown key type for {domain}"`                                           | Unsupported key type                                                                                                   |
+| `"invalid public key for {domain}"`                                         | Malformed public key                                                                                                   |
+| `"inappropriate hash algorithm for {domain}"`                               | Key record `h=` does not list sha256                                                                                   |
+| `"key not for email for {domain}"`                                          | Key record `s=` does not list email                                                                                    |
+| `"inappropriate key algorithm for {domain}"`                                | The key type does not match the seal's `a=` algorithm                                                                  |
+| `"weak key for {domain}"`                                                   | RSA key too short                                                                                                      |
 
 An ARC-Message-Signature that does not sign the From header field is not valid (RFC 6376 section 6.1.1), which fails the chain with `"i={n} no valid signature"` in both modes. An ARC-Seal `c=` tag is not defined by RFC 8617, so it is ignored like any other unknown tag.
 
@@ -94,6 +95,7 @@ These rules apply in both modes:
 - An Ed25519 seal signs the SHA-256 hash of the canonicalized data (RFC 8463).
 - The seal's `a=` algorithm has to match the key type, and the key record's `v=`, `h=` and `s=` tags are honored.
 - An ARC-Message-Signature without `c=` uses `simple/simple`, the DKIM-Signature default.
+- A `d=` with a character that can not be in a host name (such as `/`, `?`, `#`, `@` or `:`) in any ARC-Seal or in the newest ARC-Message-Signature fails the chain, and its key is not looked up.
 
 Differences between the modes:
 
@@ -115,12 +117,12 @@ The position of `i=` in an ARC-Seal or ARC-Message-Signature is not checked in e
 
 In the default mode `warnings` lists what was accepted although strict mode would have rejected it. It is only present when there is something to report and the chain did not fail, and it is never written into the Authentication-Results text.
 
-| Warning                                           | Meaning                                                                                               |
-| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `arc-tag-syntax`                                  | An ARC-Seal or the newest ARC-Message-Signature has a tag-list syntax error or an upper case tag name |
-| `arc-instance-syntax`                             | An `i=` value is not valid RFC 8617 syntax, or an ARC header field was ignored because of its `i=`    |
-| `ams-c-default`                                   | The ARC-Message-Signature has no `c=` and only verified with `relaxed/relaxed`                        |
-| `key-syntax`, `key-v-syntax`, `key-type-inferred` | Key record leniencies, see the [DKIM result reference](dkim.md#warnings)                              |
+| Warning                                                               | Meaning                                                                                               |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `arc-tag-syntax`                                                      | An ARC-Seal or the newest ARC-Message-Signature has a tag-list syntax error or an upper case tag name |
+| `arc-instance-syntax`                                                 | An `i=` value is not valid RFC 8617 syntax, or an ARC header field was ignored because of its `i=`    |
+| `ams-c-default`                                                       | The ARC-Message-Signature has no `c=` and only verified with `relaxed/relaxed`                        |
+| `key-syntax`, `key-v-syntax`, `key-type-inferred`, `key-ed25519-spki` | Key record leniencies, see the [DKIM result reference](dkim.md#warnings)                              |
 
 ## Sealing
 
@@ -131,31 +133,37 @@ In the default mode `warnings` lists what was accepted although strict mode woul
 | `headers`  | `string[]` | ARC headers to prepend: `[ARC-Seal, ARC-Message-Signature, ARC-Authentication-Results]`, or empty |
 | `errors`   | `array`    | `{ err, type, selector, signingDomain }` entries saying why no set was created                    |
 | `warnings` | `string[]` | What the default mode sealed that strict mode would have refused                                  |
+| `instance` | `number`   | The instance (`i=`) of the created set, not set when no set was created                           |
 
 Seal options:
 
-| Option          | Type               | Description                                                                                                |
-| --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `signingDomain` | `string`           | `d=` value                                                                                                 |
-| `selector`      | `string`           | `s=` value                                                                                                 |
-| `privateKey`    | `string\|Buffer`   | RSA or Ed25519 private key                                                                                 |
-| `algorithm`     | `string`           | `rsa-sha256` or `ed25519-sha256`, follows the key type when not set                                        |
-| `authResults`   | `string`           | The Authentication-Results payload for the ARC-Authentication-Results header                               |
-| `cv`            | `string`           | `none`, `pass` or `fail`. Defaults to `none` for the first set, required for later ones                    |
-| `i`             | `number`           | Instance, defaults to one more than the highest instance on the message                                    |
-| `headerList`    | `string\|string[]` | Header fields for the ARC-Message-Signature. ARC header fields and Authentication-Results are never signed |
-| `signTime`      | `Date`             | Signing time                                                                                               |
-| `strict`        | `boolean`          | Follow the RFCs exactly                                                                                    |
+| Option          | Type               | Description                                                                                                               |
+| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `signingDomain` | `string`           | `d=` value                                                                                                                |
+| `selector`      | `string`           | `s=` value                                                                                                                |
+| `privateKey`    | `string\|Buffer`   | RSA or Ed25519 private key                                                                                                |
+| `algorithm`     | `string`           | `rsa-sha256` or `ed25519-sha256`, follows the key type when not set                                                       |
+| `authResults`   | `string`           | The Authentication-Results payload for the ARC-Authentication-Results header (required). Line breaks only as CRLF folding |
+| `cv`            | `string`           | `none`, `pass` or `fail`. Defaults to `none` for the first set, required for later ones                                   |
+| `i`             | `number`           | Instance, defaults to one more than the highest instance on the message                                                   |
+| `headerList`    | `string\|string[]` | Header fields for the ARC-Message-Signature. ARC header fields and Authentication-Results are never signed                |
+| `signTime`      | `Date`             | Signing time                                                                                                              |
+| `strict`        | `boolean`          | Follow the RFCs exactly                                                                                                   |
+
+`authenticate()` always computes `authResults`, `cv` and `i` for the message it seals and ignores these values in its `seal` option. The seal options object is never modified, so one object can be shared by concurrent calls.
+
+A name repeated in `headerList` is over-signed in the ARC-Message-Signature, as with `dkimSign`.
 
 No ARC set is created (in either mode) when:
 
-| Error code         | Reason                                                                                                                                    |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `EARCCHAINFAILED`  | The newest ARC-Seal on the message already has `cv=fail` (RFC 8617 section 5.1 step 2)                                                    |
-| `EINVALIDINSTANCE` | The instance is not 1 to 50, already exists on the message, or the chain already has 50 sets                                              |
-| `EINVALIDCV`       | `cv` is not `none`, `pass` or `fail`, is missing for an instance above 1, or is `pass` while the chain on the message could not be parsed |
-| `EINVALIDALGO`     | The algorithm is not `rsa-sha256` or `ed25519-sha256`                                                                                     |
-| `EINVALIDTYPE`     | The algorithm does not match the key type                                                                                                 |
+| Error code            | Reason                                                                                                                                    |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `EARCCHAINFAILED`     | The newest ARC-Seal on the message already has `cv=fail` (RFC 8617 section 5.1 step 2)                                                    |
+| `EINVALIDINSTANCE`    | The instance is not 1 to 50, already exists on the message, or the chain already has 50 sets                                              |
+| `EINVALIDCV`          | `cv` is not `none`, `pass` or `fail`, is missing for an instance above 1, or is `pass` while the chain on the message could not be parsed |
+| `EINVALIDALGO`        | The algorithm is not `rsa-sha256` or `ed25519-sha256`                                                                                     |
+| `EINVALIDAUTHRESULTS` | `authResults` is missing or empty, or has a line break that is not folding (CRLF followed by a space or tab and more text)                |
+| `EINVALIDTYPE`        | The algorithm does not match the key type                                                                                                 |
 
 What only strict mode refuses (the default mode seals and adds the warning):