mailauth 6.0.0 → 7.0.0

package/lib/mailauth.js

@@ -7,8 +7,8 @@ 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 { formatDomain, 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,10 +123,16 @@ const authenticate = async (input, opts) => {
     }
 
     let dmarcResult;
+    let dmarcSkipReason;
     if (!opts.disableDmarc && dkimResult?.headerFrom) {
         let dkimAligned;
-        ({ response: dmarcResult, dkimAligned } = await evaluateDmarc({
+        ({
+            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')
@@ -130,13 +143,14 @@ const authenticate = async (input, opts) => {
                     underSized: r.status.underSized
                 })),
             arcResult,
-            resolver: opts.resolver
+            resolver: opts.resolver,
+            strict: opts.strict
         }));
-        if (dmarcResult.info) {
+        if (dmarcResult?.info) {
             arHeader.push(`${libmime.foldLines(dmarcResult.info, 160)}`);
         }
 
-        if (dkimAligned) {
+        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.
@@ -157,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
         });
     }
 
@@ -165,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,
@@ -209,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 = {

package/lib/mta-sts.d.ts

@@ -2,23 +2,86 @@
 
 /// <reference types="node" />
 
-import { MTASTSOptions, MTASTSPolicy, MTASTSPolicyResult, MTASTSValidationResult } from '../index';
+import { MTASTSOptions as BaseMTASTSOptions, MTASTSPolicy, MTASTSPolicyResult as BaseMTASTSPolicyResult, MTASTSValidationResult } from '../index';
+
+/**
+ * MTA-STS options
+ */
+export interface MTASTSOptions extends BaseMTASTSOptions {
+    /**
+     * Apply the RFC 8461 rules exactly (default false).
+     *
+     * - The TXT record must match the RFC 8461 3.1 ABNF (case-sensitive `v=STSv1`, `id` of 1 to 32 letters and digits)
+     * - Only HTTP 200 is accepted and the Content-Type must be `text/plain`
+     * - Policy field names and the `mode` value are case-sensitive, `max_age` must be 1 to 10 digits and `mx` must be `["*."] Domain`
+     * - The Policy Host certificate must match through a DNS-ID subjectAltName, without CN fallback or partial-label wildcards
+     * - An expired cached policy is not applied when a fetch fails
+     *
+     * In the default lax mode these are accepted and reported in the `warnings` array of the `getPolicy` result.
+     */
+    strict?: boolean;
+
+    /**
+     * Overall time limit for the HTTPS policy request in milliseconds (default 60000).
+     * The socket idle timeout is 15 seconds or this value, whichever is smaller.
+     */
+    timeout?: number;
+
+    /**
+     * Maximum size of the policy file in bytes (default 65536). Larger responses fail with the `policy_too_large` error code.
+     */
+    maxPolicySize?: number;
+}
+
+/**
+ * Markers for input that the default lax mode accepted but `strict: true` would reject
+ *
+ * - `txt-syntax`: the TXT record does not match the RFC 8461 3.1 syntax
+ * - `http-status`: the policy was served with a 2xx status other than 200
+ * - `content-type`: the policy was not served as `text/plain`
+ * - `policy-syntax`: the policy file does not match the RFC 8461 3.2 syntax (field name or mode case, max_age format, mx pattern)
+ * - `cert-identity`: the Policy Host certificate matched only through the CN or a partial-label wildcard
+ * - `expired-cache`: an expired cached policy was returned because the policy could not be fetched
+ */
+export type MTASTSWarning = 'txt-syntax' | 'http-status' | 'content-type' | 'policy-syntax' | 'cert-identity' | 'expired-cache';
+
+/**
+ * MTA-STS policy fetch result
+ */
+export interface MTASTSPolicyResult extends BaseMTASTSPolicyResult {
+    /**
+     * Lax acceptance markers, only present when the default lax mode accepted something strict mode would reject
+     */
+    warnings?: MTASTSWarning[];
+}
+
+/**
+ * MTA-STS MX validation options
+ */
+export interface MTASTSValidateOptions {
+    /**
+     * Accepted for API consistency. The matching rules are the same in both modes.
+     */
+    strict?: boolean;
+}
 
 /**
  * Resolves MTA-STS policy ID from DNS
  *
  * @param address - Email address or domain name
  * @param opts - MTA-STS options
- * @returns Policy ID or false if not found
+ * @returns Policy ID or false if not found or not usable
+ * @throws Error on DNS errors other than NXDOMAIN/NODATA, or with code `multi_sts_records` for multiple records
  */
 export function resolvePolicy(address: string, opts?: MTASTSOptions): Promise<string | false>;
 
 /**
  * Fetches and parses MTA-STS policy file from HTTPS
  *
- * @param domain - Domain name
+ * @param domain - Domain name or email address
  * @param opts - MTA-STS options
- * @returns Parsed policy or false if not found
+ * @returns Parsed policy or false if the policy host has no address records
+ * @throws Error if the policy can not be fetched or is invalid
  */
 export function fetchPolicy(domain: string, opts?: MTASTSOptions): Promise<MTASTSPolicy | false>;
 
@@ -26,27 +89,30 @@ export function fetchPolicy(domain: string, opts?: MTASTSOptions): Promise<MTAST
  * Parses MTA-STS policy file content
  *
  * @param file - Policy file content
+ * @param opts - Only `strict` is used
  * @returns Parsed policy
  * @throws Error if policy is invalid
  */
-export function parsePolicy(file: Buffer | string): MTASTSPolicy;
+export function parsePolicy(file: Buffer | string, opts?: Pick<MTASTSOptions, 'strict'>): MTASTSPolicy;
 
 /**
- * Validates MX hostname against MTA-STS policy
+ * Validates MX hostname against MTA-STS policy.
+ * This does not look at `policy.expires`, use `getPolicy` to refresh the policy.
  *
  * @param mx - MX hostname to validate
  * @param policy - MTA-STS policy
+ * @param opts - Validation options
  * @returns Validation result
  */
-export function validateMx(mx: string, policy: MTASTSPolicy): MTASTSValidationResult;
+export function validateMx(mx: string, policy: MTASTSPolicy, opts?: MTASTSValidateOptions): MTASTSValidationResult;
 
 /**
  * Gets complete MTA-STS policy for a domain
  * Resolves DNS, fetches policy file, and handles caching
  *
- * @param domain - Domain name
- * @param knownPolicy - Currently cached policy
+ * @param domain - Domain name or email address
+ * @param knownPolicy - Currently cached policy, the `policy` value of an earlier result
  * @param opts - MTA-STS options
- * @returns Policy fetch result
+ * @returns Policy fetch result, store its `policy` value as the new cached policy
  */
-export function getPolicy(domain: string, knownPolicy?: MTASTSPolicy, opts?: MTASTSOptions): Promise<MTASTSPolicyResult>;
+export function getPolicy(domain: string, knownPolicy?: MTASTSPolicy | null, opts?: MTASTSOptions): Promise<MTASTSPolicyResult>;