mailauth 5.0.3 → 7.0.0

package/lib/dmarc/verify.js

@@ -1,48 +1,64 @@
 'use strict';
 
 const dns = require('node:dns').promises;
-const punycode = require('punycode.js');
-const tldts = require('tldts');
-const { formatAuthHeaderRow, getAlignment, TLDTS_OPTS } = require('../tools');
-const getDmarcRecord = require('./get-dmarc-record');
+const { formatAuthHeaderRow, formatDomain } = require('../tools');
+const { createRecordLookup, discoverPolicy, getOrgDomain, getPolicyTags, domainExists } = require('./get-dmarc-record');
+const { getAuthorDomain } = require('./author-domain');
 
-const verifyDmarc = async opts => {
-    let { headerFrom, spfDomains, dkimDomains, resolver, arcResult } = opts;
+// Every Tree Walk is capped at eight queries, but the number of walks is not (RFC 9989 4.10.2),
+// so a message can only make this many identifiers walk for relaxed alignment. An identifier
+// past the limit is not known to align or not, so it is treated like one whose walk failed.
+const MAX_ALIGNMENT_WALKS = 10;
 
-    resolver = resolver || dns.resolve;
+// t=y asks for the policy one level below the published one (RFC 9989 4.7 "t")
+const TEST_MODE_POLICY = { reject: 'quarantine', quarantine: 'none', none: 'none' };
 
-    if (Array.isArray(headerFrom)) {
-        if (headerFrom.length === 1) {
-            headerFrom = headerFrom[0];
-        } else {
-            // invalid number of FROM addresses found
-            return false;
-        }
-    }
+const POLICY_STRENGTH = { none: 0, quarantine: 1, reject: 2 };
 
-    let atPos = headerFrom.indexOf('@');
-    let domain = atPos >= 0 ? headerFrom.substr(atPos + 1) : headerFrom;
+// Two domains can only have the same Organizational Domain if they have a common parent. With
+// no common label at all no Tree Walk result could make them align.
+const shareParent = (a, b) => a.split('.').pop() === b.split('.').pop();
 
-    domain = domain.toLowerCase().trim();
+const setHidden = (obj, key, value) => Object.defineProperty(obj, key, { value, enumerable: false, configurable: true, writable: true });
 
-    try {
-        domain = punycode.toASCII(domain);
-    } catch (err) {
-        // ignore punycode conversion errors
+const evaluateDmarc = async opts => {
+    let { headerFrom, fromFields, spfDomains, dkimDomains, resolver, arcResult, strict } = opts;
+
+    strict = !!strict;
+    resolver = resolver || dns.resolve;
+
+    // RFC 9989 5.3.1: several mailboxes are fine if they share one domain, but with zero or more
+    // than one Author Domain DMARC validation is not possible. The response stays false, as it
+    // always was for these messages, and "reason" says why.
+    const author = getAuthorDomain(headerFrom, fromFields);
+    if (!author.authorDomain) {
+        return { response: false, reason: author.reason, authorDomains: author.domains };
     }
 
+    // "domain" is reported in header.from. "authorDomain" is the name to query and compare,
+    // where "example.com." and "example.com" are the same domain.
+    const { domain, authorDomain } = author;
+
+    // what the default mode accepted that strict mode would not
+    const warnings = new Set();
+
     let formatResponse = response => {
-        response.info = formatAuthHeaderRow('dmarc', response.status);
+        if (warnings.size) {
+            response.warnings = Array.from(warnings);
+        }
+
+        response.info = formatAuthHeaderRow('dmarc', response.status, { strict });
 
         if (typeof response.status.comment === 'boolean') {
             delete response.status.comment;
         }
 
+        // for BIMI (draft-brand-indicators-for-message-identification 7.1), not part of the result
+        setHidden(response, 'authorMailboxes', author.mailboxes);
+
         return response;
     };
 
-    let orgDomain = tldts.getDomain(domain, TLDTS_OPTS);
-
     let status = {
         result: 'neutral',
         comment: false,
@@ -54,67 +70,203 @@ const verifyDmarc = async opts => {
         }
     };
 
-    let dmarcRecord;
+    // the strict parsing rejects what the default parsing would note, so it adds no warnings
+    const lookup = createRecordLookup(resolver, { strict, warnings });
+
+    let policyDiscovery;
     try {
-        dmarcRecord = await getDmarcRecord(domain, resolver);
+        policyDiscovery = await discoverPolicy(authorDomain, lookup);
     } catch (err) {
         // temperror?
         status.result = 'temperror';
-        return formatResponse({ status, domain: orgDomain || domain, error: err.message });
+        return { response: formatResponse({ status, domain: authorDomain, error: err.message }) };
     }
 
+    let { record: dmarcRecord, recordDomain, orgDomain, orgRecord } = policyDiscovery;
+
     if (!dmarcRecord) {
         // nothing to do here
         // none
         status.result = 'none';
-        return formatResponse({ status, domain: orgDomain || domain });
+        return { response: formatResponse({ status, domain: orgDomain }) };
+    }
+
+    const policyTags = getPolicyTags(dmarcRecord);
+    if (!policyTags) {
+        // no valid policy and nowhere to report to, the record gets no DMARC processing (RFC 9989 4.10.1)
+        status.result = 'none';
+        return { response: formatResponse({ status, domain: orgDomain || authorDomain }) };
     }
 
-    // the domain the applied policy record was published at
-    status.header.d = dmarcRecord.isOrgRecord ? orgDomain : domain;
+    if (!strict) {
+        // The domain the applied policy record was published at, the DMARC Policy Domain. This
+        // property is not registered for dmarc (RFC 9989 9.1), so strict mode leaves it out and
+        // the domain is only reported in "policyDomain".
+        status.header.d = recordDomain;
+    }
+
+    let policy = policyTags.p;
+    // set when the existence query that decides between "sp" and "np" failed
+    let existenceError = null;
+    if (recordDomain !== authorDomain) {
+        // A record inherited by a subdomain applies "np" if the subdomain does not exist and "sp"
+        // if it does, both falling back to "p" (RFC 9989 4.10.1). Existence only matters with "np".
+        policy = policyTags.sp || policyTags.p;
+        if (policyTags.np) {
+            try {
+                if (!(await domainExists(authorDomain, resolver))) {
+                    policy = policyTags.np;
+                }
+            } catch (err) {
+                if (policyTags.np !== policy) {
+                    // The policy is one of the two, but which one is not known. This only matters
+                    // for a message that does not pass. Until then the weaker one is assumed, so
+                    // that nothing (such as BIMI) treats the domain as more enforcing than it is.
+                    existenceError = err;
+                    if (POLICY_STRENGTH[policyTags.np] < POLICY_STRENGTH[policy]) {
+                        policy = policyTags.np;
+                    }
+                }
+            }
+        }
+    }
+
+    const testMode = dmarcRecord.t === 'y';
+    if (testMode) {
+        policy = TEST_MODE_POLICY[policy];
+    }
 
     status.comment = []
-        .concat(dmarcRecord.p ? `p=${dmarcRecord.p.toUpperCase()}` : [])
-        .concat(dmarcRecord.sp ? `sp=${dmarcRecord.sp.toUpperCase()}` : [])
+        .concat(`p=${policyTags.p.toUpperCase()}`)
+        .concat(policyTags.sp ? `sp=${policyTags.sp.toUpperCase()}` : [])
         .concat(arcResult?.status?.result ? `arc=${arcResult?.status?.result}` : [])
         .join(' ');
 
-    // use "sp" if this is a subdomain of an org domain and "sp" is set, otherwise use "p"
-    const policy = dmarcRecord.isOrgRecord && dmarcRecord.sp ? dmarcRecord.sp : dmarcRecord.p;
-
     const adkimStrict = dmarcRecord.adkim === 's';
     const aspfStrict = dmarcRecord.aspf === 's';
 
-    const dkimAlignment = getAlignment(domain, dkimDomains, adkimStrict);
-    const spfAlignment = getAlignment(domain, spfDomains, aspfStrict);
+    // Relaxed alignment compares Organizational Domains found by Tree Walks (RFC 9989 4.10.2).
+    // An identifier's Organizational Domain is always the identifier itself or one of its
+    // parents, so only identifiers at or below the author's Organizational Domain need a walk.
+    let orgDomains = new Map();
+    // throws when a Tree Walk the answer depends on failed, or was not made because of the limit
+    const alignsRelaxed = async entryDomain => {
+        if (entryDomain === authorDomain) {
+            return true;
+        }
+        if (!orgDomain) {
+            // The author's own Tree Walk failed, so there is nothing to compare against,
+            // unless the two domains have no parent in common and can never align
+            if (!shareParent(entryDomain, authorDomain)) {
+                return false;
+            }
+            throw policyDiscovery.error;
+        }
+        if (entryDomain !== orgDomain && !entryDomain.endsWith(`.${orgDomain}`)) {
+            return false;
+        }
+        if (!orgDomains.has(entryDomain)) {
+            if (orgDomains.size >= MAX_ALIGNMENT_WALKS) {
+                let err = new Error(`Alignment of ${entryDomain} not checked, limit of ${MAX_ALIGNMENT_WALKS} Tree Walks per message reached`);
+                err.code = 'EWALKLIMIT';
+                throw err;
+            }
+            orgDomains.set(entryDomain, getOrgDomain(entryDomain, lookup));
+        }
+        return (await orgDomains.get(entryDomain)) === orgDomain;
+    };
+
+    // Returns every entry that aligns, most preferred first, and the first walk error seen.
+    // Signatures with an l= tag come last, so that a signature covering the whole body is
+    // reported when several align.
+    const findAligned = async (entries, strictAlignment) => {
+        let list = []
+            .concat(entries || [])
+            .map(entry => (typeof entry === 'string' ? { domain: entry } : entry))
+            .filter(entry => entry && typeof entry.domain === 'string')
+            .sort((a, b) => (a.underSized || 0) - (b.underSized || 0));
+
+        let aligned = [];
+        let error = null;
+        for (let entry of list) {
+            let entryDomain = formatDomain(entry.domain);
+            if (!authorDomain || !entryDomain) {
+                // a bare root label normalizes to an empty string, which must not align with anything
+                continue;
+            }
+            try {
+                if (strictAlignment ? entryDomain === authorDomain : await alignsRelaxed(entryDomain)) {
+                    aligned.push(entry);
+                }
+            } catch (err) {
+                error = error || err;
+            }
+        }
+
+        return { aligned, error };
+    };
+
+    // SPF first, so a flood of DKIM signatures can not use up the walks it needs
+    const spf = await findAligned(spfDomains, aspfStrict);
+    // every signature is checked, so that each one's own alignment can be reported
+    const dkim = await findAligned(dkimDomains, adkimStrict);
+    const spfAlignment = spf.aligned[0];
+    const dkimAlignment = dkim.aligned[0];
+    const walkError = spf.error || dkim.error;
 
     // "underSized" warns that a passing DKIM signature covers only part of the body (l= tag).
     // It describes the signature rather than the alignment mode, so it is still reported when
-    // strict alignment rejected a signature that aligns at the org level.
-    const underSized = (adkimStrict && !dkimAlignment ? getAlignment(domain, dkimDomains, false) : dkimAlignment)?.underSized;
+    // strict alignment rejected a signature that aligns at the org level. A walk that fails
+    // for this warning alone does not affect the result.
+    const underSized = adkimStrict && !dkimAlignment ? (await findAligned(dkimDomains, false)).aligned[0]?.underSized : dkimAlignment?.underSized;
+
+    let response = {
+        status,
+        domain: orgDomain || authorDomain,
+        // the DMARC Policy Domain (RFC 9989 3.2.5), where the applied record was published.
+        // This is the domain RFC 9990 aggregate reports list as the published policy's domain.
+        policyDomain: recordDomain,
+        policy,
+        p: policyTags.p,
+        sp: policyTags.sp || policyTags.p,
+        np: policyTags.np,
+        testMode,
+        rr: dmarcRecord.rr,
+
+        alignment: {
+            spf: { result: spfAlignment?.domain, strict: aspfStrict },
+            dkim: { result: dkimAlignment?.domain, strict: adkimStrict, underSized }
+        }
+    };
 
     if (dkimAlignment || spfAlignment) {
         // pass
         status.result = 'pass';
+    } else if (walkError || existenceError) {
+        // an identifier might have aligned if its Tree Walk had not failed, or the
+        // policy to apply is not known because the author domain's existence is not
+        status.result = 'temperror';
+        response.error = (walkError || existenceError).message;
     } else {
         // fail
         status.result = 'fail';
     }
 
-    return formatResponse({
-        status,
-        domain: orgDomain || domain,
-        policy,
-        p: dmarcRecord.p,
-        sp: dmarcRecord.sp || dmarcRecord.p,
-        pct: dmarcRecord.pct,
-        rr: dmarcRecord.rr,
+    if (status.result !== 'temperror' && !existenceError) {
+        // RFC 9989 9.1: the evaluated policy after the policy options have been processed
+        status.policy = { dmarc: policy };
+    }
 
-        alignment: {
-            spf: { result: spfAlignment?.domain, strict: aspfStrict },
-            dkim: { result: dkimAlignment?.domain, strict: adkimStrict, underSized }
-        }
-    });
+    // for BIMI (draft-brand-indicators-for-message-identification 7.1), not part of the result:
+    // the applied record and the record holding the Organizational Domain's policy (null if unknown)
+    setHidden(response, 'record', dmarcRecord);
+    setHidden(response, 'orgRecord', orgRecord);
+
+    return { response: formatResponse(response), dkimAligned: new Set(dkim.aligned.map(entry => formatDomain(entry.domain))) };
 };
 
+const verifyDmarc = async opts => (await evaluateDmarc(opts)).response;
+
 module.exports = verifyDmarc;
+// also returns the signing domains that aligned, for the per signature flags of authenticate()
+module.exports.evaluateDmarc = evaluateDmarc;

package/lib/mailauth.js

@@ -3,12 +3,12 @@
 const { dkimSign, DkimSignStream } = require('./dkim/sign');
 const { dkimVerify } = require('./dkim/verify');
 const { spf } = require('./spf');
-const { dmarc } = require('./dmarc');
+const { dmarc, evaluateDmarc } = require('./dmarc');
 const { arc, createSeal, sealMessage, getARChain, verifyASChain } = require('./arc');
 const { bimi, validateVMC: validateBimiVmc } = require('./bimi');
 const { validateSvg: validateBimiSvg } = require('./bimi/validate-svg');
-const { parseReceived } = require('./parse-received');
-const { getAlignment } = require('./tools');
+const { parseReceived, getClientAddress } = require('./parse-received');
+const { formatDomain, getAlignment, formatAuthservId } = require('./tools');
 const libmime = require('libmime');
 const os = require('node:os');
 const { isIP } = require('net');
@@ -31,18 +31,25 @@ const { isIP } = require('net');
  * @param {Boolean} [opts.disableArc=false] If true then do not perform ARC validation and sealing
  * @param {Boolean} [opts.disableDmarc=false] If true then do not perform DMARC check
  * @param {Boolean} [opts.disableBimi=false] If true then do not perform BIMI check
+ * @param {Boolean} [opts.strict=false] If true then every check follows its RFC exactly instead of the lenient defaults
  * @returns Authentication result
  */
 const authenticate = async (input, opts) => {
     opts = Object.assign({}, opts); // copy keys
 
     opts.mta = opts.mta || os.hostname();
+    opts.strict = !!opts.strict;
+
+    // RFC 8601 section 2.5: the authserv-id, usually a host name. A value that is not a token is
+    // quoted, or throws under strict, before any work is done
+    const authservId = formatAuthservId(opts.mta, opts.strict);
 
     const dkimResult = await dkimVerify(input, {
         resolver: opts.resolver,
         sender: opts.sender, // defaults to Return-Path header
         seal: opts.seal,
-        minBitLength: opts.minBitLength
+        minBitLength: opts.minBitLength,
+        strict: opts.strict
     });
 
     const receivedChain = dkimResult.headers?.parsed.filter(r => r.key === 'received').map(row => parseReceived(row.line));
@@ -52,13 +59,9 @@ const authenticate = async (input, opts) => {
         let rcvd = receivedChain?.find(row => row.from?.value);
         if (rcvd) {
             let helo = rcvd.from.value;
-            let ip;
-            if (rcvd.from.comment) {
-                let ipMatch = rcvd.from.comment.match(/\[([^\]]+)\]/);
-                if (ipMatch) {
-                    ip = ipMatch[1].replace(/^IPv6:/i, '');
-                }
-            }
+            // the address of the connection from the TCP-info part of the from clause
+            // (RFC 5321 section 4.4), never an address the client claimed in its HELO
+            let ip = getClientAddress(rcvd.from);
 
             if (ip && !opts.ip) {
                 opts.ip = ip;
@@ -95,12 +98,16 @@ const authenticate = async (input, opts) => {
     if (!opts.disableArc) {
         arcResult = await arc(dkimResult.arc, {
             resolver: opts.resolver,
-            minBitLength: opts.minBitLength
+            minBitLength: opts.minBitLength,
+            strict: opts.strict,
+            // reported as smtp.remote-ip in strict mode (RFC 8617 section 6)
+            ip: opts.ip
         });
     }
 
     let headers = [];
     let arHeader = [];
+    let receivedSpfHeader = false;
 
     dkimResult?.results?.forEach(row => {
         arHeader.push(`${libmime.foldLines(row.info, 160)}`);
@@ -108,7 +115,7 @@ const authenticate = async (input, opts) => {
 
     if (spfResult) {
         arHeader.push(libmime.foldLines(spfResult.info, 160));
-        headers.push(spfResult.header);
+        receivedSpfHeader = spfResult.header;
     }
 
     if (arcResult?.info) {
@@ -116,9 +123,16 @@ const authenticate = async (input, opts) => {
     }
 
     let dmarcResult;
+    let dmarcSkipReason;
     if (!opts.disableDmarc && dkimResult?.headerFrom) {
-        dmarcResult = await dmarc({
+        let dkimAligned;
+        ({
+            response: dmarcResult,
+            dkimAligned,
+            reason: dmarcSkipReason
+        } = await evaluateDmarc({
             headerFrom: dkimResult.headerFrom,
+            fromFields: dkimResult.fromFields,
             spfDomains: [].concat((spfResult && spfResult.status.result === 'pass' && spfResult.domain) || []),
             dkimDomains: (dkimResult.results || [])
                 .filter(r => r.status.result === 'pass')
@@ -129,17 +143,24 @@ const authenticate = async (input, opts) => {
                     underSized: r.status.underSized
                 })),
             arcResult,
-            resolver: opts.resolver
-        });
-        if (dmarcResult.info) {
+            resolver: opts.resolver,
+            strict: opts.strict
+        }));
+        if (dmarcResult?.info) {
             arHeader.push(`${libmime.foldLines(dmarcResult.info, 160)}`);
         }
 
-        if (dmarcResult.alignment?.dkim?.strict) {
-            // the DKIM verifier only knows relaxed alignment, it runs before the DMARC record
+        if (dkimAligned && dmarcResult) {
+            // The DKIM verifier runs before the DMARC record and the Tree Walks are known, so its
+            // per signature flag only guesses relaxed alignment from the Public Suffix List.
+            // Passing signatures take the DMARC verdict, failing ones the record's alignment mode.
             let fromDomain = dmarcResult.status.header.from;
             for (let row of dkimResult.results || []) {
-                row.status.aligned = (row.status.aligned && getAlignment(fromDomain, [row.signingDomain], true)?.domain) || false;
+                if (row.status.result === 'pass') {
+                    row.status.aligned = dkimAligned.has(formatDomain(row.signingDomain)) ? row.signingDomain : false;
+                } else if (dmarcResult.alignment.dkim.strict) {
+                    row.status.aligned = (row.status.aligned && getAlignment(fromDomain, [row.signingDomain], true)?.domain) || false;
+                }
             }
         }
     }
@@ -150,7 +171,8 @@ const authenticate = async (input, opts) => {
             dmarc: dmarcResult,
             headers: dkimResult.headers,
             bimiWithAlignedDkim: opts.bimiWithAlignedDkim,
-            resolver: opts.resolver
+            resolver: opts.resolver,
+            strict: opts.strict
         });
     }
 
@@ -158,42 +180,57 @@ const authenticate = async (input, opts) => {
         arHeader.push(`${libmime.foldLines(bimiResult.info, 160)}`);
     }
 
-    headers.push(`Authentication-Results: ${opts.mta};\r\n ` + arHeader.join(';\r\n '));
+    const arValue = `${authservId};\r\n ` + arHeader.join(';\r\n ');
+    const authResultsHeader = `Authentication-Results: ${arValue}`;
+
+    if (opts.strict) {
+        // RFC 8601 section 5: Authentication-Results "SHOULD be inserted above any other
+        // trace header fields", and Received-SPF is one (RFC 7208 section 9.1)
+        headers.push(authResultsHeader);
+        if (receivedSpfHeader) {
+            headers.push(receivedSpfHeader);
+        }
+    } else {
+        if (receivedSpfHeader) {
+            headers.push(receivedSpfHeader);
+        }
+        headers.push(authResultsHeader);
+    }
 
     if (arcResult) {
-        arcResult.authResults = `${opts.mta};\r\n ` + arHeader.join(';\r\n ');
+        arcResult.authResults = arValue;
     }
 
     // seal only messages with a valid ARC chain
     if (dkimResult?.seal && (['none', 'pass'].includes(arcResult?.status?.result) || arcResult?.status?.shouldSeal)) {
-        let i = arcResult.i + 1;
-        let seal = Object.assign(
-            {
-                i,
-                cv: arcResult.status.result,
-                authResults: arcResult.authResults,
-                signTime: new Date()
-            },
-            dkimResult.seal
-        );
-
-        // get ARC sealing headers to prepend to the message
+        // createSeal picks the instance: the next one after the highest on the message, even if
+        // some of the ARC headers were not part of a valid chain, and never a 51st set
         let sealResult = await createSeal(false, {
             headers: dkimResult.headers,
             arc: dkimResult.arc,
-            seal
+            seal: Object.assign(
+                {
+                    cv: arcResult.status.result,
+                    authResults: arcResult.authResults,
+                    signTime: new Date()
+                },
+                dkimResult.seal
+            ),
+            strict: opts.strict
         });
 
         if (sealResult?.errors?.length) {
-            // sealing failed, usually an unusable key. The message goes out unsealed, so
-            // say why somewhere the caller can find it rather than dropping it silently
+            // sealing failed, usually an unusable key or a chain that is already full. The
+            // message goes out unsealed, so say why somewhere the caller can find it rather
+            // than dropping it silently
             arcResult.sealErrors = sealResult.errors;
         }
 
-        sealResult?.headers?.reverse().forEach(header => headers.unshift(header));
+        // the ARC headers go on top of the message
+        headers.unshift(...(sealResult?.headers || []));
     }
 
-    return {
+    const result = {
         dkim: dkimResult,
         spf: spfResult,
         dmarc: dmarcResult || false,
@@ -202,6 +239,15 @@ const authenticate = async (input, opts) => {
         receivedChain,
         headers: headers.join('\r\n') + '\r\n'
     };
+
+    if (!dmarcResult && dmarcSkipReason) {
+        // RFC 9989 section 5.3.1: DMARC can not be evaluated for a message with no Author
+        // Domain or with more than one, and section 11.5 suggests treating such a message as
+        // suspicious. `dmarc` stays false, this says why
+        result.dmarcSkipReason = dmarcSkipReason;
+    }
+
+    return result;
 };
 
 module.exports = {