mailauth 7.1.1 → 7.3.0

package/lib/tools.js

@@ -13,7 +13,7 @@ const parseDkimHeaders = require('./parse-dkim-headers');
 const { parseTagList } = parseDkimHeaders;
 const tldts = require('tldts');
 const Joi = require('joi');
-const { DOMAIN_NAME } = require('./dkim/syntax');
+const { DOMAIN_NAME, HOST_NAME_CHARS } = require('./dkim/syntax');
 const base64Schema = Joi.string().base64({ paddingRequired: false });
 
 const defaultDKIMFieldNames =
@@ -33,7 +33,10 @@ const keyOrderingAS = ['i', 'a', 't', 'cv', 'd', 's', 'b'];
 
 const TLDTS_OPTS = {
     allowIcannDomains: true,
-    allowPrivateDomains: true
+    allowPrivateDomains: true,
+    // the input is a host name, not a URL. Otherwise "example.com/x.example.net" would be read
+    // as the URL of the host "example.com"
+    extractHostname: false
 };
 
 /**
@@ -68,6 +71,10 @@ const toALabel = domain => {
         .join('.');
 };
 
+// Whether a d= value only has the characters of a host name once U-labels are converted to
+// A-labels (see HOST_NAME_CHARS in lib/dkim/syntax.js)
+const isHostNameDomain = domain => HOST_NAME_CHARS.test(toALabel(String(domain)));
+
 // lower case A-label form of a domain without the root dot, for comparing domains
 const normalizeDomainName = domain =>
     toALabel((domain || '').toString().trim())
@@ -201,12 +208,51 @@ const normalizeFieldNames = fieldNames =>
 
 const defaultDKIMFieldNamesNormalized = normalizeFieldNames(defaultDKIMFieldNames);
 
+// A field name that can be written into h= although the message has no such field: RFC 5322
+// ftext without the ";" that would end the tag (RFC 6376 section 3.2)
+const OVERSIGN_FIELD_NAME = /^[\x21-\x39\x3c-\x7e]+$/;
+
+// The names a signer lists in h= more times than the message has fields of that name
+// (RFC 6376 sections 5.4.2 and 8.15), so that adding such a field breaks the signature. Only a
+// name the header list repeats is over-signed: it appears in h= as many times as it is listed,
+// or as many times as the message has it, whichever is more
+const getOversignedNames = (fieldNames, signingList) => {
+    let listed = new Map();
+    for (let casedKey of fieldNames.split(':')) {
+        casedKey = casedKey.replace(/^[ \t]+|[ \t]+$/g, '');
+        let key = lowerCaseASCII(casedKey);
+        if (!key) {
+            continue;
+        }
+        if (!listed.has(key)) {
+            listed.set(key, { casedKey, count: 0 });
+        }
+        listed.get(key).count++;
+    }
+
+    let extra = [];
+    for (let [key, { casedKey, count }] of listed) {
+        if (count < 2 || !OVERSIGN_FIELD_NAME.test(casedKey)) {
+            continue;
+        }
+        let present = signingList.filter(header => header.key === key).length;
+        for (let i = present; i < count; i++) {
+            extra.push(casedKey);
+        }
+    }
+    return extra;
+};
+
 const getSigningHeaderLines = (parsedHeaders, fieldNames, verify) => {
+    let configuredFieldNames = typeof fieldNames === 'string' ? fieldNames : false;
+
     // an h= tag is attacker controlled on inbound mail, so only the constant default list
     // is normalized ahead of time
-    fieldNames = typeof fieldNames === 'string' ? normalizeFieldNames(fieldNames) : defaultDKIMFieldNamesNormalized;
+    fieldNames = configuredFieldNames !== false ? normalizeFieldNames(configuredFieldNames) : defaultDKIMFieldNamesNormalized;
 
     let signingList = [];
+    // names listed in h= without a header field to hash for them
+    let oversigned = [];
 
     if (verify) {
         let parsedList = [].concat(parsedHeaders);
@@ -227,14 +273,36 @@ const getSigningHeaderLines = (parsedHeaders, fieldNames, verify) => {
                 signingList.push(header);
             }
         }
+
+        if (configuredFieldNames) {
+            oversigned = getOversignedNames(configuredFieldNames, signingList);
+        }
     }
 
     return {
-        keys: signingList.map(entry => entry.casedKey).join(': '),
+        keys: signingList
+            .map(entry => entry.casedKey)
+            .concat(oversigned)
+            .join(': '),
         headers: signingList
     };
 };
 
+// RFC 6376 section 2.11 dkim-quoted-printable, for the i= tag of a DKIM-Signature. Every byte
+// of the UTF-8 encoding that is not a dkim-safe-char (%x21-3A / %x3C / %x3E-7E) is written as
+// "=XX". This includes "=" itself, which a verifier would otherwise read as an escape
+const encodeDkimQuotedPrintable = value => {
+    let result = '';
+    for (let byte of Buffer.from((value || '').toString(), 'utf8')) {
+        if (byte >= 0x21 && byte <= 0x7e && byte !== 0x3b && byte !== 0x3d) {
+            result += String.fromCharCode(byte);
+        } else {
+            result += '=' + byte.toString(16).toUpperCase().padStart(2, '0');
+        }
+    }
+    return result;
+};
+
 /**
  * Generates `DKIM-Signature: ...` header for selected values
  * @param {Object} values
@@ -312,6 +380,9 @@ const formatSignatureHeaderLine = (type, values, folded) => {
                         // convert to A-label if needed
                         val = val.substr(0, atPos + 1) + toALabel(val.substr(atPos + 1));
                     }
+                    // the AUID is dkim-quoted-printable, a raw non-ASCII or "=" in it would be
+                    // read back as something else
+                    val = encodeDkimQuotedPrintable(val);
                 }
 
                 return `${key}=${val}`;
@@ -360,6 +431,8 @@ const addWarning = (list, ...items) => {
 const KEY_ERROR_COMMENTS = new Map([
     ['ENOTFOUND', 'no key'],
     ['ENODATA', 'no key'],
+    // a key record name that can not exist in the DNS, so there is no key, now or later
+    ['EBADNAME', 'no key'],
     ['EINVALIDVER', 'unknown key version'],
     ['EINVALIDTYPE', 'unknown key type'],
     ['EINVALIDVAL', 'invalid public key'],
@@ -414,6 +487,18 @@ const isBareRsaPublicKey = der => {
     return der[headerLength] === 0x02;
 };
 
+/**
+ * Whether a name can exist in the DNS (RFC 1035 section 2.3.4): no empty label, labels of at
+ * most 63 octets and a name of at most 253 octets, not counting a trailing root dot
+ *
+ * @param {String} name Domain name, with A-labels
+ * @returns {Boolean} true when the name can be looked up
+ */
+const isValidDnsName = name => {
+    name = (name || '').toString().replace(/\.$/, '');
+    return Buffer.byteLength(name) <= 253 && name.split('.').every(label => label.length && Buffer.byteLength(label) <= 63);
+};
+
 /**
  * Fetches and validates a DKIM public key record (RFC 6376 section 3.6.1, RFC 8463)
  *
@@ -434,13 +519,21 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     const strict = !!options.strict;
 
     // RFC 8616 section 3: a U-label is converted to an A-label before it is looked up
-    let list = await resolver(toALabel(name), 'TXT');
+    let lookupName = toALabel(name);
+    if (!isValidDnsName(lookupName)) {
+        // the resolver would fail with an error that looks transient, or ask for a name that
+        // can not have a record at all
+        throw keyError('Invalid key record name', 'EBADNAME');
+    }
+    let list = await resolver(lookupName, 'TXT');
+    // the record is parsed as it is, whitespace is only removed from p= (by the tag-list
+    // parser), where base64string allows FWS anywhere (RFC 6376 section 3.6.1)
     let rr =
         list &&
         []
             .concat(list[0] || [])
             .join('')
-            .replace(/\s+/g, '');
+            .trim();
 
     if (!rr) {
         throw keyError('Missing key value', 'EINVALIDVAL');
@@ -459,6 +552,18 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     let entry = parseTagList(rr, { strict });
     const tags = entry.parsed;
 
+    // The value of a k=, s= or t= tag. FWS is allowed around "=", ";" and the ":" of a list,
+    // not inside a value (RFC 6376 section 3.6.1), so strict mode reads the value as it is. The
+    // lenient mode removes the whitespace, as it always has
+    const tagValue = name => {
+        let value = typeof tags[name]?.value === 'string' ? tags[name].value : '';
+        if (/\s/.test(splitKeyList(value).join(':'))) {
+            violation(`Invalid key record syntax: whitespace in ${name}=`, 'EINVALIDVAL', 'key-syntax');
+            return value.replace(/\s+/g, '');
+        }
+        return value;
+    };
+
     if (entry.syntaxErrors.length) {
         // RFC 6376 section 6.1.2 step 5: a key record that does not adhere to the format is ignored
         violation(`Invalid key record syntax: ${entry.syntaxErrors[0]}`, 'EINVALIDVAL', 'key-syntax');
@@ -479,7 +584,8 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     // rules apply to them as well
     if (tags.v) {
         let version = (tags.v.value || '').toString();
-        if (version.toLowerCase().trim() !== 'dkim1') {
+        // the lenient mode reads "DKIM 1" as DKIM1, the exact check below marks it
+        if (version.replace(/\s+/g, '').toLowerCase() !== 'dkim1') {
             throw keyError('Unknown key version', 'EINVALIDVER', rr);
         }
 
@@ -492,7 +598,7 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     // RFC 6376 section 3.6.1 s=: "Verifiers for a given service type MUST ignore this record
     // if the appropriate type is not listed", applied in every mode, it is the key owner's choice
     if (tags.s) {
-        let services = splitKeyList(tags.s.value);
+        let services = splitKeyList(tagValue('s'));
         if (!services.includes('email') && !services.includes('*')) {
             throw keyError('Key is not meant for email', 'EINVALIDSERVICE', rr);
         }
@@ -507,7 +613,7 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
         }
     }
 
-    let declaredKeyType = tags.k ? (tags.k.value || '').toString().toLowerCase().trim() : false;
+    let declaredKeyType = tags.k ? tagValue('k').toLowerCase().trim() : false;
 
     let rawPublicKey = Buffer.from(publicKeyValue, 'base64');
     let publicKeyObj;
@@ -559,9 +665,9 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
         violation(`Unknown key type (${keyType})`, 'EINVALIDTYPE', 'key-type-inferred');
     }
 
-    if (strict && keyType === 'ed25519' && rawPublicKey.length !== 32) {
-        // RFC 8463 section 4 publishes the bare key, not a DER structure
-        throw keyError('Invalid ed25519 public key', 'EINVALIDVAL', rr);
+    if (keyType === 'ed25519' && rawPublicKey.length !== 32) {
+        // RFC 8463 section 4 publishes the bare key, not a SubjectPublicKeyInfo structure
+        violation('Invalid ed25519 public key', 'EINVALIDVAL', 'key-ed25519-spki');
     }
 
     let modulusLength = publicKeyObj.asymmetricKeyDetails.modulusLength;
@@ -571,7 +677,7 @@ const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     }
 
     // t= flags. "y" is the testing mode, "s" forbids an i= domain that is a subdomain of d=
-    let flags = splitKeyList(tags.t?.value);
+    let flags = splitKeyList(tagValue('t'));
 
     return {
         publicKey: exportedKey,
@@ -727,12 +833,21 @@ const escapePropValue = (value, strict) => {
         return value;
     }
 
+    // RFC 8601 section 1.5.2 extends domain-name to U-labels, a domain with U-labels is
+    // checked in its A-label form. The default mode quotes it, as older versions did
+    let isDomainName = domain => DOMAIN_NAME.test(domain) || (strict && NON_ASCII.test(domain) && DOMAIN_NAME.test(toALabel(domain)));
+
+    if (strict && isDomainName(value)) {
+        // the domain-name branch of pvalue, without a local-part and "@"
+        return value;
+    }
+
     let atPos = value.lastIndexOf('@');
     if (atPos >= 0) {
         let localPart = value.substring(0, atPos);
         let domain = value.substring(atPos + 1);
 
-        if (DOMAIN_NAME.test(domain)) {
+        if (isDomainName(domain)) {
             if (!localPart || DOT_ATOM_TEXT.test(localPart)) {
                 // a valid [ [ local-part ] "@" ] domain-name as it is
                 if (strict || LEGACY_UNQUOTED.test(value)) {
@@ -857,12 +972,17 @@ const formatAuthHeaderRow = (method, status, options) => {
 // RFC 6376 section 3.4.2. Only SP and HTAB are whitespace here: the line is a
 // 'binary' string, so a byte such as 0xA0 (the second byte of a UTF-8
 // non-breaking space) must not be collapsed or trimmed
+// The bytes of a header line for canonicalization. A string is a header line built here, and it
+// is written out as UTF-8, so it is hashed as the same UTF-8 bytes. A Buffer holds the bytes of
+// the message as they are
+const toLineBytes = line => (typeof line === 'string' ? Buffer.from(line) : line);
+
 const formatRelaxedLine = (line, suffix) => {
     let result =
         // a missing line is nothing to canonicalize. Optional chaining would resolve the
         // whole chain to undefined and the concatenation below would then hash the
         // 9 byte string "undefined" as if it were a header
-        (line || '')
+        (toLineBytes(line) || Buffer.alloc(0))
             .toString('binary')
             // unfold
             .replace(/\r?\n/g, '')
@@ -917,6 +1037,21 @@ const formatDomain = domain => {
     return domain.replace(/\.+$/, '');
 };
 
+// A domain as getAlignment() compares it, after formatDomain(): labels of letters, digits, "-"
+// and "_" (which the lenient mode lets through), with no empty label. Anything else, such as
+// the URL delimiters "/", "?" and "#", can not be a host name and never aligns
+const ALIGNMENT_DOMAIN = /^[a-z0-9_-]+(?:\.[a-z0-9_-]+)*$/;
+
+// the Organizational Domain of a domain as found from the Public Suffix List, or false for a
+// value that is not a host name
+const getOrgDomain = domain => {
+    domain = typeof domain === 'string' ? formatDomain(domain) : '';
+    if (!ALIGNMENT_DOMAIN.test(domain)) {
+        return false;
+    }
+    return tldts.getDomain(domain, TLDTS_OPTS) || domain;
+};
+
 const getAlignment = (fromDomain, domainList, strict) => {
     // This argument used to be an options object. Every object is truthy, so a leftover
     // { strict: false } call would otherwise mean hard strict, the opposite of what it asks for.
@@ -936,9 +1071,10 @@ const getAlignment = (fromDomain, domainList, strict) => {
 
     if (strict) {
         // strict alignment: the domains must be identical (RFC 9989 §3.2.10.2)
-        let from = formatDomain(fromDomain);
-        if (!from) {
-            // a bare root label normalizes to an empty string, which must not align with anything
+        let from = typeof fromDomain === 'string' ? formatDomain(fromDomain) : '';
+        if (!ALIGNMENT_DOMAIN.test(from)) {
+            // a bare root label normalizes to an empty string, which must not align with
+            // anything, and neither does a value that is not a host name
             return false;
         }
         for (let entry of domainList) {
@@ -950,13 +1086,12 @@ const getAlignment = (fromDomain, domainList, strict) => {
     }
 
     // relaxed alignment: the domains must share an Organizational Domain (RFC 9989 §3.2.10.1)
-    let fromOrg = formatDomain(tldts.getDomain(fromDomain, TLDTS_OPTS) || fromDomain);
+    let fromOrg = getOrgDomain(fromDomain);
     if (!fromOrg) {
         return false;
     }
     for (let entry of domainList) {
-        let entryOrg = formatDomain(tldts.getDomain(entry.domain, TLDTS_OPTS) || entry.domain);
-        if (entryOrg === fromOrg) {
+        if (getOrgDomain(entry.domain) === fromOrg) {
             return entry;
         }
     }
@@ -1221,6 +1356,8 @@ module.exports = {
     createError,
     addWarning,
     KEY_ERROR_COMMENTS,
+    isValidDnsName,
+    isBareRsaPublicKey,
 
     defaultDKIMFieldNames,
     defaultARCFieldNames,
@@ -1247,10 +1384,12 @@ module.exports = {
 
     getAlignment,
 
+    toLineBytes,
     formatRelaxedLine,
     stripSignatureValue,
     formatDomain,
     toALabel,
+    isHostNameDomain,
     normalizeDomainName,
     isSameOrSubdomain,
 

package/package.json

@@ -1,11 +1,14 @@
 {
     "name": "mailauth",
-    "version": "7.1.1",
+    "version": "7.3.0",
     "description": "Email authentication library for Node.js",
     "main": "lib/mailauth.js",
     "types": "index.d.ts",
     "scripts": {
         "test": "eslint \"lib/**/*.js\" \"test/**/*.js\" && mocha --recursive \"./test/**/*-test.js\" --reporter spec",
+        "coverage": "c8 mocha --recursive \"./test/**/*-test.js\" --reporter dot",
+        "coverage:check": "c8 check-coverage",
+        "mutation": "stryker run",
         "format": "prettier --write .",
         "build-source": "rm -rf node_modules package-lock.json && npm install && npm run licenses && rm -rf node_modules package-lock.json && npm install --production && rm -rf package-lock.json",
         "build-dist": "pkg --compress Brotli package.json && rm -rf package-lock.json && npm install && node winconf.js",
@@ -34,15 +37,18 @@
     },
     "homepage": "https://github.com/postalsys/mailauth",
     "devDependencies": {
+        "@stryker-mutator/core": "10.0.0",
+        "c8": "12.0.0",
         "chai": "4.4.1",
         "eslint": "10.12.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
-        "js-yaml": "5.4.2",
-        "license-report": "6.8.5",
+        "fast-check": "4.10.2",
+        "js-yaml": "5.4.3",
+        "license-report": "6.8.6",
         "mbox-reader": "1.2.0",
         "mocha": "12.0.3",
-        "prettier": "3.9.9",
+        "prettier": "3.9.10",
         "resedit": "3.1.0"
     },
     "dependencies": {
@@ -52,9 +58,9 @@
         "ipaddr.js": "2.5.0",
         "joi": "18.2.9",
         "libmime": "5.4.7",
-        "nodemailer": "10.0.14",
+        "nodemailer": "10.1.0",
         "punycode.js": "2.3.1",
-        "tldts": "7.4.16",
+        "tldts": "7.4.18",
         "undici": "8.11.2"
     },
     "engines": {
@@ -75,5 +81,8 @@
             "node24-win-x64"
         ],
         "outputPath": "ee-dist"
+    },
+    "overrides": {
+        "qs": "6.16.0"
     }
 }

package/stryker.config.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+    "_comment": "Opt-in mutation testing, run with `npm run mutation`. The mocha runner plugin does not support mocha 12, so every mutant runs the tests of the mutated modules through the command runner. The long mocha timeout keeps the slower instrumented code from failing tests by timeout, which would count as a killed mutant",
+    "testRunner": "command",
+    "commandRunner": {
+        "command": "npx mocha --bail --timeout 60000 --reporter dot \"test/dkim/**/*-test.js\" \"test/spf/**/*-test.js\" \"test/dmarc/**/*-test.js\" \"test/dkim2/**/*-test.js\" \"test/property/*-test.js\" test/mailauth-test.js"
+    },
+    "coverageAnalysis": "off",
+    "mutate": ["lib/dkim/body/*.js", "lib/spf/macro.js", "lib/dmarc/author-domain.js", "lib/dkim2/*.js"],
+    "reporters": ["clear-text", "progress", "html", "json"],
+    "htmlReporter": { "fileName": "reports/mutation/mutation.html" },
+    "jsonReporter": { "fileName": "reports/mutation/mutation.json" },
+    "tempDirName": ".stryker-tmp",
+    "cleanTempDir": true,
+    "timeoutMS": 60000
+}