mailauth 4.12.0 → 4.13.0

package/docs/spf.md

@@ -0,0 +1,196 @@
+# SPF Verification Result Reference
+
+This document describes the result object returned by the `spf()` function.
+
+## Overview
+
+The `spf` function verifies the SPF (Sender Policy Framework) record for an email sender and returns an object containing the verification result.
+
+```javascript
+const { spf } = require('mailauth/lib/spf');
+
+const result = await spf({
+    sender: 'user@example.com',
+    ip: '192.0.2.1',
+    helo: 'mail.example.com',
+    mta: 'mx.receiver.com'
+});
+```
+
+## Result Object Fields
+
+| Field | Type | Presence | Description |
+|-------|------|----------|-------------|
+| `domain` | `string` | Always | The domain extracted from the sender address for SPF lookup |
+| `client-ip` | `string` | Always | The client IP address that was checked |
+| `helo` | `string` | If provided | The EHLO/HELO hostname from the SMTP session |
+| `envelope-from` | `string` | If provided | The MAIL FROM address |
+| `status` | `object` | Always | Verification status object (see below) |
+| `header` | `string` | Always | Formatted Received-SPF header value |
+| `info` | `string` | Always | Formatted Authentication-Results header value |
+| `rr` | `string` | Record found | Raw SPF DNS TXT record |
+| `lookups` | `object` | Always | DNS lookup statistics (see below) |
+
+## status Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `result` | `string` | SPF result code (see below) |
+| `comment` | `string` | Human-readable explanation of the result |
+| `smtp` | `object` | SMTP session identifiers |
+
+### status.smtp Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mailfrom` | `string` | The MAIL FROM address |
+| `helo` | `string` | The HELO/EHLO hostname |
+
+## lookups Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `limit` | `number` | Maximum DNS lookups allowed (default: 10) |
+| `count` | `number` | Number of DNS lookups performed |
+| `void` | `number` | Number of void (empty result) DNS lookups |
+| `subqueries` | `object` | Counts of DNS queries by type (e.g., `{A: 2, MX: 1}`) |
+
+## Result Values
+
+| Result | SPF Qualifier | Description |
+|--------|---------------|-------------|
+| `pass` | `+` | Sender is authorized |
+| `fail` | `-` | Sender is explicitly not authorized |
+| `softfail` | `~` | Sender is probably not authorized (transitional) |
+| `neutral` | `?` | No policy assertion about the sender |
+| `none` | - | No SPF record found or invalid domain |
+| `permerror` | - | Permanent error (invalid SPF record, too many DNS lookups) |
+| `temperror` | - | Temporary error (DNS timeout, server refused) |
+
+## Comment Format
+
+The `status.comment` field follows this format based on the result:
+
+| Result | Comment Format |
+|--------|----------------|
+| `pass` | `"{mta}: domain of {sender} designates {ip} as permitted sender"` |
+| `fail` | `"{mta}: domain of {sender} does not designate {ip} as permitted sender"` |
+| `softfail` | `"{mta}: domain of transitioning {sender} does not designate {ip} as permitted sender"` |
+| `neutral` | `"{mta}: {ip} is neither permitted nor denied by domain of {sender}"` |
+| `none` | `"{mta}: {domain} does not designate permitted sender hosts"` |
+| `permerror` | `"{mta}: permanent error in processing during lookup of {sender}: {text}"` |
+| `temperror` | `"{mta}: error in processing during lookup of {sender}: {text}"` |
+
+## Example Output
+
+### SPF Pass
+
+```json
+{
+  "domain": "example.com",
+  "client-ip": "192.0.2.1",
+  "helo": "mail.example.com",
+  "envelope-from": "user@example.com",
+  "status": {
+    "result": "pass",
+    "comment": "mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender",
+    "smtp": {
+      "mailfrom": "user@example.com",
+      "helo": "mail.example.com"
+    }
+  },
+  "header": "Received-SPF: pass (mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender) client-ip=192.0.2.1;",
+  "info": "spf=pass (mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender) smtp.mailfrom=user@example.com smtp.helo=mail.example.com",
+  "rr": "v=spf1 ip4:192.0.2.0/24 -all",
+  "lookups": {
+    "limit": 10,
+    "count": 1,
+    "void": 0,
+    "subqueries": {}
+  }
+}
+```
+
+### SPF Fail
+
+```json
+{
+  "domain": "example.com",
+  "client-ip": "203.0.113.1",
+  "helo": "attacker.example.net",
+  "envelope-from": "user@example.com",
+  "status": {
+    "result": "fail",
+    "comment": "mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender",
+    "smtp": {
+      "mailfrom": "user@example.com",
+      "helo": "attacker.example.net"
+    }
+  },
+  "header": "Received-SPF: fail (mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender) client-ip=203.0.113.1;",
+  "info": "spf=fail (mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender) smtp.mailfrom=user@example.com smtp.helo=attacker.example.net",
+  "rr": "v=spf1 ip4:192.0.2.0/24 -all",
+  "lookups": {
+    "limit": 10,
+    "count": 1,
+    "void": 0,
+    "subqueries": {}
+  }
+}
+```
+
+### SPF None (No Record)
+
+```json
+{
+  "domain": "no-spf.example.com",
+  "client-ip": "192.0.2.1",
+  "helo": "mail.no-spf.example.com",
+  "envelope-from": "user@no-spf.example.com",
+  "status": {
+    "result": "none",
+    "comment": "mx.receiver.com: no-spf.example.com does not designate permitted sender hosts",
+    "smtp": {
+      "mailfrom": "user@no-spf.example.com",
+      "helo": "mail.no-spf.example.com"
+    }
+  },
+  "header": "Received-SPF: none (mx.receiver.com: no-spf.example.com does not designate permitted sender hosts) client-ip=192.0.2.1;",
+  "info": "spf=none (mx.receiver.com: no-spf.example.com does not designate permitted sender hosts) smtp.mailfrom=user@no-spf.example.com smtp.helo=mail.no-spf.example.com",
+  "lookups": {
+    "limit": 10,
+    "count": 1,
+    "void": 1,
+    "subqueries": {}
+  }
+}
+```
+
+### SPF Permerror (Too Many Lookups)
+
+```json
+{
+  "domain": "complex.example.com",
+  "client-ip": "192.0.2.1",
+  "envelope-from": "user@complex.example.com",
+  "status": {
+    "result": "permerror",
+    "comment": "mx.receiver.com: permanent error in processing during lookup of user@complex.example.com: Too many DNS requests",
+    "smtp": {
+      "mailfrom": "user@complex.example.com"
+    }
+  },
+  "header": "Received-SPF: permerror (mx.receiver.com: permanent error in processing during lookup of user@complex.example.com: Too many DNS requests) client-ip=192.0.2.1;",
+  "info": "spf=permerror (mx.receiver.com: permanent error in processing during lookup of user@complex.example.com: Too many DNS requests) smtp.mailfrom=user@complex.example.com",
+  "lookups": {
+    "limit": 10,
+    "count": 11,
+    "void": 0,
+    "subqueries": {
+      "include": 5,
+      "a": 3,
+      "mx": 2
+    }
+  }
+}
+```

package/lib/bimi/index.js

@@ -5,6 +5,7 @@ const crypto = require('node:crypto');
 const dns = require('node:dns');
 const { formatAuthHeaderRow, parseDkimHeaders, formatDomain, getAlignment } = require('../tools');
 const Joi = require('joi');
+const libmime = require('libmime');
 //const packageData = require('../../package.json');
 const httpsSchema = Joi.string().uri({
     scheme: ['https']
@@ -187,6 +188,10 @@ const lookup = async data => {
         response.status.policy = { authority: 'none', 'authority-uri': recordData.parsed.a.value }; // VMC has not been actually checked here yet, so authority is none
     }
 
+    if (recordData?.parsed?.p?.value) {
+        response.preference = recordData.parsed.p.value;
+    }
+
     response.info = formatAuthHeaderRow('bimi', response.status);
     return response;
 };
@@ -396,6 +401,21 @@ const validateVMC = async (bimiData, opts) => {
         }
     }
 
+    // Generate headers when validation succeeds
+    let canGenerateHeaders =
+        result.location?.success && result.location?.logoFile && (!result.authority || (result.authority.success && result.authority.hashMatch !== false));
+
+    if (canGenerateHeaders) {
+        result.headers = {
+            indicator: libmime.foldLines(`BIMI-Indicator: ${result.location.logoFile}`, 160),
+            location: `BIMI-Location: v=BIMI1; l=${bimiData.location}`
+        };
+
+        if (bimiData.preference) {
+            result.headers.preference = `BIMI-Logo-Preference: ${bimiData.preference}`;
+        }
+    }
+
     return result;
 };
 

package/lib/dkim/dkim-verifier.js

@@ -174,6 +174,19 @@ class DkimVerifier extends MessageParser {
         }
     }
 
+    getSignatureTimeValid(signatureHeader) {
+        // Signature claims to be from the future
+        if (signatureHeader.timestamp && signatureHeader.timestamp > this.curTime) {
+            return false;
+        }
+        // Signature has expired
+        if (signatureHeader.expiration && signatureHeader.expiration < this.curTime) {
+            return false;
+        }
+        // Within validity window or no constraints (vacuously true)
+        return true;
+    }
+
     async finalChunk() {
         try {
             if (!this.headers || !this.bodyHashes.size) {
@@ -341,7 +354,10 @@ class DkimVerifier extends MessageParser {
                     bodyHash,
                     bodyHashExpecting: signatureHeader.parsed?.bh?.value,
                     signingHeaders,
-                    status
+                    status,
+                    signTime: signatureHeader.timestamp ? signatureHeader.timestamp.toISOString() : null,
+                    expiresAfter: signatureHeader.expiration ? signatureHeader.expiration.toISOString() : null,
+                    signatureTimeValid: this.getSignatureTimeValid(signatureHeader)
                 };
 
                 if (typeof signatureHeader.sourceBodyLength === 'number') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mailauth",
-    "version": "4.12.0",
+    "version": "4.13.0",
     "description": "Email authentication library for Node.js",
     "main": "lib/mailauth.js",
     "types": "index.d.ts",
@@ -42,23 +42,23 @@
         "license-report": "6.8.1",
         "mbox-reader": "1.2.0",
         "mocha": "11.7.5",
-        "prettier": "3.7.4",
+        "prettier": "3.8.1",
         "resedit": "3.0.1"
     },
     "dependencies": {
-        "@postalsys/vmc": "1.1.2",
-        "fast-xml-parser": "4.5.2",
+        "@postalsys/vmc": "1.1.3",
+        "fast-xml-parser": "5.3.4",
         "ipaddr.js": "2.3.0",
         "joi": "18.0.2",
         "libmime": "5.3.7",
-        "nodemailer": "7.0.11",
+        "nodemailer": "7.0.13",
         "punycode.js": "2.3.1",
-        "tldts": "7.0.19",
-        "undici": "7.16.0",
+        "tldts": "7.0.21",
+        "undici": "7.20.0",
         "yargs": "17.7.2"
     },
     "engines": {
-        "node": ">=18.0.0"
+        "node": ">=20.18.1"
     },
     "bin": {
         "mailauth": "bin/mailauth.js"