mailauth 6.0.0 → 7.0.0

package/lib/bimi/index.js

@@ -3,9 +3,12 @@
 const { Buffer } = require('node:buffer');
 const crypto = require('node:crypto');
 const dns = require('node:dns');
-const { formatAuthHeaderRow, parseDkimHeaders, formatDomain, getAlignment } = require('../tools');
+const { formatAuthHeaderRow, parseDkimHeaders, parseTagList, formatDomain, getAlignment } = require('../tools');
 const Joi = require('joi');
 const libmime = require('libmime');
+const addressparser = require('nodemailer/lib/addressparser');
+const getDmarcRecord = require('../dmarc/get-dmarc-record');
+const { parseDmarcRecord } = getDmarcRecord;
 //const packageData = require('../../package.json');
 const httpsSchema = Joi.string().uri({
     scheme: ['https']
@@ -21,8 +24,61 @@ const fetchAgent = new Agent({
 const { vmc } = require('@postalsys/vmc');
 const { validateSvg } = require('./validate-svg');
 
+// Records that do not start with a "v=" tag for the current version are discarded (7.2 steps 4 and 7)
+const BIMI_VERSION_RE = /^v[ \t]*=[ \t]*BIMI1[ \t]*(?:;|$)/i;
+
+const POLICY_VALUES = new Set(['none', 'quarantine', 'reject']);
+
+// Returns the reason a DMARC record does not meet the policy requirements of
+// draft-brand-indicators-for-message-identification 7.1 steps 7 to 9, or false if it does
+const checkDmarcRecord = record => {
+    // a record without a valid "p" is applied as p=none, or not at all (RFC 9989 4.10.1)
+    if (!POLICY_VALUES.has(record.p) || record.p === 'none') {
+        return 'too lax DMARC policy';
+    }
+    if (record.sp === 'none') {
+        return 'too lax DMARC subdomain policy';
+    }
+    if (record.p === 'quarantine' && record.pct !== undefined && record.pct !== 100) {
+        return 'DMARC policy applied to a percentage of messages';
+    }
+    return false;
+};
+
+// Parses a BIMI Assertion Record, which uses the DKIM tag-list syntax (4.3, RFC 6376 3.2). The
+// values are the strings of the tag list: the parsed map of parseTagList would turn an empty "l="
+// into the number 0. Tag names are case-folded and the last duplicate wins, as before.
+const parseAssertionRecord = record => {
+    let tags = {};
+    for (let tag of parseTagList(record).tags) {
+        let name = tag.name.trim().toLowerCase();
+        if (name) {
+            tags[name] = tag.value;
+        }
+    }
+    return tags;
+};
+
+// Counts the addresses in the From header fields, including members of a group
+const countFromAddresses = headerRows => {
+    let fromRows = headerRows.filter(row => row.key === 'from');
+    if (fromRows.length > 1) {
+        return fromRows.length;
+    }
+    let count = 0;
+    for (let row of fromRows) {
+        let value = (row.line || '').toString();
+        let splitterPos = value.indexOf(':');
+        let list = addressparser((splitterPos >= 0 ? value.substr(splitterPos + 1) : value).trim());
+        for (let entry of list) {
+            count += Array.isArray(entry.group) ? entry.group.length : 1;
+        }
+    }
+    return count;
+};
+
 const lookup = async data => {
-    let { dmarc, headers, resolver, bimiWithAlignedDkim } = data;
+    let { dmarc, headers, resolver, bimiWithAlignedDkim, strict } = data;
     let headerRows = (headers && headers.parsed) || [];
 
     resolver = resolver || dns.promises.resolve;
@@ -34,32 +90,36 @@ const lookup = async data => {
 
     let response = { status: { header: {} } };
 
-    if (dmarc.status?.result !== 'pass') {
-        response.status.result = 'skipped';
-        response.status.comment = dmarc.status?.result === 'none' ? 'DMARC not enabled' : 'message failed DMARC';
-        response.info = formatAuthHeaderRow('bimi', response.status);
+    const finish = (result, comment) => {
+        response.status.result = result;
+        if (comment) {
+            response.status.comment = comment;
+        }
+        response.info = formatAuthHeaderRow('bimi', response.status, { strict });
         return response;
+    };
+
+    // 7.1 step 1: one From header field with one address. DMARC evaluates several addresses of the same domain.
+    let mailboxes = typeof dmarc.authorMailboxes === 'number' ? dmarc.authorMailboxes : 0;
+    if (mailboxes > 1 || countFromAddresses(headerRows) > 1) {
+        return finish('skipped', 'multiple From addresses');
     }
 
-    if (dmarc.policy === 'none' || (dmarc.policy === 'quarantine' && dmarc.pct && dmarc.pct < 100)) {
-        response.status.result = 'skipped';
-        response.status.comment = 'too lax DMARC policy';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+    if (dmarc.status?.result !== 'pass') {
+        return finish('skipped', dmarc.status?.result === 'none' ? 'DMARC not enabled' : 'message failed DMARC');
+    }
+
+    // a domain testing its policy (t=y) is not enforcing it yet
+    if (dmarc.policy === 'none' || dmarc.testMode) {
+        return finish('skipped', 'too lax DMARC policy');
     }
 
     if (!dmarc.alignment?.dkim?.result && bimiWithAlignedDkim) {
-        response.status.result = 'skipped';
-        response.status.comment = 'Aligned DKIM signature required';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+        return finish('skipped', 'Aligned DKIM signature required');
     }
 
     if (dmarc.alignment?.dkim?.underSized) {
-        response.status.result = 'skipped';
-        response.status.comment = 'undersized DKIM signature';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+        return finish('skipped', 'undersized DKIM signature');
     }
 
     const authorDomain = dmarc.status?.header?.from;
@@ -67,10 +127,42 @@ const lookup = async data => {
 
     if (!authorDomain || !orgDomain) {
         // should this even happen?
-        response.status.result = 'skipped';
-        response.status.comment = 'could not determine domain';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+        return finish('skipped', 'could not determine domain');
+    }
+
+    // 7.1 steps 7 to 9: neither the record for the Author Domain nor the one for the Author
+    // Organizational Domain may be p=none or sp=none, or apply quarantine to a percentage only.
+    // dmarc() provides both records, for a result built elsewhere they are looked up here.
+    let dmarcRecords = [];
+    let appliedRecord = dmarc.record || (dmarc.rr ? parseDmarcRecord(dmarc.rr) : null);
+    if (appliedRecord) {
+        dmarcRecords.push(appliedRecord);
+    }
+    let orgRecord = dmarc.orgRecord;
+    if (orgRecord === undefined) {
+        let appliedDomain = dmarc.policyDomain || dmarc.status?.header?.d || formatDomain(authorDomain);
+        if (formatDomain(orgDomain) !== formatDomain(appliedDomain) || !appliedRecord) {
+            try {
+                orgRecord = await getDmarcRecord(orgDomain, resolver);
+            } catch (err) {
+                orgRecord = null;
+            }
+        } else {
+            orgRecord = false;
+        }
+    }
+    if (orgRecord === null) {
+        // the Tree Walk that finds the Organizational Domain failed
+        return finish('temperror', 'failed to resolve the DMARC policy of the organizational domain');
+    }
+    if (orgRecord) {
+        dmarcRecords.push(orgRecord);
+    }
+    for (let record of dmarcRecords) {
+        let reason = checkDmarcRecord(record);
+        if (reason) {
+            return finish('skipped', reason);
+        }
     }
 
     let selector;
@@ -80,18 +172,12 @@ const lookup = async data => {
         if (['bimi-selector'].includes(row.key)) {
             if (bimiSelectorHeader) {
                 // already found one
-                response.status.result = 'fail';
-                response.status.comment = 'multiple BIMI-Selector headers';
-                response.info = formatAuthHeaderRow('bimi', response.status);
-                return response;
+                return finish('fail', 'multiple BIMI-Selector headers');
             }
 
             bimiSelectorHeader = parseDkimHeaders(row.line);
             if (bimiSelectorHeader?.parsed?.v?.value?.toLowerCase() !== 'bimi1') {
-                response.status.result = 'fail';
-                response.status.comment = 'missing bimi version in selector header';
-                response.info = formatAuthHeaderRow('bimi', response.status);
-                return response;
+                return finish('fail', 'missing bimi version in selector header');
             }
 
             selector = bimiSelectorHeader?.parsed?.s?.value;
@@ -100,9 +186,11 @@ const lookup = async data => {
 
     selector = selector?.trim() || 'default';
 
+    // 7.2 steps 3 and 6: the selector at the Author Domain, then the same selector at the
+    // Organizational Domain. A custom selector does not fall back to "default".
     let bimiTags = [`${selector}._bimi.${authorDomain}`];
-    if (selector !== 'default' || authorDomain !== orgDomain) {
-        bimiTags.push(`default._bimi.${orgDomain}`);
+    if (formatDomain(authorDomain) !== formatDomain(orgDomain)) {
+        bimiTags.push(`${selector}._bimi.${orgDomain}`);
     }
 
     let record;
@@ -114,85 +202,78 @@ const lookup = async data => {
             if (err.code === 'ENOTFOUND' || err.code === 'ENODATA') {
                 continue;
             }
-            response.status.result = 'temperr';
-            response.status.comment = `failed to resolve ${d}`;
-            response.info = formatAuthHeaderRow('bimi', response.status);
-            return response;
+            // "temperror" is the result keyword of the draft (7.7), older versions used "temperr"
+            return finish('temperror', `failed to resolve ${d}`);
         }
 
-        if (txt?.length === 1 && Array.isArray(txt?.[0])) {
-            record = txt[0]?.join('').trim();
+        // 7.2 steps 4 and 7: other TXT records, such as site verification tokens, are discarded
+        let records = []
+            .concat(txt || [])
+            .map(row => (Array.isArray(row) ? row.join('') : String(row)).trim())
+            .filter(row => BIMI_VERSION_RE.test(row));
+
+        if (records.length === 1) {
+            record = records[0];
             response.status.header.selector = d.split('._bimi.').shift();
             response.status.header.d = d.split('._bimi.').pop();
             response.rr = record;
             break;
-        } else if (txt) {
-            response.status.result = 'temperr';
-            response.status.comment = `invalid BIMI response for ${d}`;
-            response.info = formatAuthHeaderRow('bimi', response.status);
-            return response;
+        } else if (records.length > 1) {
+            // 7.2 step 9: several records end the discovery
+            return finish('fail', `multiple BIMI records for ${d}`);
         }
     }
 
     if (!record) {
-        response.status.result = 'none';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+        return finish('none');
     }
 
-    let recordData = parseDkimHeaders(`DNS: TXT;${record}`);
-    if (recordData?.parsed?.v?.value?.toLowerCase() !== 'bimi1') {
-        response.status.result = 'fail';
-        response.status.comment = 'missing bimi version in dns record';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+    let recordData = parseAssertionRecord(record);
+    if (recordData.v?.toLowerCase() !== 'bimi1') {
+        return finish('fail', 'missing bimi version in dns record');
     }
 
-    if (!recordData?.parsed?.l?.value && !recordData?.parsed?.a?.value) {
-        response.status.result = 'fail';
-        response.status.comment = 'missing location value in dns record';
-        response.info = formatAuthHeaderRow('bimi', response.status);
-        return response;
+    let location = recordData.l;
+    let authority = recordData.a;
+
+    // 4.3.1 and 7.5: an empty l= with an empty or missing a= is a Declination to Publish
+    if (location === '' && !authority) {
+        return finish('declined');
     }
 
-    if (recordData?.parsed?.l?.value) {
-        let locationValidation = httpsSchema.validate(recordData?.parsed?.l?.value);
-        if (locationValidation.error) {
-            response.status.result = 'fail';
-            response.status.comment = 'invalid location value in dns record';
-            response.info = formatAuthHeaderRow('bimi', response.status);
-            return response;
-        }
+    // l= is required (4.3), and 7.3 step 1 needs a valid one even when a= is set
+    if (!location) {
+        return finish('fail', 'missing location value in dns record');
     }
 
-    if (recordData?.parsed?.a?.value) {
-        let authorityValidation = httpsSchema.validate(recordData?.parsed?.a?.value);
+    let locationValidation = httpsSchema.validate(location);
+    if (locationValidation.error) {
+        return finish('fail', 'invalid location value in dns record');
+    }
+
+    if (authority) {
+        let authorityValidation = httpsSchema.validate(authority);
         if (authorityValidation.error) {
-            response.status.result = 'fail';
-            response.status.comment = 'invalid authority value in dns record';
-            response.info = formatAuthHeaderRow('bimi', response.status);
-            return response;
+            return finish('fail', 'invalid authority value in dns record');
         }
     }
 
     response.status.result = 'pass';
 
-    if (recordData?.parsed?.l?.value) {
-        response.location = recordData.parsed.l.value;
-    }
+    response.location = location;
 
-    if (recordData?.parsed?.a?.value) {
-        response.authority = recordData.parsed.a.value;
+    if (authority) {
+        response.authority = authority;
 
         // Apple Mail requires additional policy header values in Authentication-Results header
-        response.status.policy = { authority: 'none', 'authority-uri': recordData.parsed.a.value }; // VMC has not been actually checked here yet, so authority is none
+        response.status.policy = { authority: 'none', 'authority-uri': authority }; // VMC has not been actually checked here yet, so authority is none
     }
 
-    if (recordData?.parsed?.p?.value) {
-        response.preference = recordData.parsed.p.value;
+    if (recordData.p) {
+        response.preference = recordData.p;
     }
 
-    response.info = formatAuthHeaderRow('bimi', response.status);
+    response.info = formatAuthHeaderRow('bimi', response.status, { strict });
     return response;
 };
 

package/lib/commands/report.js

@@ -25,7 +25,8 @@ const cmd = async argv => {
     }
 
     const opts = {
-        trustReceived: true
+        trustReceived: true,
+        strict: !!argv.strict
     };
 
     if (argv.clientIp) {

package/lib/commands/seal.js

@@ -1,7 +1,8 @@
 'use strict';
 
+const { Buffer } = require('node:buffer');
 const { authenticate } = require('../mailauth');
-const { sealMessage } = require('../arc');
+const { createSeal } = require('../arc');
 const fs = require('node:fs');
 const { GathererStream } = require('../gatherer-stream');
 const { resolve } = require('node:dns').promises;
@@ -67,7 +68,8 @@ const cmd = async argv => {
         privateKey,
         algorithm: argv.algo,
         headerList: argv.headerFields,
-        signTime: argv.time ? new Date(argv.time * 1000) : new Date()
+        signTime: argv.time ? new Date(argv.time * 1000) : new Date(),
+        strict: !!argv.strict
     };
 
     if (argv.authResults || argv.authResultsFile) {
@@ -93,14 +95,36 @@ const cmd = async argv => {
             console.error('--------');
         }
 
-        let sealHeaders = await sealMessage(gatherer, sealOpts);
+        let { headers, errors, warnings } = await createSeal(gatherer, { seal: sealOpts });
+
+        if (!headers.length) {
+            // nothing was sealed, say why instead of printing the message as if it had been
+            let err = errors?.[0]?.err || new Error('The message could not be sealed');
+            throw err;
+        }
 
         // createSeal writes the instance it actually used back into the seal options
         if (sealOpts.i > 1 && !argv.cv) {
             console.error(`warning: sealed with i=${sealOpts.i} and cv=none; a chain with i>1 only validates when cv=pass (use --cv pass)`);
         }
 
-        process.stdout.write(sealHeaders);
+        for (let warning of warnings || []) {
+            switch (warning) {
+                case 'arc-instance-gap':
+                    console.error(`warning: sealed with i=${sealOpts.i}, which does not follow the existing ARC chain`);
+                    break;
+                case 'arc-cv-instance':
+                    // covered by the message above for the default cv
+                    if (argv.cv) {
+                        console.error(`warning: cv=${argv.cv} is not valid for i=${sealOpts.i} (i=1 takes cv=none, later sets take cv=pass or cv=fail)`);
+                    }
+                    break;
+                default:
+                    console.error(`warning: ${warning}`);
+            }
+        }
+
+        process.stdout.write(Buffer.from(headers.join('\r\n') + '\r\n'));
         if (!argv.headersOnly) {
             // print full message as well
             await writeMessageBody(gatherer);
@@ -121,7 +145,8 @@ const cmd = async argv => {
 
     const opts = {
         trustReceived: true,
-        seal: signatureOpts
+        seal: signatureOpts,
+        strict: !!argv.strict
     };
 
     if (argv.clientIp) {
@@ -168,6 +193,11 @@ const cmd = async argv => {
 
     let result = await authenticate(gatherer, opts);
 
+    for (let sealError of result.arc?.sealErrors || []) {
+        // the message is printed without a seal
+        console.error(`warning: the message was not sealed: ${sealError?.err?.message || sealError?.err}`);
+    }
+
     process.stdout.write(result.headers);
     if (!argv.headersOnly) {
         // print full message as well

package/lib/commands/sign.js

@@ -68,9 +68,16 @@ const cmd = async argv => {
 
     let signResult = await dkimSign(gatherer, {
         signTime,
-        signatureData: [signatureOpts]
+        signatureData: [signatureOpts],
+        strict: !!argv.strict
     });
 
+    if (argv.verbose) {
+        for (let warning of signResult.warnings || []) {
+            console.error(`Signing warning: ${warning}`);
+        }
+    }
+
     if (signResult.errors?.length) {
         if (argv.verbose) {
             for (let error of signResult.errors) {

package/lib/commands/spf.js

@@ -32,6 +32,14 @@ const cmd = async argv => {
         opts.maxVoidCount = argv.maxVoidLookups;
     }
 
+    if (argv.strict) {
+        opts.strict = true;
+    }
+
+    if (argv.maxElapsedTime) {
+        opts.maxElapsedTime = Number(argv.maxElapsedTime);
+    }
+
     for (let key of ['sender', 'helo', 'mta']) {
         if (argv[key]) {
             opts[key] = argv[key];

package/lib/dkim/body/relaxed.js

@@ -174,9 +174,9 @@ class RelaxedHash {
 
     update(chunk, final) {
         this.byteLength += (chunk && chunk.length) || 0;
-        if (this.maxSizeReached) {
-            return;
-        }
+        // The body is canonicalized to the end even once the l= limit has been reached.
+        // Nothing past the limit is hashed (_updateBodyHash stops that), but it is counted in
+        // canonicalizedLength, which is how the unsigned content after l= is reported
 
         // Canonicalize content by applying a and b in order:
         // a.1. Ignore all whitespace at the end of lines.
@@ -279,8 +279,9 @@ class RelaxedHash {
                 this._pushBodyHash(lineNeedsFixing || chunkPart[chunkPart.length - 1] === CHAR_SPACE ? this.fixLineBuffer(chunkPart) : chunkPart);
             }
 
-            if (this.bodyHashedBytes) {
-                // terminating line break for non-empty messages
+            if (this.canonicalizedLength) {
+                // terminating line break for non-empty messages. A body with content is non-empty
+                // even when l= keeps all of it out of the hash
                 this._updateBodyHash(CRLF);
             }
         }

package/lib/dkim/body/simple.js

@@ -84,9 +84,7 @@ class SimpleHash {
         }
 
         this.byteLength += chunk.length;
-        if (this.maxSizeReached) {
-            return;
-        }
+        // keeps reading past the l= limit, see RelaxedHash.update() for why
 
         // Find the line endings at the end of the chunk. They may be the *CRLF that ends
         // the body, which digest() collapses, and a trailing <CR> may still pair up with