mailauth 7.1.1 → 7.3.0

package/lib/dkim/dkim-verifier.js

@@ -8,28 +8,34 @@ const {
     getAlignment,
     getCurTime,
     toALabel,
+    isHostNameDomain,
     normalizeDomainName,
     isSameOrSubdomain,
     addWarning,
     KEY_ERROR_COMMENTS,
+    isValidDnsName,
     splitAlgorithm,
     isSupportedAlgorithm,
     createKeyCache
 } = require('../../lib/tools');
-const { DOMAIN_NAME, SELECTOR, TIMESTAMP, BODY_LENGTH } = require('./syntax');
+const { DOMAIN_NAME, SELECTOR, LOCAL_PART, TIMESTAMP, BODY_LENGTH } = require('./syntax');
 const { MessageParser } = require('./message-parser');
 const { dkimBody } = require('./body');
 const { generateCanonicalizedHeader } = require('./header');
-const { getARChain } = require('../arc');
+const { getARChain, getHighestArcInstance } = require('../arc');
 const addressparser = require('nodemailer/lib/addressparser');
+const { parseFromHeader, getAuthorDomain } = require('../dmarc/author-domain');
 const crypto = require('node:crypto');
 const libmime = require('libmime');
 
 // RFC 6376 section 3.5 syntax, used by the strict mode
 // sig-a-tag-alg = sig-a-tag-k "-" sig-a-tag-h, both ALPHA *(ALPHA / DIGIT)
 const ALGORITHM = /^[A-Za-z][A-Za-z0-9]*-[A-Za-z][A-Za-z0-9]*$/;
-// RFC 5322 dot-atom-text with the UTF-8 of RFC 6531, or a quoted-string, for the i= local-part
-const LOCAL_PART = /^(?:(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+(?:\.(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+)*|"(?:[^"\\\r\n]|\\.)*")$/;
+
+// sig-c-tag-alg is "simple", "relaxed" or a hyphenated-word, sig-c-tag one or two of them
+// separated by "/" (RFC 6376 section 3.5). An empty c= is not an omitted one (section 3.2)
+const C_TAG_ALG = '[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
+const CANONICALIZATION = new RegExp(`^${C_TAG_ALG}(?:/${C_TAG_ALG})?$`);
 
 // Required tags of a DKIM-Signature (RFC 6376 section 3.5)
 const REQUIRED_DKIM_TAGS = ['v', 'a', 'b', 'bh', 'd', 'h', 's'];
@@ -73,6 +79,10 @@ class DkimVerifier extends MessageParser {
 
         this.headerFrom = [];
         this.fromFields = 0;
+        // "valid", "lax" or "invalid", see parseFromHeader
+        this.fromSyntax = 'valid';
+        // the Author Domain result of getAuthorDomain, set when there is a From address
+        this.author = false;
         this.envelopeFrom = false;
 
         // ARC verification info, `warnings` lists what the lenient mode accepted in the chain
@@ -83,8 +93,9 @@ class DkimVerifier extends MessageParser {
         this.keyCache = createKeyCache(this.resolver);
         Object.defineProperty(this.arc, 'keyCache', { value: this.keyCache, enumerable: false, configurable: true, writable: true });
 
-        // should we also seal this message using ARC
-        this.seal = this.options.seal;
+        // should we also seal this message using ARC. A copy, so the body hash stored on it
+        // below never ends up on the caller's object, which may be shared by concurrent calls
+        this.seal = this.options.seal ? Object.assign({}, this.options.seal) : false;
 
         if (this.seal) {
             // calculate body hash for the seal
@@ -106,6 +117,9 @@ class DkimVerifier extends MessageParser {
         } catch (err) {
             this.arc.error = err;
         }
+        // the cv= of the newest ARC-Seal in the header fields, also when the chain could not be
+        // parsed. arc() uses it to decide whether a failed chain is sealed with cv=fail
+        this.arc.latestCv = getHighestArcInstance(headers).latestCv;
 
         this.signatureHeaders = headers.parsed
             .filter(h => h.key === 'dkim-signature')
@@ -125,19 +139,22 @@ class DkimVerifier extends MessageParser {
             if (splitterPos >= 0) {
                 fromHeader = fromHeader.substr(splitterPos + 1);
             }
-            let from = addressparser(fromHeader.trim());
-            for (let addr of from) {
-                // RFC 6854 allows a group in From, and the mailboxes of the group are authors
-                // like any other. Leaving them out would leave DMARC without an Author Domain
-                for (let mailbox of [].concat(addr?.group || addr || [])) {
-                    if (mailbox && mailbox.address) {
-                        // the full addr-spec, the domain is what follows its last "@"
-                        this.headerFrom.push(mailbox.address);
-                    }
-                }
+            // the full addr-specs, including the mailboxes of a group (RFC 6854). A general
+            // purpose address parser guesses at malformed input, which could hand DMARC a domain
+            // that is not the one a reader sees, so the RFC 5322 grammar is followed instead
+            let { addresses, syntax } = parseFromHeader(fromHeader);
+            this.headerFrom.push(...addresses);
+            if (syntax === 'invalid' || this.fromSyntax === 'valid') {
+                this.fromSyntax = syntax;
             }
         }
 
+        if (this.headerFrom.length) {
+            // the same Author Domain rules as the DMARC check: a From header field that does
+            // not yield a single Author Domain aligns with no signature
+            this.author = getAuthorDomain(this.headerFrom, this.fromFields, { fromSyntax: this.fromSyntax, strict: this.strict });
+        }
+
         if (this.options.sender) {
             let returnPath = addressparser(this.options.sender);
             this.envelopeFrom = returnPath.length && returnPath[0].address ? returnPath[0].address : false;
@@ -258,9 +275,12 @@ class DkimVerifier extends MessageParser {
         signatureHeader.algorithm = (parsed.a?.value || '').toString();
         Object.assign(signatureHeader, splitAlgorithm(signatureHeader.algorithm));
 
-        signatureHeader.canonicalization = (parsed.c?.value || '').toString();
-        signatureHeader.headerCanon = signatureHeader.canonicalization.split('/').shift().toLowerCase().trim() || 'simple';
-        signatureHeader.bodyCanon = getBodyCanon(signatureHeader.canonicalization);
+        let canonicalization = (parsed.c?.value || '').toString();
+        signatureHeader.headerCanon = canonicalization.split('/').shift().toLowerCase().trim() || 'simple';
+        signatureHeader.bodyCanon = getBodyCanon(canonicalization);
+        // the canonicalization as read here, for the header canonicalizer. The c= text itself
+        // can be malformed, "/relaxed" has no header part
+        signatureHeader.canonicalization = `${signatureHeader.headerCanon}/${signatureHeader.bodyCanon}`;
 
         signatureHeader.signingDomain = (parsed.d?.value || '').toString();
         signatureHeader.selector = (parsed.s?.value || '').toString();
@@ -331,12 +351,31 @@ class DkimVerifier extends MessageParser {
                 return;
             }
 
+            // the lenient mode reads a missing part as "simple" and ignores a third one
+            let canonError = parsed.c && !CANONICALIZATION.test((rawTags.get('c') || '').replace(/[ \t\r\n]+/g, ''));
+            if (canonError && violation('signature syntax error', 'tag-syntax')) {
+                return;
+            }
+
             // "This list MUST NOT be empty", the From check below covers the lenient mode
             if (parsed.h && !normalizeFieldList(parsed.h.value).length && violation('signature syntax error')) {
                 return;
             }
 
-            let invalidNames = !DOMAIN_NAME.test(toALabel(signatureHeader.signingDomain)) || !SELECTOR.test(toALabel(signatureHeader.selector));
+            // toALabel converts each label on its own, so these also make up the key record name
+            let signingDomainALabel = toALabel(signatureHeader.signingDomain);
+            let selectorALabel = toALabel(signatureHeader.selector);
+            if (!isHostNameDomain(signingDomainALabel)) {
+                signatureHeader.invalid = 'signature syntax error';
+                return;
+            }
+
+            // DOMAIN_NAME limits the length of each label, the key record name has to fit in
+            // the 253 octets of a DNS name as well
+            let invalidNames =
+                !DOMAIN_NAME.test(signingDomainALabel) ||
+                !SELECTOR.test(selectorALabel) ||
+                !isValidDnsName(`${selectorALabel}._domainkey.${signingDomainALabel}`);
             if (invalidNames && violation('signature syntax error', 'tag-syntax')) {
                 return;
             }
@@ -467,6 +506,7 @@ class DkimVerifier extends MessageParser {
      * @returns {Object} Signature result
      */
     async verifySignature(signatureHeader, fallback) {
+        // the canonicalization as prepareSignature() read it
         const canonicalization = fallback ? signatureHeader.fallbackCanonicalization : signatureHeader.canonicalization;
         const bodyHashKey = fallback ? signatureHeader.fallbackBodyHashKey : signatureHeader.bodyHashKey;
 
@@ -493,8 +533,8 @@ class DkimVerifier extends MessageParser {
             header: this.getStatusHeader(signatureHeader)
         };
 
-        if (signatureHeader.type === 'DKIM' && this.headerFrom?.length) {
-            status.aligned = getAlignment(this.headerFrom[0].split('@').pop(), [signatureHeader.signingDomain])?.domain || false;
+        if (signatureHeader.type === 'DKIM' && this.author) {
+            status.aligned = (this.author.authorDomain && getAlignment(this.author.authorDomain, [signatureHeader.signingDomain])?.domain) || false;
         }
 
         const bodyHasher = this.bodyHashes.get(bodyHashKey);
@@ -503,11 +543,22 @@ class DkimVerifier extends MessageParser {
 
         const warnings = [].concat(signatureHeader.warnings || []);
 
-        if (signatureHeader.invalid) {
+        // RFC 6376 section 3.5 l=: "This value MUST NOT be larger than the actual number of
+        // octets in the canonicalized message body"
+        let invalidBodyLength =
+            signatureHeader.type === 'DKIM' &&
+            typeof signatureHeader.maxBodyLength === 'number' &&
+            typeof bodyHasher?.canonicalizedLength === 'number' &&
+            signatureHeader.maxBodyLength > bodyHasher.canonicalizedLength;
+        if (invalidBodyLength && !this.strict) {
+            addWarning(warnings, 'tag-syntax');
+        }
+
+        if (signatureHeader.invalid || (invalidBodyLength && this.strict)) {
             // RFC 6376 section 6.1.1 PERMFAIL, reported as neutral, which RFC 8601 section
             // 2.7.1 uses for a signature with syntax errors. The key is not looked up
             status.result = 'neutral';
-            status.comment = signatureHeader.invalid;
+            status.comment = signatureHeader.invalid || 'signature syntax error';
         } else if (signatureHeader.parsed?.bh?.value !== bodyHash) {
             // RFC 6376 section 6.1.3 step 3 is a PERMFAIL, which RFC 8601 reports as "fail".
             // The lenient mode keeps reporting neutral, as it always has
@@ -542,9 +593,10 @@ class DkimVerifier extends MessageParser {
                 }
 
                 let keyError = false;
-                if (this.strict && res?.keyType && res.keyType !== signatureHeader.signAlgo) {
-                    // RFC 6376 section 6.1.2 step 8. The lenient mode lets the crypto library
-                    // report the mismatch, as it always has
+                if (res?.keyType && res.keyType !== signatureHeader.signAlgo) {
+                    // RFC 6376 section 6.1.2 step 8, in every mode. The crypto library does not
+                    // catch every mismatch: an RSA key verifies a PKCS#1 v1.5 signature over the
+                    // digest that an ed25519-sha256 signature is made over
                     keyError = 'inappropriate key algorithm';
                 } else if (
                     res?.flags?.includes('s') &&

package/lib/dkim/header/simple.js

@@ -1,10 +1,10 @@
 'use strict';
 
 const { Buffer } = require('node:buffer');
-const { stripSignatureValue } = require('../../../lib/tools');
+const { stripSignatureValue, toLineBytes } = require('../../../lib/tools');
 const { buildSignatureOpts } = require('./signature-opts');
 
-const formatSimpleLine = (line, suffix) => Buffer.from(line.toString('binary') + (suffix ? suffix : ''), 'binary');
+const formatSimpleLine = (line, suffix) => Buffer.concat([toLineBytes(line), Buffer.from(suffix ? suffix : '', 'binary')]);
 
 // generate headers for signing
 const simpleHeaders = (type, signingHeaderLines, options) => {

package/lib/dkim/sign.js

@@ -25,7 +25,7 @@ const dkimSign = async (input, options) => {
 class DkimSignStream extends Transform {
     constructor(options) {
         super(options);
-        this.signer = new DkimSigner(options);
+        this.signer = this.createSigner(options);
 
         this.chunks = [];
         this.chunklen = 0;
@@ -43,6 +43,11 @@ class DkimSignStream extends Transform {
         });
     }
 
+    // the signer that collects the signature headers, a subclass can sign with a different protocol
+    createSigner(options) {
+        return new DkimSigner(options);
+    }
+
     finishStream() {
         if (this.finished || !this.finishCb) {
             return;
@@ -90,4 +95,4 @@ class DkimSignStream extends Transform {
     }
 }
 
-module.exports = { dkimSign, DkimSignStream };
+module.exports = { dkimSign, DkimSignStream, formatSignatures };

package/lib/dkim/syntax.js

@@ -13,6 +13,15 @@ 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}$/;
+// the Local-part of an i= value (RFC 6376 section 3.5): RFC 5322 dot-atom-text with the UTF-8
+// of RFC 6531, or a quoted-string
+const LOCAL_PART = /^(?:(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+(?:\.(?:[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]|[^\x00-\x7f])+)*|"(?:[^"\\\r\n]|\\.)*")$/;
+
+// The characters of a host name, after U-labels are converted to A-labels. A d= with anything
+// else (such as "/", "?", "#", "@" or ":") can not name the zone of its key record, so a
+// DKIM-Signature, ARC-Seal or ARC-Message-Signature with it is a syntax error in every mode
+// (RFC 6376 section 3.5)
+const HOST_NAME_CHARS = /^[A-Za-z0-9_.-]+$/;
 
 // RFC 8617 section 4.2.1: instance values range from 1 to 50
 const MAX_ARC_INSTANCE = 50;
@@ -24,6 +33,8 @@ module.exports = {
     DOMAIN_LABEL,
     DOMAIN_NAME,
     SELECTOR,
+    LOCAL_PART,
+    HOST_NAME_CHARS,
     TIMESTAMP,
     BODY_LENGTH,
     MAX_ARC_INSTANCE,

package/lib/dkim/verify.js

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

package/lib/dkim2/dkim2-parser.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// The part of message parsing the DKIM2 signer and verifier share: the body is hashed with every
+// algorithm asked for, and kept when a body Recipe has to copy lines from it
+
+const { Buffer } = require('node:buffer');
+const { MessageParser } = require('../dkim/message-parser');
+const { SimpleHash } = require('../dkim/body/simple');
+const { MessageState, splitBodyLines } = require('./message-state');
+
+class Dkim2Parser extends MessageParser {
+    constructor() {
+        super();
+        this.bodyHashers = new Map();
+        this.bodyChunks = null;
+    }
+
+    // hashes the body with `algorithm` too, called from messageHeaders()
+    hashBodyWith(algorithm) {
+        if (!this.bodyHashers.has(algorithm)) {
+            this.bodyHashers.set(algorithm, new SimpleHash(algorithm));
+        }
+    }
+
+    // keeps the body in memory, called from messageHeaders()
+    keepBody() {
+        this.bodyChunks = this.bodyChunks || [];
+    }
+
+    async nextChunk(chunk) {
+        for (let hasher of this.bodyHashers.values()) {
+            hasher.update(chunk);
+        }
+        if (this.bodyChunks) {
+            this.bodyChunks.push(chunk);
+        }
+    }
+
+    // The message as it is, once the whole body has been read
+    currentState() {
+        let hashes = new Map();
+        for (let [algorithm, hasher] of this.bodyHashers) {
+            hashes.set(algorithm, hasher.digest('base64'));
+        }
+        let lines = this.bodyChunks ? splitBodyLines(Buffer.concat(this.bodyChunks)) : null;
+        // the lines hold the body from now on
+        this.bodyChunks = null;
+        return MessageState.fromMessage(this.headers.parsed, { lines, hashes });
+    }
+}
+
+module.exports = { Dkim2Parser };

package/lib/dkim2/dkim2-signer.js

@@ -0,0 +1,334 @@
+'use strict';
+
+// DKIM2 signer (draft-ietf-dkim-dkim2-spec-06 section 9)
+
+const crypto = require('node:crypto');
+const { getPrivateKey, getCurTime, isSameOrSubdomain } = require('../tools');
+const {
+    MI_KEY,
+    SIG_KEY,
+    HASH_ALGORITHMS,
+    NONCE,
+    TEXTSTRING,
+    isDomain,
+    parseMessageInstance,
+    parseSignature,
+    canonicalSignatureField,
+    formatMessageInstance,
+    formatSignature,
+    parsePath,
+    continuesCustody,
+    buildSignatureInput
+} = require('./fields');
+const { parseRecipe } = require('./recipe');
+const { Dkim2Parser } = require('./dkim2-parser');
+const { ALGORITHM_KEY_TYPES, rsaKeyProblem, signatureData } = require('./key');
+
+// the signing algorithm of each key type
+const KEY_ALGORITHMS = new Map(Array.from(ALGORITHM_KEY_TYPES, ([algorithm, keyType]) => [keyType, algorithm]));
+
+const signError = (message, code) => {
+    let err = new Error(message);
+    err.code = code || 'EDKIM2SIGN';
+    return err;
+};
+
+// Converts an address to an RFC 5321 path with the angle brackets (sections 8.5 and 8.6)
+const toPath = (value, allowNull) => {
+    let path = String(value ?? '').trim();
+    if (path && !/^<.*>$/.test(path)) {
+        path = `<${path}>`;
+    }
+    if (!path || path === '<>') {
+        if (!allowNull) {
+            throw signError('A RCPT TO address can not be empty', 'EINVALIDPATH');
+        }
+        return '<>';
+    }
+    if (!/^<[^<>\r\n]+>$/.test(path)) {
+        throw signError(`Invalid SMTP path ${JSON.stringify(path)}`, 'EINVALIDPATH');
+    }
+    return path;
+};
+
+// Section 3: the signing algorithm follows the key type
+const loadKey = ({ selector, privateKey, algorithm }) => {
+    if (!isDomain(selector)) {
+        throw signError(`Invalid selector ${JSON.stringify(selector)}`, 'EINVALIDSELECTOR');
+    }
+
+    let keyObject = getPrivateKey(privateKey);
+    let keyAlgorithm = KEY_ALGORITHMS.get(keyObject.asymmetricKeyType);
+    if (!keyAlgorithm) {
+        throw signError(`Unsupported key type ${keyObject.asymmetricKeyType}`, 'EINVALIDALGO');
+    }
+    if (algorithm && algorithm.toLowerCase() !== keyAlgorithm) {
+        throw signError(`Algorithm ${algorithm} does not match the ${keyObject.asymmetricKeyType} key of selector ${selector}`, 'EINVALIDALGO');
+    }
+
+    // section 3.2: RSA keys of at least 1024 bits with the public exponent 65537
+    let problem = keyObject.asymmetricKeyType === 'rsa' && rsaKeyProblem(keyObject);
+    if (problem) {
+        throw signError(`The RSA key of selector ${selector} ${problem}`, problem === 'is too short' ? 'ESHORTKEY' : 'EINVALIDKEY');
+    }
+
+    return { selector: selector.toLowerCase(), algorithm: keyAlgorithm, keyObject };
+};
+
+const createSignature = (algorithm, input, keyObject) => crypto.sign(...signatureData(algorithm, input), keyObject);
+
+// Validates the signing options and puts them into the form the signer uses
+const normalizeOptions = options => {
+    options = options || {};
+
+    let signingDomain = (options.signingDomain || '').toString().trim().toLowerCase();
+    if (!isDomain(signingDomain)) {
+        throw signError(`Invalid signing domain ${JSON.stringify(options.signingDomain)}`, 'EINVALIDDOMAIN');
+    }
+
+    let keyList =
+        options.signatureData || (options.privateKey ? [{ selector: options.selector, privateKey: options.privateKey, algorithm: options.algorithm }] : []);
+    if (!keyList.length) {
+        throw signError('No signing keys provided', 'ENOKEY');
+    }
+    let keys = keyList.map(loadKey);
+
+    // section 8.9: no selector twice, at most two signatures with the same algorithm
+    let selectors = new Set();
+    let algorithmCounts = new Map();
+    for (let { selector, algorithm } of keys) {
+        if (selectors.has(selector)) {
+            throw signError(`Selector ${selector} is listed more than once`, 'EINVALIDSELECTOR');
+        }
+        selectors.add(selector);
+        algorithmCounts.set(algorithm, (algorithmCounts.get(algorithm) || 0) + 1);
+        if (algorithmCounts.get(algorithm) > 2) {
+            throw signError(`More than two signatures use ${algorithm}`, 'EINVALIDALGO');
+        }
+    }
+
+    let result = { signingDomain, keys };
+
+    if (options.nextDomain) {
+        // section 8.7: nd= replaces both mf= and rt=
+        if (options.mailFrom !== undefined || options.rcptTo !== undefined) {
+            throw signError('nextDomain can not be used together with mailFrom or rcptTo', 'EINVALIDOPTS');
+        }
+        result.nextDomain = options.nextDomain.toString().trim().toLowerCase();
+        if (!isDomain(result.nextDomain)) {
+            throw signError(`Invalid next domain ${JSON.stringify(options.nextDomain)}`, 'EINVALIDDOMAIN');
+        }
+    } else {
+        // section 9.2: the envelope MUST be available to the signer
+        if (options.mailFrom === undefined || options.rcptTo === undefined) {
+            throw signError('mailFrom and rcptTo are required, unless nextDomain is set', 'EINVALIDOPTS');
+        }
+        result.mailFrom = toPath(options.mailFrom, true);
+        result.rcptTo = [].concat(options.rcptTo).map(value => toPath(value, false));
+        if (!result.rcptTo.length) {
+            throw signError('rcptTo needs at least one address', 'EINVALIDOPTS');
+        }
+
+        // section 8.8: the d= domain is the MAIL FROM domain or a parent of it
+        if (result.mailFrom !== '<>' && !isSameOrSubdomain(parsePath(result.mailFrom).domain, signingDomain)) {
+            throw signError(`The MAIL FROM domain does not match the signing domain ${signingDomain}`, 'EINVALIDDOMAIN');
+        }
+    }
+
+    if (options.nonce !== undefined) {
+        result.nonce = options.nonce.toString();
+        if (!NONCE.test(result.nonce)) {
+            throw signError('A nonce is at most 64 printable ASCII characters with no semicolon', 'EINVALIDOPTS');
+        }
+    }
+
+    result.flags = [].concat(options.flags || []).map(flag => flag.toString());
+    for (let flag of result.flags) {
+        if (!TEXTSTRING.test(flag)) {
+            throw signError(`Invalid flag ${JSON.stringify(flag)}`, 'EINVALIDOPTS');
+        }
+    }
+
+    result.hashAlgorithms = Array.from(new Set([].concat(options.hashAlgorithms || ['sha256']).map(algorithm => algorithm.toString().toLowerCase())));
+    for (let algorithm of result.hashAlgorithms) {
+        if (!HASH_ALGORITHMS.has(algorithm)) {
+            throw signError(`Unsupported hash algorithm ${algorithm}`, 'EINVALIDALGO');
+        }
+    }
+
+    if (options.recipe !== undefined && options.recipe !== null) {
+        let parsed = parseRecipe(JSON.stringify(options.recipe));
+        if (parsed.error) {
+            throw signError(`Invalid recipe: ${parsed.error}`, 'EINVALIDRECIPE');
+        }
+        result.recipe = options.recipe;
+        result.parsedRecipe = parsed.value;
+    }
+
+    // section 8.4, the time is read once so that the signed and the emitted t= are the same
+    result.t = Math.floor(getCurTime(options.signTime).getTime() / 1000);
+
+    return result;
+};
+
+// Reads the DKIM2 header fields that are already on the message. They have to be valid and
+// numbered without gaps, otherwise the next numbers are not known
+const readChain = (rows, key, parser, label, field) => {
+    let map = new Map();
+    for (let row of rows) {
+        if (row.key !== key) {
+            continue;
+        }
+        let parsed = parser(row.line);
+        if (parsed.error || map.has(parsed[field])) {
+            throw signError(`Can not sign a message with an invalid ${label} header field (${parsed.error || 'duplicate'})`, 'EINVALIDCHAIN');
+        }
+        map.set(parsed[field], Object.assign({ line: row.line }, parsed));
+    }
+    for (let pos = 1; pos <= map.size; pos++) {
+        if (!map.has(pos)) {
+            throw signError(`Can not sign a message where ${label} ${field}=${pos} is missing`, 'EINVALIDCHAIN');
+        }
+    }
+    return map;
+};
+
+class Dkim2Signer extends Dkim2Parser {
+    constructor(options) {
+        super();
+        this.options = normalizeOptions(options);
+
+        // the header fields to put on top of the message, DKIM2-Signature first
+        this.signatureHeaders = [];
+    }
+
+    async messageHeaders(headers) {
+        this.instances = readChain(headers.parsed, MI_KEY, parseMessageInstance, 'Message-Instance', 'm');
+        this.signatures = readChain(headers.parsed, SIG_KEY, parseSignature, 'DKIM2-Signature', 'i');
+
+        this.options.hashAlgorithms.forEach(algorithm => this.hashBodyWith(algorithm));
+        this.topInstance = this.instances.get(this.instances.size);
+        if (this.topInstance) {
+            // the hashes of the top instance are compared with the message as it is now
+            for (let { algorithm } of this.topInstance.hashes) {
+                if (HASH_ALGORITHMS.has(algorithm)) {
+                    this.hashBodyWith(algorithm);
+                }
+            }
+            if (Array.isArray(this.options.parsedRecipe?.b)) {
+                // the recipe is checked against the previous instance, which needs the body lines
+                this.keepBody();
+            }
+        }
+    }
+
+    // Section 9.1: a new Message-Instance when the message has no instance yet, or when it has
+    // changed since the top one, with a Recipe that recreates the top one
+    buildInstance(current) {
+        let options = this.options;
+        let hashes = options.hashAlgorithms.map(algorithm => ({ algorithm, headerHash: current.headerHash(algorithm), bodyHash: current.bodyHash(algorithm) }));
+
+        if (!this.topInstance) {
+            return { m: 1, hashes, recipe: options.recipe };
+        }
+
+        let top = this.topInstance;
+        let comparable = top.hashes.filter(hash => HASH_ALGORITHMS.has(hash.algorithm));
+        if (!comparable.length) {
+            throw signError(`Message-Instance m=${top.m} has no supported hash algorithm`, 'EINVALIDCHAIN');
+        }
+
+        let changed = comparable.some(hash => current.headerHash(hash.algorithm) !== hash.headerHash || current.bodyHash(hash.algorithm) !== hash.bodyHash);
+        if (!changed) {
+            return null;
+        }
+
+        if (!options.parsedRecipe) {
+            throw signError(`The message has changed since Message-Instance m=${top.m}, a recipe is required`, 'ENORECIPE');
+        }
+
+        let previous;
+        try {
+            previous = current.previous(options.parsedRecipe);
+        } catch (err) {
+            throw signError(`Invalid recipe: ${err.message}`, 'EINVALIDRECIPE');
+        }
+
+        for (let { algorithm, headerHash, bodyHash } of comparable) {
+            let previousBodyHash = previous.bodyHash(algorithm);
+            // a null body Recipe declares that the previous body can not be recreated
+            if (previous.headerHash(algorithm) !== headerHash || (previousBodyHash !== null && previousBodyHash !== bodyHash)) {
+                throw signError(`The recipe does not recreate Message-Instance m=${top.m}`, 'EINVALIDRECIPE');
+            }
+        }
+
+        return { m: top.m + 1, hashes, recipe: options.recipe };
+    }
+
+    // Section 9.3: the new signature continues the chain of custody of the previous one
+    checkCustody() {
+        let options = this.options;
+        let previous = this.signatures.get(this.signatures.size);
+        if (!previous) {
+            return;
+        }
+
+        if (previous.nextDomain) {
+            if (previous.nextDomain !== options.signingDomain) {
+                throw signError(`DKIM2-Signature i=${previous.i} requires the next signing domain to be ${previous.nextDomain}`, 'ECUSTODY');
+            }
+            return;
+        }
+
+        if (!continuesCustody(previous, options.mailFrom, options.signingDomain)) {
+            throw signError(`The signature would break the chain of custody, it does not match a RCPT TO of DKIM2-Signature i=${previous.i}`, 'ECUSTODY');
+        }
+    }
+
+    async finalChunk() {
+        let options = this.options;
+
+        let current = this.currentState();
+
+        let instance = this.buildInstance(current);
+        this.checkCustody();
+
+        let instanceHeader = instance ? formatMessageInstance(instance) : null;
+        let signature = {
+            i: this.signatures.size + 1,
+            m: instance ? instance.m : this.instances.size,
+            t: options.t,
+            signingDomain: options.signingDomain,
+            mailFrom: options.mailFrom,
+            rcptTo: options.rcptTo,
+            nextDomain: options.nextDomain,
+            nonce: options.nonce,
+            flags: options.flags,
+            signatures: options.keys.map(({ selector, algorithm }) => ({ selector, algorithm, signature: '' }))
+        };
+
+        // section 9.6: every Message-Instance by m=, every DKIM2-Signature by i=, and the new
+        // signature with empty signature values
+        let inOrder = map => Array.from({ length: map.size }, (v, index) => map.get(index + 1).line);
+        let instanceLines = inOrder(this.instances).concat(instanceHeader || []);
+        let signatureLines = inOrder(this.signatures);
+        let unsignedHeader = formatSignature(signature);
+        let input = buildSignatureInput(instanceLines, signatureLines, unsignedHeader);
+
+        options.keys.forEach(({ algorithm, keyObject }, index) => {
+            signature.signatures[index].signature = createSignature(algorithm, input, keyObject).toString('base64');
+        });
+
+        let signatureHeader = formatSignature(signature);
+        if (!canonicalSignatureField(signatureHeader, true).equals(canonicalSignatureField(unsignedHeader, true))) {
+            // the emitted header has to be the one that was signed
+            throw signError('The signed and the emitted DKIM2-Signature differ', 'EINTERNAL');
+        }
+
+        this.signatureHeaders = [signatureHeader].concat(instanceHeader || []);
+        this.i = signature.i;
+        this.m = signature.m;
+    }
+}
+
+module.exports = { Dkim2Signer };