mailauth 6.0.0 → 7.1.0

package/lib/spf/index.js

@@ -1,24 +1,50 @@
 'use strict';
 
 const { spfVerify } = require('./spf-verify');
+const { parseIp, isValidTargetName } = require('./syntax');
 const os = require('node:os');
 const dns = require('node:dns');
 const libmime = require('libmime');
 const Joi = require('joi');
 const domainSchema = Joi.string().domain({ allowUnicode: false, tlds: false });
-const { formatAuthHeaderRow, escapeCommentValue } = require('../tools');
+const { formatAuthHeaderRow, escapeCommentValue, formatDotAtomOrQuoted, MAX_HEADER_VALUE_LENGTH, toALabel } = require('../tools');
 
 const MAX_RESOLVE_COUNT = 10;
 const MAX_VOID_COUNT = 2;
 
-const formatHeaders = result => {
-    let header = `Received-SPF: ${result.status.result}${result.status.comment ? ` (${escapeCommentValue(result.status.comment)})` : ''} client-ip=${
-        result['client-ip']
-    };`;
+/**
+ * Formats the Received-SPF header field (RFC 7208 section 9.1)
+ */
+const formatHeaders = (result, keys) => {
+    let pairs = [];
+    for (let key of ['client-ip', 'envelope-from', 'helo']) {
+        if (keys[key]) {
+            let value = formatDotAtomOrQuoted(keys[key]);
+            // a value this long can not be folded and would take the line past the 998
+            // character limit of RFC 5322 section 2.1.1, so the optional pair is left out
+            if (Buffer.byteLength(value) <= MAX_HEADER_VALUE_LENGTH) {
+                pairs.push(`${key}=${value};`);
+            }
+        }
+    }
+
+    let header = `Received-SPF: ${result.status.result}${result.status.comment ? ` (${escapeCommentValue(result.status.comment)})` : ''}${
+        pairs.length ? ` ${pairs.join(' ')}` : ''
+    }`;
 
     return libmime.foldLines(header, 160);
 };
 
+const timeLimitError = () => {
+    let err = new Error('SPF evaluation time limit exceeded');
+    err.code = 'ESPFTIMELIMIT';
+    err.spfResult = {
+        error: 'temperror',
+        text: 'SPF evaluation time limit exceeded'
+    };
+    return err;
+};
+
 /**
  * Dual-stack DNS resolver for SPF A/AAAA mechanism queries
  *
@@ -37,13 +63,17 @@ const formatHeaders = result => {
  *   - AAAA query returns: ENODATA (empty)
  *   - Result: Returns empty AAAA array (no match), but does NOT count as void
  *
+ * RFC 7208 section 4.6.4 counts the query for the client's address type only, so this is used
+ * in the default mode only. `state.clientVoid` is set if that query alone was void.
+ *
  * @param {Function} resolver - Base DNS resolver function
  * @param {String} domain - Domain to query
  * @param {Object} opts - Options object with clientIpType (4 or 6)
+ * @param {Object} [state] - Updated with the clientVoid flag
  * @returns {Promise<Array>} - Array of IP addresses matching client type
  * @throws {Error} - Throws on real DNS errors or when both A and AAAA are void
  */
-let dualStackResolver = async (resolver, domain, opts) => {
+let dualStackResolver = async (resolver, domain, opts, state) => {
     const isIPv6 = opts.clientIpType === 6;
 
     // Query both A and AAAA records in parallel for efficiency
@@ -79,6 +109,11 @@ let dualStackResolver = async (resolver, domain, opts) => {
         throw voidError;
     }
 
+    if (state && (isIPv6 ? aaaaIsVoid : aIsVoid)) {
+        // RFC 7208 would count this as a void lookup
+        state.clientVoid = true;
+    }
+
     // Return only the records matching the client's IP type
     // Empty arrays are valid (host exists but doesn't match client IP type)
     return isIPv6 ? aaaaRecords : aRecords;
@@ -96,11 +131,19 @@ let dualStackResolver = async (resolver, domain, opts) => {
  * @param {Number} maxResolveCount - Maximum DNS lookups allowed (default: 10)
  * @param {Number} maxVoidCount - Maximum void lookups allowed (default: 2)
  * @param {Boolean} ignoreFirst - If true, don't count the first DNS lookup (used for initial TXT record fetch)
+ * @param {Object} [options]
+ * @param {Boolean} [options.strict] - If true, follow RFC 7208 exactly (no dual-stack void optimization)
+ * @param {Object} [options.ctx] - Shared evaluation state, lax acceptances are added to ctx.warnings
+ * @param {Number} [options.deadline] - Timestamp after which no more queries are made
  * @returns {Function} - Rate-limited resolver function with signature: (domain, type, opts) => Promise<Array>
  */
-let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) => {
+let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst, options) => {
+    options = options || {};
+
     let resolveCount = 0;
     let voidCount = 0;
+    // void lookups as RFC 7208 counts them, without the dual-stack optimization
+    let rfcVoidCount = 0;
 
     let subResolveCounts = {};
     let firstCounted = !ignoreFirst;
@@ -108,7 +151,18 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
     maxResolveCount = maxResolveCount || MAX_RESOLVE_COUNT;
     maxVoidCount = maxVoidCount || MAX_VOID_COUNT;
 
+    let checkRfcVoidCount = () => {
+        if (rfcVoidCount > maxVoidCount && options.ctx && options.ctx.warnings) {
+            // strict mode would have returned permerror here
+            options.ctx.warnings.add('void-lookup-limit');
+        }
+    };
+
     let resolverFunc = async (domain, type, opts) => {
+        if (options.deadline && Date.now() >= options.deadline) {
+            throw timeLimitError();
+        }
+
         // Increment DNS lookup counter
         // Note: Dual-stack queries (A+AAAA) still count as 1 lookup
         if (firstCounted) {
@@ -130,7 +184,8 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
         // Validate domain name format before querying
         // This is a lenient check to pass test suites and prevent obvious invalid queries
         try {
-            if (!/^([\x20-\x2D\x2f-\x7e]+\.)+[a-z]+[a-z\-0-9]*$/i.test(domain)) {
+            // strict mode also accepts every name that follows the domain-spec rules of RFC 7208
+            if (!/^([\x20-\x2D\x2f-\x7e]+\.)+[a-z]+[a-z\-0-9]*$/i.test(domain) && !(options.strict && isValidTargetName(domain))) {
                 throw new Error('Failed to validate domain');
             }
         } catch (err) {
@@ -142,24 +197,45 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
         }
 
         // Execute DNS query with dual-stack optimization for A/AAAA queries
+        let state = {};
         try {
             // Use dual-stack resolver when:
             // 1. Query type is A or AAAA (address lookups)
             // 2. Client IP type is provided (4 for IPv4, 6 for IPv6)
+            // 3. Not in strict mode, RFC 7208 only looks at the query for the client's address type
             // This prevents single-stack hosts from being counted as void lookups
-            if (opts?.clientIpType && (type === 'A' || type === 'AAAA')) {
-                return await dualStackResolver(resolver, domain, opts);
+            let result;
+            if (!options.strict && opts?.clientIpType && (type === 'A' || type === 'AAAA')) {
+                result = await dualStackResolver(resolver, domain, opts, state);
             } else {
                 // Standard single-query resolution for other record types (TXT, MX, PTR, etc.) and A if no client info provided.
-                return await resolver(domain, type);
+                result = await resolver(domain, type);
             }
+
+            if (state.clientVoid) {
+                rfcVoidCount++;
+                checkRfcVoidCount();
+            }
+
+            return result;
         } catch (err) {
+            if (!err || typeof err !== 'object') {
+                // a custom resolver rejected with something other than an error object
+                let wrapped = new Error(`DNS error when resolving ${domain}: ${err}`);
+                wrapped.spfResult = {
+                    error: 'temperror',
+                    text: wrapped.message
+                };
+                throw wrapped;
+            }
+
             switch (err.code) {
                 case 'ENOTFOUND': // Domain does not exist
                 case 'ENODATA': {
                     // Domain exists but has no records of this type
                     // Increment void lookup counter
                     voidCount++;
+                    rfcVoidCount++;
                     if (voidCount > maxVoidCount) {
                         err.spfResult = {
                             error: 'permerror',
@@ -167,6 +243,7 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
                         };
                         throw err;
                     }
+                    checkRfcVoidCount();
                     // Return empty array to continue SPF evaluation
                     return [];
                 }
@@ -187,8 +264,27 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
                     };
                     throw err;
 
+                case 'ESPFTIMELIMIT':
+                    throw err;
+
+                case 'EBADNAME':
+                    // the resolver rejected the name (for example a label longer than 63 characters),
+                    // handled like the names that fail the format check above
+                    err.spfResult = {
+                        error: 'permerror',
+                        text: `Invalid domain ${domain}`
+                    };
+                    throw err;
+
                 default:
-                    // Unknown error - propagate as-is
+                    // Any other DNS error (SERVFAIL, connection refused, bad response, ...) is a
+                    // temporary error (RFC 7208 sections 4.4 and 5), also inside include and redirect
+                    if (!err.spfResult) {
+                        err.spfResult = {
+                            error: 'temperror',
+                            text: err.message
+                        };
+                    }
                     throw err;
             }
         }
@@ -210,6 +306,50 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
     return resolverFunc;
 };
 
+/**
+ * Wraps a DNS resolver so that each question is sent once per SPF evaluation. The lookup limits
+ * are counted by limitedResolver before it calls this, so every query still counts. Nothing
+ * mutable is handed out twice: limitedResolver writes spfResult onto the error it gets, and
+ * the MX list is sorted in place, so every caller gets its own copy of the error or the list
+ *
+ * @param {Function} resolver Base DNS resolver
+ * @returns {Function} Resolver with the same signature
+ */
+const memoizeResolver = resolver => {
+    const answers = new Map();
+
+    const copyError = err => {
+        if (!err || typeof err !== 'object') {
+            // not an error object, there is nothing on it to share
+            return err;
+        }
+        let copy = Object.assign(new Error(err.message), err);
+        copy.code = err.code;
+        if (err.spfResult && typeof err.spfResult === 'object') {
+            copy.spfResult = Object.assign({}, err.spfResult);
+        }
+        return copy;
+    };
+
+    return (name, type) => {
+        let key = `${type}:${name}`;
+        let answer = answers.get(key);
+        if (!answer) {
+            // a resolver that throws synchronously still does so, and is not cached
+            answer = Promise.resolve(resolver(name, type));
+            // failures are reported to the callers below, never as an unhandled rejection
+            answer.catch(() => false);
+            answers.set(key, answer);
+        }
+        return answer.then(
+            value => (Array.isArray(value) ? value.slice() : value),
+            err => {
+                throw copyError(err);
+            }
+        );
+    };
+};
+
 /**
  *
  * @param {Object} opts
@@ -219,30 +359,57 @@ let limitedResolver = (resolver, maxResolveCount, maxVoidCount, ignoreFirst) =>
  * @param {String} [opts.mta] Hostname of the MTA or MX server that processes the message
  * @param {String} [opts.maxResolveCount=10] Maximum DNS lookups allowed
  * @param {String} [opts.maxVoidCount=2] Maximum empty DNS lookups allowed
+ * @param {Number} [opts.maxElapsedTime] Maximum time in milliseconds for the whole evaluation, temperror if exceeded (no limit by default)
+ * @param {Boolean} [opts.strict=false] If true, follow RFC 7208 exactly instead of the lenient default
  */
 const verify = async opts => {
-    let { sender, ip, helo, mta, maxResolveCount, maxVoidCount, resolver } = opts || {};
+    let { sender, ip, helo, mta, maxResolveCount, maxVoidCount, resolver, strict, maxElapsedTime } = opts || {};
+
+    strict = !!strict;
 
     mta = mta || os.hostname();
 
+    // a null reverse-path means that the HELO identity is checked (RFC 7208 section 2.4)
+    let nullSender = !sender;
+
     sender = sender || `postmaster@${helo}`;
 
-    // convert mapped IPv6 IP addresses to IPv4
-    let mappingMatch = (ip || '').toString().match(/^[:A-F]+:((\d+\.){3}\d+)$/i);
-    if (mappingMatch) {
-        ip = mappingMatch[1];
+    // IPv4-mapped IPv6 addresses (::ffff:0:0/96, dotted or hex form) are IPv4 clients (RFC 7208 section 5),
+    // no other IPv6 address is ever treated as IPv4
+    let parsedIp = ip ? parseIp(ip) : null;
+    if (parsedIp) {
+        ip = ip.toString().trim();
+    }
+    if (parsedIp && parsedIp.kind() === 'ipv6' && parsedIp.isIPv4MappedAddress()) {
+        parsedIp = parsedIp.toIPv4Address();
+        ip = parsedIp.toString();
     }
 
-    let atPos = sender.indexOf('@');
+    // the local-part may be a quoted string that contains "@", the domain follows the last "@"
+    let atPos = sender.lastIndexOf('@');
     if (atPos < 0) {
         sender = `postmaster@${sender}`;
     } else if (atPos === 0) {
         sender = `postmaster${sender}`;
     }
+    atPos = sender.lastIndexOf('@');
+
+    let domain =
+        sender
+            .substr(atPos + 1)
+            .toLowerCase()
+            .trim() || '-';
+
+    // RFC 8616 section 4: U-labels are converted to A-labels before SPF validation, this also
+    // applies to the sender domain used in macro expansion
+    let evalSender = sender;
+    if (/[^\x00-\x7F]/.test(domain)) {
+        domain = toALabel(domain);
+        evalSender = `${sender.substr(0, atPos)}@${domain}`;
+    }
 
-    let domain = sender.split('@').pop().toLowerCase().trim() || '-';
-
-    resolver = resolver || dns.promises.resolve;
+    // one DNS query per question for the whole evaluation, includes and redirects included
+    resolver = memoizeResolver(resolver || dns.promises.resolve);
 
     let status = {
         result: 'neutral',
@@ -254,10 +421,35 @@ const verify = async opts => {
         }
     };
 
-    let verifyResolver = limitedResolver(resolver, maxResolveCount, maxVoidCount, true);
+    // shared evaluation state
+    let ctx = { warnings: new Set(), usedLocalPart: false };
+
+    let deadline = typeof maxElapsedTime === 'number' && maxElapsedTime > 0 ? Date.now() + maxElapsedTime : false;
+    let resolverOptions = { strict, ctx, deadline };
+
+    let verifyResolver = limitedResolver(resolver, maxResolveCount, maxVoidCount, true, resolverOptions);
+
+    // the explanation lookup is not counted toward the lookup limits (RFC 7208 section 4.6.4)
+    let expResolver = async (name, type) => {
+        if (deadline && Date.now() >= deadline) {
+            throw timeLimitError();
+        }
+        return await resolver(name, type);
+    };
 
     let result;
+    let timer;
     try {
+        if (!parsedIp) {
+            // <ip> is a required argument of check_host() (RFC 7208 section 4.1)
+            let err = new Error('Invalid client IP');
+            err.spfResult = {
+                error: 'temperror',
+                text: 'missing or invalid client IP address'
+            };
+            throw err;
+        }
+
         let validation = domainSchema.validate(domain);
         if (validation.error) {
             let err = validation.error;
@@ -268,18 +460,35 @@ const verify = async opts => {
             throw err;
         }
 
-        result = await spfVerify(domain, {
-            sender,
+        let evaluation = spfVerify(domain, {
+            sender: evalSender,
             ip,
             mta,
             helo,
+            strict,
+            ctx,
+            expResolver,
 
             // generate DNS handler
             resolver: verifyResolver,
 
-            // allow to create sub resolvers
-            createSubResolver: () => limitedResolver(resolver, maxResolveCount, maxVoidCount)
+            // allow to create sub resolvers. Address lookups of MX and PTR names do not count as void lookups
+            createSubResolver: subOptions =>
+                limitedResolver(resolver, maxResolveCount, subOptions && subOptions.ignoreVoid ? Infinity : maxVoidCount, false, resolverOptions)
         });
+
+        if (deadline) {
+            // RFC 7208 section 4.6.4: a limit on the elapsed time, temperror if exceeded
+            evaluation.catch(() => false);
+            result = await Promise.race([
+                evaluation,
+                new Promise((resolve, reject) => {
+                    timer = setTimeout(() => reject(timeLimitError()), Math.max(deadline - Date.now(), 0));
+                })
+            ]);
+        } else {
+            result = await evaluation;
+        }
     } catch (err) {
         if (err.spfResult) {
             result = err.spfResult;
@@ -289,6 +498,8 @@ const verify = async opts => {
                 text: err.message
             };
         }
+    } finally {
+        clearTimeout(timer);
     }
 
     if (result && typeof result === 'object') {
@@ -353,13 +564,24 @@ const verify = async opts => {
             break;
     }
 
+    if (strict) {
+        // RFC 8601 section 2.7.2: only the identity that was checked is reported, and the
+        // local-part only if the policy has provisions for it
+        status.smtp = nullSender ? { helo } : { mailfrom: ctx.usedLocalPart ? sender : sender.substr(atPos + 1) };
+    }
+
     if (result.rr) {
         response.rr = result.rr;
     }
 
     response.status = status;
-    response.header = formatHeaders(response);
-    response.info = formatAuthHeaderRow('spf', status);
+    response.header = formatHeaders(response, {
+        'client-ip': parsedIp ? ip : false,
+        // RFC 7208 section 9.1: "envelope-from" if the "MAIL FROM" identity was checked
+        'envelope-from': nullSender ? false : sender,
+        helo
+    });
+    response.info = formatAuthHeaderRow('spf', status, { strict });
 
     if (typeof response.status.comment === 'boolean') {
         delete response.status.comment;
@@ -369,6 +591,16 @@ const verify = async opts => {
         response.lookups = result.lookups;
     }
 
+    if (result.explanation && status.result === 'fail') {
+        // explanation string published by the domain owner (RFC 7208 section 6.2), third party text
+        response.explanation = result.explanation;
+    }
+
+    if (ctx.warnings.size && status.result !== 'permerror') {
+        // the default mode accepted something that strict mode would have rejected
+        response.warnings = Array.from(ctx.warnings);
+    }
+
     return response;
 };
 

package/lib/spf/macro.js

@@ -1,8 +1,19 @@
 'use strict';
 
-const net = require('net');
-const ipaddr = require('ipaddr.js');
 const os = require('node:os');
+const { parseIp } = require('./syntax');
+
+// RFC 3986 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+const urlEscape = value =>
+    Array.from(Buffer.from(value, 'utf-8'))
+        .map(byte => {
+            let chr = String.fromCharCode(byte);
+            if (/^[A-Za-z0-9\-._~]$/.test(chr)) {
+                return chr;
+            }
+            return `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+        })
+        .join('');
 
 /**
  * Renders macro into an output string.
@@ -13,20 +24,31 @@ const os = require('node:os');
  * @param {String} values.helo Client's HELO/EHLO domain
  * @param {String} [values.mta] Hostname of the MTA or MX server that processes the message
  * @param {String} [values.domain] Domain currently being evaluated by check_host(), changes on include/redirect recursion (RFC 7208 sections 5.2, 6.1)
+ * @param {String} [values.p] Validated domain name of the client IP (RFC 7208 section 7.3), "unknown" if not set
+ * @param {Object} [values.addr] `values.ip` parsed with parseIp(), if the caller already has it
  */
 const macro = (input, values) => {
     input = (input || '').toString();
 
-    let { sender, ip, helo, mta, domain } = values || {};
+    if (input.indexOf('%') < 0) {
+        // nothing to expand
+        return input;
+    }
+
+    let { sender, ip, helo, mta, domain, p, addr } = values || {};
 
     sender = (sender || '').toString();
     ip = (ip || '').toString();
     helo = (helo || '').toString();
 
-    let atPos = sender.indexOf('@');
+    // the local-part may be a quoted string that contains "@", the domain follows the last "@"
+    let atPos = sender.lastIndexOf('@');
     let senderLocal = atPos >= 0 ? sender.substr(0, atPos) : '';
     let senderDomain = atPos >= 0 ? sender.substr(atPos + 1) : sender;
-    let vStr = net.isIPv4(ip) ? 'in-addr' : net.isIPv6(ip) ? 'ip6' : '';
+
+    // the caller can pass the client IP already parsed, it is then not parsed again
+    let parsedIp = addr || parseIp(ip);
+    let vStr = parsedIp ? (parsedIp.kind() === 'ipv4' ? 'in-addr' : 'ip6') : '';
 
     return input.replace(/%%|%_|%-|%\{([^}]+)\}|%/gi, (m, c) => {
         if (m === '%') {
@@ -65,18 +87,25 @@ const macro = (input, values) => {
                 break;
 
             case 'o':
-            case 'p': // validated domain name is unsupported, instead we use the unvalidated sender domain
                 curval = senderDomain;
                 break;
 
+            case 'p':
+                // validated domain name of the client IP, resolved by the caller (RFC 7208 section 7.3)
+                curval = p || 'unknown';
+                break;
+
             case 'd':
                 // current <domain> of check_host(), not the sender domain (these only match at the top level)
                 curval = domain || senderDomain;
                 break;
 
             case 'i':
-                curval = ipaddr.parse(ip).toNormalizedString();
-                if (net.isIPv6(ip)) {
+                if (!parsedIp) {
+                    throw new Error(`Invalid IP address ${ip}`);
+                }
+                curval = parsedIp.toNormalizedString();
+                if (parsedIp.kind() === 'ipv6') {
                     curval = curval
                         .split(':')
                         .flatMap(p => {
@@ -94,11 +123,14 @@ const macro = (input, values) => {
                 break;
 
             case 'h':
-                curval = helo || `[${ipaddr.parse(ip).toString()}]`;
+                curval = helo || `[${parsedIp ? parsedIp.toString() : ip}]`;
                 break;
 
             case 'c':
-                curval = ipaddr.parse(ip).toString();
+                if (!parsedIp) {
+                    throw new Error(`Invalid IP address ${ip}`);
+                }
+                curval = parsedIp.toString();
                 break;
 
             case 'r':
@@ -134,8 +166,8 @@ const macro = (input, values) => {
             nr = parseInt(nr, 10);
         }
 
-        // find the reverse transformer
-        if (chars.length && chars[0] === 'r') {
+        // find the reverse transformer, ABNF literals are case-insensitive, so "R" is the same as "r"
+        if (chars.length && chars[0].toLowerCase() === 'r') {
             chars.shift();
             reversed = true;
         }
@@ -163,7 +195,12 @@ const macro = (input, values) => {
             }
 
             // no matter the expansion delimiter, values are joined with dots
-            return curval.join('.');
+            curval = curval.join('.');
+        }
+
+        // uppercase macros expand exactly as their lowercase equivalents, and are then URL escaped (RFC 7208 section 7.3)
+        if (macroChar !== macroChar.toLowerCase()) {
+            curval = urlEscape(curval);
         }
 
         return curval;