mailauth 4.12.1 → 4.13.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.12.1"
+    ".": "4.13.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [4.13.0](https://github.com/postalsys/mailauth/compare/v4.12.1...v4.13.0) (2026-02-04)
+
+
+### Features
+
+* **bimi:** add BIMI headers to VMC validation output ([77ce4e8](https://github.com/postalsys/mailauth/commit/77ce4e847d79b2acf319c3b79e865225e4c97040))
+* **dkim:** add timestamp, expiration, and validity status to output ([2267eb7](https://github.com/postalsys/mailauth/commit/2267eb77fbcaf79a6c0fb59681815628186a3ae9))
+
+
+### Bug Fixes
+
+* update Node.js requirement to >=20.18.1 ([3280a59](https://github.com/postalsys/mailauth/commit/3280a597430cf47b640b1cc31e661ab18becf145)), closes [#109](https://github.com/postalsys/mailauth/issues/109)
+
 ## [4.12.1](https://github.com/postalsys/mailauth/compare/v4.12.0...v4.12.1) (2026-02-01)
 
 

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2020-2025 Postal Systems OÜ
+Copyright (c) 2020-2026 Postal Systems OÜ
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -15,7 +15,7 @@
 - **BIMI** resolving and **VMC** validation
 - **MTA-STS** helper functions
 
-mailauth is a pure JavaScript implementation, requiring no external applications or compilation. It runs on any server or device with Node.js version 16 or later.
+mailauth is a pure JavaScript implementation, requiring no external applications or compilation. It runs on any server or device with Node.js version 20.18.1 or later.
 
 > [!NOTE]
 > mailauth is used by [EmailEngine](https://emailengine.app/) for validating email authentication settings. See the [Email Authentication Testing documentation](https://learn.emailengine.app/docs/advanced/email-authentication-testing) for details.
@@ -163,6 +163,8 @@ const signResult = await dkimSign(message, options);
     - **canonicalization** (`string`): Canonicalization method. Defaults to `'relaxed/relaxed'`.
     - **algorithm** (`string`): Signing and hashing algorithm. Defaults to `'rsa-sha256'`.
     - **signTime** (`Date`): Signing time. Defaults to current time.
+    - **expires** (`Date`): Signature expiration time (`x=` tag). Optional.
+    - **headerList** (`Array`): List of header field names to sign. Optional; uses default set if not specified.
     - **signatureData** (`Array`): Array of signature objects. Each object may contain:
         - **signingDomain** (`string`): DKIM key domain name.
         - **selector** (`string`): DKIM key selector.
@@ -250,6 +252,8 @@ const result = await dkimVerify(message);
 // Returns an object containing verification results
 ```
 
+See [DKIM Result Reference](docs/dkim.md) for details on the result object structure.
+
 ##### Example
 
 ```javascript
@@ -287,6 +291,8 @@ const result = await spf(options);
 // Returns an object containing SPF verification results
 ```
 
+See [SPF Result Reference](docs/spf.md) for details on the result object structure.
+
 ##### Parameters
 
 - **options**:
@@ -338,6 +344,8 @@ const { arc } = await authenticate(message, {
 console.log(arc);
 ```
 
+See [ARC Result Reference](docs/arc.md) for details on the result object structure.
+
 **Sample Output:**
 
 ```json
@@ -419,6 +427,8 @@ process.stdout.write(message);
 
 DMARC is verified during the authentication process. Although the `dmarc` handler is exported, it requires input from previous steps like SPF and DKIM.
 
+See [DMARC Result Reference](docs/dmarc.md) for details on the result object structure.
+
 #### DMARC Helpers
 
 ##### `getDmarcRecord(domain [, resolver])`
@@ -467,6 +477,8 @@ console.log(dmarcRecord);
 
 Brand Indicators for Message Identification (BIMI) support is based on [draft-blank-ietf-bimi-02](https://tools.ietf.org/html/draft-blank-ietf-bimi-02). BIMI information is resolved during the authentication step, provided the message passes DMARC validation with a policy other than "none".
 
+See [BIMI Result Reference](docs/bimi.md) for details on the result object structure.
+
 #### Example
 
 ```javascript
@@ -518,6 +530,8 @@ const { policy, status } = await getPolicy(domain [, knownPolicy]);
 // Returns an object with the policy and status
 ```
 
+See [MTA-STS Result Reference](docs/mta-sts.md) for details on the result object structure.
+
 ##### Parameters
 
 - **domain** (`string`): The domain to retrieve the policy for.
@@ -604,6 +618,6 @@ Based on ValiMail's [arc_test_suite](https://github.com/ValiMail/arc_test_suite)
 
 ## License
 
-© 2020-2024 Postal Systems OÜ
+© 2020-2026 Postal Systems OÜ
 
 Licensed under the [MIT License](LICENSE).

package/cli.md

@@ -268,6 +268,7 @@ mailauth vmc [options]
 - `--authority <url>`, `-a <url>`: URL of the VMC resource.
 - `--authorityPath <path>`, `-p <path>`: Path to a local VMC file, used to avoid network requests.
 - `--domain <domain>`, `-d <domain>`: Sender domain to validate against the certificate.
+- `--date <timestamp>`, `-t <timestamp>`: ISO-formatted timestamp for certificate expiration checks. Defaults to the current time.
 
 #### Example
 
@@ -421,6 +422,6 @@ When this option is used, mailauth will not perform actual DNS queries but will
 
 ## License
 
-&copy; 2020-2024 Postal Systems OÜ
+&copy; 2020-2026 Postal Systems OÜ
 
 Licensed under the [MIT License](LICENSE).

package/docs/arc.md

@@ -0,0 +1,176 @@
+# ARC Validation Result Reference
+
+This document describes the result object returned by ARC (Authenticated Received Chain) validation and sealing.
+
+## Overview
+
+ARC validation is performed automatically during the authentication step. ARC allows intermediate mail handlers to sign messages, preserving authentication results across forwarding.
+
+```javascript
+const { authenticate } = require('mailauth');
+
+const { arc } = await authenticate(message, {
+    trustReceived: true
+});
+```
+
+## Validation Result Object Fields
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `status` | `object` | Always | Validation status object (see below) |
+| `chain` | `array` | Non-enumerable | Array of ARC chain entries (hidden from JSON serialization) |
+| `i` | `number\|false` | Always | Last instance number in chain, or `false` if no chain |
+| `signature` | `object` | Chain exists | Verification result for last ARC-Message-Signature |
+| `authenticationResults` | `object` | Chain exists | Parsed last ARC-Authentication-Results |
+| `info` | `string` | Result not "none" | Formatted Authentication-Results header value |
+
+## 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"}`) |
+
+## authenticationResults Object
+
+When ARC validation passes, the `authenticationResults` object contains parsed results from the last ARC-Authentication-Results header:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mta` | `string` | Hostname of the MTA that added this ARC set |
+| `arc` | `object` | ARC result (`{result: "pass\|fail\|none", ...}`) |
+| `spf` | `object` | SPF result (`{result: "pass\|fail\|...", ...}`) |
+| `dmarc` | `object` | DMARC result (`{result: "pass\|fail\|none", header: {...}}`) |
+| `dkim` | `array` | Array of DKIM results |
+
+## Result Values
+
+| Result | Description |
+|--------|-------------|
+| `none` | No ARC chain present in message |
+| `pass` | ARC chain validated successfully |
+| `fail` | ARC chain validation failed |
+
+## 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` |
+| `"i={n} invalid as c"` | Invalid canonicalization for ARC-Seal |
+| `"i={n} invalid ams h"` | ARC-Message-Signature signed arc-seal (forbidden) |
+| `"no key for {domain}"` | DNS key not found |
+| `"unknown key version for {domain}"` | Unsupported key version |
+| `"unknown key type for {domain}"` | Unsupported key type |
+| `"invalid public key for {domain}"` | Malformed public key |
+| `"weak key for {domain}"` | RSA key too short |
+
+## Seal Result Object
+
+When sealing a message with `sealMessage()`, the result contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `headers` | `string[]` | Array of ARC headers to prepend: `[ARC-Seal, ARC-Message-Signature, ARC-Authentication-Results]` |
+
+## Example Output
+
+### ARC Pass
+
+```json
+{
+  "status": {
+    "result": "pass",
+    "comment": "i=2 spf=pass dkim=pass dkdomain=example.com dmarc=pass fromdomain=example.com"
+  },
+  "i": 2,
+  "signature": {
+    "id": "abc123...",
+    "signingDomain": "forwarder.example.net",
+    "selector": "arc",
+    "status": {
+      "result": "pass"
+    }
+  },
+  "authenticationResults": {
+    "mta": "mx.forwarder.example.net",
+    "spf": {
+      "result": "pass",
+      "smtp": {
+        "mailfrom": "user@example.com"
+      }
+    },
+    "dkim": [
+      {
+        "result": "pass",
+        "header": {
+          "i": "@example.com",
+          "s": "selector1"
+        }
+      }
+    ],
+    "dmarc": {
+      "result": "pass",
+      "header": {
+        "from": "example.com"
+      }
+    }
+  },
+  "info": "arc=pass (i=2 spf=pass dkim=pass dkdomain=example.com dmarc=pass fromdomain=example.com)"
+}
+```
+
+### ARC Fail
+
+```json
+{
+  "status": {
+    "result": "fail",
+    "comment": "i=2 seal signature validation failed",
+    "shouldSeal": true
+  },
+  "i": 2,
+  "info": "arc=fail (i=2 seal signature validation failed)"
+}
+```
+
+### ARC None
+
+```json
+{
+  "status": {
+    "result": "none"
+  },
+  "i": 0
+}
+```
+
+### Seal Headers Output
+
+When using `sealMessage()`:
+
+```javascript
+const { sealMessage } = require('mailauth');
+
+const sealHeaders = await sealMessage(message, {
+    signingDomain: 'example.com',
+    selector: 'arc',
+    privateKey: privateKey,
+    authResults: 'mx.example.com; spf=pass; dkim=pass',
+    cv: 'pass'
+});
+
+// sealHeaders is a Buffer containing:
+// ARC-Seal: i=1; a=rsa-sha256; cv=pass; d=example.com; s=arc; ...
+// ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=example.com; ...
+// ARC-Authentication-Results: i=1; mx.example.com; spf=pass; dkim=pass
+```

package/docs/bimi.md

@@ -0,0 +1,272 @@
+# BIMI Result Reference
+
+This document describes the result object returned by BIMI (Brand Indicators for Message Identification) resolution.
+
+## Overview
+
+BIMI allows organizations to display brand logos in email clients. BIMI information is resolved during the authentication step, provided the message passes DMARC validation with a policy other than "none".
+
+```javascript
+const { authenticate } = require('mailauth');
+
+const { bimi } = await authenticate(message, {
+    ip: '192.0.2.1',
+    helo: 'mail.example.com',
+    sender: 'user@example.com'
+});
+```
+
+## 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 |
+
+## status Object
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `result` | `string` | Always | BIMI result code (see below) |
+| `comment` | `string` | On skip/fail | Reason for skip or failure |
+| `header` | `object` | Always | Header information |
+| `policy` | `object` | VMC found | Authority policy details |
+
+### status.header Object
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `selector` | `string` | Record found | BIMI selector used (e.g., `"default"`) |
+| `d` | `string` | Record found | Domain where BIMI record was found |
+
+### status.policy Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `authority` | `string` | VMC validation status (`"none"` before validation) |
+| `authority-uri` | `string` | URL of the authority evidence document |
+
+## Result Values
+
+| Result | Description |
+|--------|-------------|
+| `pass` | BIMI record found and valid |
+| `skipped` | BIMI lookup skipped (see skip reasons below) |
+| `fail` | BIMI record found but invalid |
+| `none` | No BIMI record found |
+| `temperr` | Temporary error during DNS lookup |
+
+## Skip Reasons
+
+The `status.comment` field explains why BIMI was skipped:
+
+| Comment | Description |
+|---------|-------------|
+| `"DMARC not enabled"` | DMARC result was `none` |
+| `"message failed DMARC"` | DMARC result was not `pass` |
+| `"too lax DMARC policy"` | DMARC policy is `none` or `quarantine` with `pct < 100` |
+| `"Aligned DKIM signature required"` | `bimiWithAlignedDkim` option set but no aligned DKIM |
+| `"undersized DKIM signature"` | DKIM signature has unsigned body bytes (due to `l=` tag) |
+| `"could not determine domain"` | Unable to extract domain from headers |
+
+## 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 neither `l=` nor `a=` tag |
+| `"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 |
+| `"failed to resolve {domain}"` | DNS lookup error |
+| `"invalid BIMI response for {domain}"` | DNS response format invalid |
+
+## VMC Validation Result
+
+When using `validateVMC()` to validate the authority evidence document:
+
+```javascript
+const { bimi, validateVMC } = require('mailauth/lib/bimi');
+
+const bimiResult = await bimi(data);
+const vmcResult = await validateVMC(bimiResult, options);
+```
+
+### 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) |
+
+### 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 |
+
+### authority Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | VMC/CMC URL |
+| `success` | `boolean` | Whether fetch and validation succeeded |
+| `vmc` | `object` | Parsed VMC data (on success) |
+| `domainVerified` | `boolean` | Whether domain matches certificate |
+| `hashMatch` | `boolean` | Whether logo hash matches certificate |
+| `error` | `object` | Error details (on failure) |
+
+### headers Object
+
+Present only when VMC validation succeeds. 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 |
+
+These headers should be added to messages after successful BIMI validation. The MTA should:
+1. Remove any existing BIMI-* headers from incoming messages
+2. Add these headers after successful validation
+
+### 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 |
+
+## Example Output
+
+### BIMI Pass
+
+```json
+{
+  "status": {
+    "result": "pass",
+    "header": {
+      "selector": "default",
+      "d": "example.com"
+    },
+    "policy": {
+      "authority": "none",
+      "authority-uri": "https://example.com/bimi/vmc.pem"
+    }
+  },
+  "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",
+  "info": "bimi=pass header.selector=default header.d=example.com policy.authority=none policy.authority-uri=https://example.com/bimi/vmc.pem"
+}
+```
+
+### BIMI Skipped (DMARC Failed)
+
+```json
+{
+  "status": {
+    "result": "skipped",
+    "comment": "message failed DMARC",
+    "header": {}
+  },
+  "info": "bimi=skipped (message failed DMARC)"
+}
+```
+
+### BIMI Skipped (Policy Too Lax)
+
+```json
+{
+  "status": {
+    "result": "skipped",
+    "comment": "too lax DMARC policy",
+    "header": {}
+  },
+  "info": "bimi=skipped (too lax DMARC policy)"
+}
+```
+
+### BIMI None (No Record)
+
+```json
+{
+  "status": {
+    "result": "none",
+    "header": {
+      "selector": "default",
+      "d": "example.com"
+    }
+  },
+  "info": "bimi=none header.selector=default header.d=example.com"
+}
+```
+
+### BIMI Fail (Invalid Record)
+
+```json
+{
+  "status": {
+    "result": "fail",
+    "comment": "missing location value in dns record",
+    "header": {
+      "selector": "default",
+      "d": "example.com"
+    }
+  },
+  "rr": "v=BIMI1;",
+  "info": "bimi=fail (missing location value in dns record) header.selector=default header.d=example.com"
+}
+```
+
+### VMC Validation Result
+
+```json
+{
+  "location": {
+    "url": "https://example.com/bimi/logo.svg",
+    "success": true,
+    "logoFile": "PHN2ZyB4bWxucz0i...",
+    "hashAlgo": "sha256",
+    "hashValue": "abc123..."
+  },
+  "authority": {
+    "url": "https://example.com/bimi/vmc.pem",
+    "success": true,
+    "domainVerified": true,
+    "hashMatch": true,
+    "vmc": {
+      "type": "VMC",
+      "mediaType": "image/svg+xml",
+      "logoFile": "PHN2ZyB4bWxucz0i...",
+      "hashAlgo": "sha256",
+      "hashValue": "abc123...",
+      "validHash": true,
+      "certificate": {
+        "subjectAltName": ["example.com", "*.example.com"]
+      }
+    }
+  },
+  "headers": {
+    "indicator": "BIMI-Indicator: PHN2ZyB4bWxucz0i...",
+    "location": "BIMI-Location: v=BIMI1; l=https://example.com/bimi/logo.svg",
+    "preference": "BIMI-Logo-Preference: self"
+  }
+}
+```