mailauth 6.0.0 → 7.1.0

package/lib/dkim/header/relaxed.js

@@ -1,12 +1,12 @@
 'use strict';
 
 const { Buffer } = require('node:buffer');
-const { formatSignatureHeaderLine, formatRelaxedLine, stripSignatureValue, getCurTime } = require('../../../lib/tools');
+const { formatRelaxedLine, stripSignatureValue } = require('../../../lib/tools');
+const { buildSignatureOpts } = require('./signature-opts');
 
 // generate headers for signing
 const relaxedHeaders = (type, signingHeaderLines, options) => {
-    let { signatureHeaderLine, signingDomain, selector, algorithm, canonicalization, bodyHash, signTime, signature, instance, bodyHashedBytes, expires } =
-        options || {};
+    let { signatureHeaderLine, strict } = options || {};
     let chunks = [];
 
     for (let signedHeaderLine of signingHeaderLines.headers) {
@@ -16,48 +16,11 @@ const relaxedHeaders = (type, signingHeaderLines, options) => {
     let opts = false;
 
     if (!signatureHeaderLine) {
-        opts = {
-            a: algorithm,
-            c: canonicalization,
-            s: selector,
-            d: signingDomain,
-            h: signingHeaderLines.keys,
-            bh: bodyHash
-        };
-
-        if (typeof bodyHashedBytes === 'number') {
-            opts.l = bodyHashedBytes;
-        }
-
-        if (instance) {
-            // ARC only
-            opts.i = instance;
-        }
-
-        // The same opts object formats the line that gets signed here and, once the
-        // signature exists, the line that is emitted. Leaving t= out of it lets
-        // formatSignatureHeaderLine read the clock again for the second one, and a second
-        // boundary falling between the two reads signs one timestamp and publishes another
-        opts.t = Math.floor(getCurTime(signTime).getTime() / 1000);
-
-        if (expires) {
-            opts.x = Math.floor(getCurTime(expires).getTime() / 1000);
-        }
-
-        signatureHeaderLine = formatSignatureHeaderLine(
-            type,
-            Object.assign(
-                {
-                    // make sure that b= always has a value, otherwise folding would be different
-                    b: signature || 'a'.repeat(73)
-                },
-                opts
-            ),
-            true
-        );
+        ({ opts, signatureHeaderLine } = buildSignatureOpts(type, signingHeaderLines, options));
     }
 
-    chunks.push(stripSignatureValue(formatRelaxedLine(signatureHeaderLine)));
+    // the strict mode reads the tag names of a signature header case-sensitively
+    chunks.push(stripSignatureValue(formatRelaxedLine(signatureHeaderLine), strict));
 
     return { canonicalizedHeader: Buffer.concat(chunks), signatureHeaderLine, dkimHeaderOpts: opts };
 };

package/lib/dkim/header/signature-opts.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { formatSignatureHeaderLine, getCurTime } = require('../../tools');
+
+/**
+ * Builds the tags of a signature header that is being created, and the header line that the
+ * header canonicalization hashes for it. Shared by the relaxed and the simple canonicalization.
+ *
+ * @param {String} type 'DKIM', 'ARC' or 'AS'
+ * @param {Object} signingHeaderLines { keys } as returned by getSigningHeaderLines()
+ * @param {Object} options The options of the canonicalization
+ * @returns {Object} { opts, signatureHeaderLine }
+ */
+const buildSignatureOpts = (type, signingHeaderLines, options) => {
+    let {
+        signingDomain,
+        selector,
+        algorithm,
+        canonicalization,
+        bodyHash,
+        signTime,
+        signature,
+        instance,
+        identity,
+        bodyHashedBytes,
+        expires,
+        timestamp,
+        expiration
+    } = options || {};
+
+    let opts = {
+        a: algorithm,
+        c: canonicalization,
+        s: selector,
+        d: signingDomain,
+        h: signingHeaderLines.keys,
+        bh: bodyHash
+    };
+
+    if (typeof bodyHashedBytes === 'number') {
+        opts.l = bodyHashedBytes;
+    }
+
+    if (instance && type === 'ARC') {
+        // ARC only, the i= of an ARC-Message-Signature is the instance number
+        opts.i = instance;
+    } else if (identity && type === 'DKIM') {
+        // DKIM only, the i= of a DKIM-Signature is the AUID
+        opts.i = identity;
+    }
+
+    // The same opts object formats the line that gets signed here and, once the
+    // signature exists, the line that is emitted. Leaving t= out of it lets
+    // formatSignatureHeaderLine read the clock again for the second one, and a second
+    // boundary falling between the two reads signs one timestamp and publishes another.
+    // `timestamp` and `expiration` are the values the signer already validated, false
+    // leaves the tag out (an explicit null keeps formatSignatureHeaderLine from adding
+    // a t= of its own). Callers that do not pass them get the values from signTime and
+    // expires
+    if (typeof timestamp === 'number' || timestamp === false) {
+        opts.t = timestamp === false ? null : timestamp;
+    } else {
+        opts.t = Math.floor(getCurTime(signTime).getTime() / 1000);
+    }
+
+    if (typeof expiration === 'number') {
+        opts.x = expiration;
+    } else if (expiration !== false && expires) {
+        opts.x = Math.floor(getCurTime(expires).getTime() / 1000);
+    }
+
+    let signatureHeaderLine = formatSignatureHeaderLine(
+        type,
+        Object.assign(
+            {
+                // make sure that b= always has a value, otherwise folding would be different
+                b: signature || 'a'.repeat(73)
+            },
+            opts
+        ),
+        true
+    );
+
+    return { opts, signatureHeaderLine };
+};
+
+module.exports = { buildSignatureOpts };

package/lib/dkim/header/simple.js

@@ -1,14 +1,14 @@
 'use strict';
 
 const { Buffer } = require('node:buffer');
-const { formatSignatureHeaderLine, stripSignatureValue, getCurTime } = require('../../../lib/tools');
+const { stripSignatureValue } = require('../../../lib/tools');
+const { buildSignatureOpts } = require('./signature-opts');
 
 const formatSimpleLine = (line, suffix) => Buffer.from(line.toString('binary') + (suffix ? suffix : ''), 'binary');
 
 // generate headers for signing
 const simpleHeaders = (type, signingHeaderLines, options) => {
-    let { signatureHeaderLine, signingDomain, selector, algorithm, canonicalization, bodyHash, signTime, signature, instance, bodyHashedBytes, expires } =
-        options || {};
+    let { signatureHeaderLine, strict } = options || {};
     let chunks = [];
 
     for (let signedHeaderLine of signingHeaderLines.headers) {
@@ -18,48 +18,11 @@ const simpleHeaders = (type, signingHeaderLines, options) => {
     let opts = false;
 
     if (!signatureHeaderLine) {
-        opts = {
-            a: algorithm,
-            c: canonicalization,
-            s: selector,
-            d: signingDomain,
-            h: signingHeaderLines.keys,
-            bh: bodyHash
-        };
-
-        if (typeof bodyHashedBytes === 'number') {
-            opts.l = bodyHashedBytes;
-        }
-
-        if (instance) {
-            // ARC only (should never happen thoug as simple algo is not allowed)
-            opts.i = instance;
-        }
-
-        // The same opts object formats the line that gets signed here and, once the
-        // signature exists, the line that is emitted. Leaving t= out of it lets
-        // formatSignatureHeaderLine read the clock again for the second one, and a second
-        // boundary falling between the two reads signs one timestamp and publishes another
-        opts.t = Math.floor(getCurTime(signTime).getTime() / 1000);
-
-        if (expires) {
-            opts.x = Math.floor(getCurTime(expires).getTime() / 1000);
-        }
-
-        signatureHeaderLine = formatSignatureHeaderLine(
-            type,
-            Object.assign(
-                {
-                    // make sure that b= has a value, otherwise folding would be different
-                    b: signature || 'a'.repeat(73)
-                },
-                opts
-            ),
-            true
-        );
+        ({ opts, signatureHeaderLine } = buildSignatureOpts(type, signingHeaderLines, options));
     }
 
-    chunks.push(stripSignatureValue(formatSimpleLine(signatureHeaderLine)));
+    // the strict mode reads the tag names of a signature header case-sensitively
+    chunks.push(stripSignatureValue(formatSimpleLine(signatureHeaderLine), strict));
 
     return { canonicalizedHeader: Buffer.concat(chunks), signatureHeaderLine, dkimHeaderOpts: opts };
 };

package/lib/dkim/message-parser.js

@@ -20,6 +20,8 @@ class MessageParser extends Writable {
 
         this.state = 'header';
         this.stateBytes = [];
+        // bytes of the header section seen so far
+        this.headerBytes = 0;
 
         this.headers = false;
         this.headerChunks = [];
@@ -61,12 +63,22 @@ class MessageParser extends Writable {
                 if (this.stateBytes.length > 4) {
                     this.stateBytes = this.stateBytes.slice(-4);
                 }
+                this.headerBytes++;
 
                 let b0 = this.stateBytes[this.stateBytes.length - 1];
                 let b1 = this.stateBytes.length > 1 && this.stateBytes[this.stateBytes.length - 2];
                 let b2 = this.stateBytes.length > 2 && this.stateBytes[this.stateBytes.length - 3];
 
-                if (b0 === 0x0a && (b1 === 0x0a || (b1 === 0x0d && b2 === 0x0a))) {
+                if (
+                    b0 === 0x0a &&
+                    (b1 === 0x0a ||
+                        (b1 === 0x0d && b2 === 0x0a) ||
+                        // RFC 5322 section 2.1: an empty line ends the header section, and when
+                        // the very first line is empty the header section is empty. Everything
+                        // after it is body, even if it looks like header fields
+                        this.headerBytes === 1 ||
+                        (this.headerBytes === 2 && b1 === 0x0d))
+                ) {
                     // found header ending
                     if (i === chunk.length - 1) {
                         //end of chunk
@@ -88,13 +100,14 @@ class MessageParser extends Writable {
         await this.nextChunk(chunk);
     }
 
+    // Rewrites every bare <LF> to <CRLF>. `lastByte` has to follow every byte, the <LF>s
+    // included: an <LF> directly after a <CRLF> is a bare one too, and it was left as it was
+    // when only the other bytes were tracked
     *ensureLinebreaks(input) {
         let pos = 0;
         for (let i = 0; i < input.length; i++) {
             let c = input[i];
-            if (c !== 0x0a) {
-                this.lastByte = c;
-            } else if (this.lastByte !== 0x0d) {
+            if (c === 0x0a && this.lastByte !== 0x0d) {
                 // emit line break
                 let buf;
                 if (i === 0 || pos === i) {
@@ -106,6 +119,7 @@ class MessageParser extends Writable {
 
                 pos = i + 1;
             }
+            this.lastByte = c;
         }
         if (pos === 0) {
             yield input;

package/lib/dkim/sign.d.ts

@@ -3,31 +3,37 @@
 /// <reference types="node" />
 
 import { Transform } from 'stream';
-import { MessageInput, DKIMSignOptions, DKIMSignResult } from '../../index';
+import { MessageInput, DKIMSignOptions, DKIMSignResult, DKIMSignError, DKIMSignWarning } from '../../index';
 
 /**
  * Signs an email message with DKIM signature(s)
  *
  * @param input - RFC822 formatted message (stream, buffer, or string)
- * @param options - DKIM signing options
- * @returns DKIM signature header(s) and any errors
+ * @param options - DKIM signing options, including `strict`
+ * @returns DKIM signature header(s), an empty string if none was created, plus errors and warnings
  */
 export function dkimSign(input: MessageInput, options: DKIMSignOptions): Promise<DKIMSignResult>;
 
 /**
  * Transform stream for DKIM signing
- * Prepends DKIM-Signature header to the message stream
+ * Prepends the DKIM-Signature header(s) to the message stream. When no signature could be
+ * created the message is passed through unchanged
  */
 export class DkimSignStream extends Transform {
     /**
      * Creates a DKIM signing stream
      *
-     * @param options - DKIM signing options
+     * @param options - DKIM signing options, including `strict`
      */
     constructor(options: DKIMSignOptions);
 
     /**
-     * Any errors encountered during signing
+     * The signatures that could not be created, set when the stream ends
      */
-    errors: Error[] | null;
+    errors: DKIMSignError[] | null;
+
+    /**
+     * What was signed although strict mode would have refused it, set when the stream ends
+     */
+    warnings: DKIMSignWarning[] | null;
 }

package/lib/dkim/sign.js

@@ -3,12 +3,23 @@
 const { writeToStream } = require('../../lib/tools');
 const { DkimSigner } = require('./dkim-signer');
 const { Transform } = require('node:stream');
+const { Buffer } = require('node:buffer');
+
+// The DKIM-Signature header lines to prepend to the message, each ending with a CRLF. An
+// empty string when no signature was created: a lone CRLF in front of the message would be
+// the empty line that ends the header section, and turn every header of it into body
+const formatSignatures = signatureHeaders => (signatureHeaders.length ? signatureHeaders.join('\r\n') + '\r\n' : '');
 
 const dkimSign = async (input, options) => {
     let dkimSigner = new DkimSigner(options);
     await writeToStream(dkimSigner, input);
 
-    return { signatures: dkimSigner.signatureHeaders.join('\r\n') + '\r\n', arc: dkimSigner.arc, errors: dkimSigner.errors };
+    return {
+        signatures: formatSignatures(dkimSigner.signatureHeaders),
+        arc: dkimSigner.arc,
+        errors: dkimSigner.errors,
+        warnings: dkimSigner.warnings
+    };
 };
 
 class DkimSignStream extends Transform {
@@ -20,6 +31,7 @@ class DkimSignStream extends Transform {
         this.chunklen = 0;
 
         this.errors = null;
+        this.warnings = null;
 
         this.finished = false;
         this.finishCb = null;
@@ -40,8 +52,12 @@ class DkimSignStream extends Transform {
         this.finishCb = null;
 
         this.errors = this.signer.errors;
+        this.warnings = this.signer.warnings;
 
-        this.push(Buffer.from(this.signer.signatureHeaders.join('\r\n') + '\r\n'));
+        let signatures = formatSignatures(this.signer.signatureHeaders);
+        if (signatures) {
+            this.push(Buffer.from(signatures));
+        }
         this.push(Buffer.concat(this.chunks, this.chunklen));
         done();
     }

package/lib/dkim/syntax.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Grammar shared by the DKIM and ARC signers and verifiers. ARC reuses the DKIM tag syntax
+// (RFC 8617 section 4.1), so both read these from here. This module requires nothing, so
+// that lib/tools.js can use it as well.
+
+// RFC 6376 section 3.5 sub-domain
+const DOMAIN_LABEL = '[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?';
+// domain-name = sub-domain 1*("." sub-domain)
+const DOMAIN_NAME = new RegExp(`^${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})+$`);
+// selector = sub-domain *("." sub-domain)
+const SELECTOR = new RegExp(`^${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*$`);
+// sig-t-tag and sig-x-tag are 1*12DIGIT, sig-l-tag is 1*76DIGIT
+const TIMESTAMP = /^[0-9]{1,12}$/;
+const BODY_LENGTH = /^[0-9]{1,76}$/;
+
+// RFC 8617 section 4.2.1: instance values range from 1 to 50
+const MAX_ARC_INSTANCE = 50;
+
+// the header fields of an ARC set (RFC 8617 section 4.1)
+const ARC_HEADER_KEYS = ['arc-seal', 'arc-message-signature', 'arc-authentication-results'];
+
+module.exports = {
+    DOMAIN_LABEL,
+    DOMAIN_NAME,
+    SELECTOR,
+    TIMESTAMP,
+    BODY_LENGTH,
+    MAX_ARC_INSTANCE,
+    ARC_HEADER_KEYS
+};

package/lib/dkim/verify.js

@@ -10,6 +10,7 @@ const dkimVerify = async (input, options) => {
     const result = {
         //headers: dkimVerifier.headers,
         headerFrom: dkimVerifier.headerFrom,
+        fromFields: dkimVerifier.fromFields,
         envelopeFrom: dkimVerifier.envelopeFrom,
         results: dkimVerifier.results
     };

package/lib/dmarc/author-domain.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const { formatDomain, toALabel } = require('../tools');
+
+// Characters that can not appear in a domain name taken from an address. Anything like this
+// means the address was malformed and the text after the "@" is not a domain.
+const INVALID_DOMAIN_CHARS = /[\s"<>(),;:\\@[\]]/;
+
+// A domain literal (RFC 5322 3.4.1). It is kept as is, it can not publish a DMARC record.
+const DOMAIN_LITERAL = /^\[[^[\]\\]*\]$/;
+
+// Removes an obsolete source route (RFC 5322 4.4 obs-angle-addr), as in "@relay.example:ceo@bank.example",
+// where the route ends with the first ":" that is not inside a domain literal
+const stripRoute = address => {
+    if (address.charAt(0) !== '@') {
+        return address;
+    }
+    let inLiteral = false;
+    for (let i = 1; i < address.length; i++) {
+        let c = address.charAt(i);
+        if (c === '[') {
+            inLiteral = true;
+        } else if (c === ']') {
+            inLiteral = false;
+        } else if (c === ':' && !inLiteral) {
+            return address.slice(i + 1);
+        }
+    }
+    return address;
+};
+
+// Returns the positions of the "@" signs that separate a local-part from a domain. An "@" inside
+// a quoted string of the local-part (RFC 5322 3.2.4) or inside a domain literal does not count.
+// With an unterminated quoted string the quotes are not honored, so that the "@" of an address
+// such as '"ceo@bank.example' still counts and the domain the reader sees is not dropped.
+const findSeparators = (address, honorQuotes) => {
+    let positions = [];
+    let inQuote = false;
+    let escaped = false;
+    let inLiteral = false;
+
+    for (let i = 0; i < address.length; i++) {
+        let c = address.charAt(i);
+        if (inQuote) {
+            if (escaped) {
+                escaped = false;
+            } else if (c === '\\') {
+                escaped = true;
+            } else if (c === '"') {
+                inQuote = false;
+            }
+            continue;
+        }
+        if (inLiteral) {
+            if (c === ']') {
+                inLiteral = false;
+            }
+            continue;
+        }
+        if (c === '"' && honorQuotes && !positions.length) {
+            inQuote = true;
+        } else if (c === '[' && positions.length) {
+            inLiteral = true;
+        } else if (c === '@') {
+            positions.push(i);
+        }
+    }
+
+    if (inQuote) {
+        return findSeparators(address, false);
+    }
+
+    return positions;
+};
+
+// Normalizes the domain part of an address. Returns { domain, authorDomain } or null when it is
+// not a domain. "domain" is lower case and an A-label (RFC 9989 5.3.1), "authorDomain" also has
+// the trailing root dot removed and is the name that is queried and compared.
+const normalizeDomain = value => {
+    let domain = (value || '').trim().toLowerCase();
+    if (!domain) {
+        return null;
+    }
+
+    if (!DOMAIN_LITERAL.test(domain)) {
+        if (INVALID_DOMAIN_CHARS.test(domain)) {
+            return null;
+        }
+        domain = toALabel(domain);
+    }
+
+    let authorDomain = formatDomain(domain);
+    if (!authorDomain) {
+        // "user@." has no domain name, only the root
+        return null;
+    }
+
+    return { domain, authorDomain };
+};
+
+// Returns the normalized domains found in one address. A valid addr-spec has one domain, the text
+// after the "@" that ends the local-part. An address with more than one "@" outside a quoted string
+// is malformed and every candidate is returned, so that it counts as more than one Author Domain.
+const getAddressDomains = address => {
+    if (typeof address !== 'string') {
+        return [];
+    }
+
+    address = address.trim();
+
+    if (address.indexOf('@') < 0) {
+        // not an address, but dmarc() has always accepted a bare domain name here
+        let entry = normalizeDomain(address);
+        return entry ? [entry] : [];
+    }
+
+    address = stripRoute(address);
+
+    let positions = findSeparators(address, true);
+    let domains = [];
+    for (let i = 0; i < positions.length; i++) {
+        let entry = normalizeDomain(address.slice(positions[i] + 1, i + 1 < positions.length ? positions[i + 1] : address.length));
+        if (entry) {
+            domains.push(entry);
+        }
+    }
+
+    return domains;
+};
+
+// Extracts the Author Domain from the RFC5322.From addresses (RFC 9989 5.3.1). Several mailboxes
+// are fine as long as they all use the same domain. Returns
+//   { domain, authorDomain, mailboxes } when there is exactly one Author Domain, or
+//   { reason, domains, mailboxes } when DMARC validation is not possible, where "reason" is
+//   "no-author-domain", "multiple-author-domains", "invalid-author-domain" or
+//   "multiple-from-fields".
+// "fromFields" is the number of From header fields the addresses came from, if known. RFC 5322
+// allows only one, and with several the DKIM signature can cover a different field than the one
+// a mail client shows, so their addresses are not merged into one Author Domain.
+const getAuthorDomain = (headerFrom, fromFields) => {
+    let addresses = [].concat(headerFrom === undefined || headerFrom === null ? [] : headerFrom);
+
+    let found = new Map();
+    let invalid = false;
+    for (let address of addresses) {
+        let entries = getAddressDomains(address);
+        if (!entries.length) {
+            // a mailbox without a usable domain is not skipped, the domain a reader sees for it
+            // is unknown, so the Author Domain can not be determined
+            invalid = true;
+        }
+        for (let entry of entries) {
+            if (!found.has(entry.authorDomain)) {
+                found.set(entry.authorDomain, entry);
+            }
+        }
+    }
+
+    let mailboxes = addresses.length;
+
+    if (fromFields > 1) {
+        return { reason: 'multiple-from-fields', domains: Array.from(found.keys()), mailboxes };
+    }
+
+    if (invalid && found.size) {
+        return { reason: 'invalid-author-domain', domains: Array.from(found.keys()), mailboxes };
+    }
+
+    if (found.size === 1) {
+        let [entry] = found.values();
+        return { domain: entry.domain, authorDomain: entry.authorDomain, mailboxes };
+    }
+
+    return {
+        reason: found.size ? 'multiple-author-domains' : 'no-author-domain',
+        domains: Array.from(found.keys()),
+        mailboxes
+    };
+};
+
+module.exports = { getAuthorDomain, getAddressDomains };