mailauth 6.0.0 → 7.0.0

package/lib/tools.js

@@ -10,8 +10,10 @@ const crypto = require('node:crypto');
 const https = require('node:https');
 const packageData = require('../package');
 const parseDkimHeaders = require('./parse-dkim-headers');
+const { parseTagList } = parseDkimHeaders;
 const tldts = require('tldts');
 const Joi = require('joi');
+const { DOMAIN_NAME } = require('./dkim/syntax');
 const base64Schema = Joi.string().base64({ paddingRequired: false });
 
 const defaultDKIMFieldNames =
@@ -34,6 +36,51 @@ const TLDTS_OPTS = {
     allowPrivateDomains: true
 };
 
+/**
+ * Converts the U-labels of a domain name to A-labels (RFC 5890 section 2.3.2.1). Only the
+ * labels that have non-ASCII characters in them are touched: they are normalized to NFC and
+ * lower cased first, because the Punycode encoding of an upper case letter is a different
+ * label than the encoding of its lower case form, and IDNA2008 has no upper case U-labels.
+ * ASCII labels are returned as they are, so a value that is already an A-label (or plain
+ * ASCII) never changes.
+ *
+ * @param {String} domain Domain name
+ * @returns {String} Domain name with A-labels, or the input if it can not be converted
+ */
+const toALabel = domain => {
+    domain = (domain || '').toString();
+    if (!NON_ASCII.test(domain)) {
+        return domain;
+    }
+
+    return domain
+        .split('.')
+        .map(label => {
+            if (!NON_ASCII.test(label)) {
+                return label;
+            }
+            try {
+                return punycode.toASCII(label.normalize('NFC').toLowerCase());
+            } catch (err) {
+                return label;
+            }
+        })
+        .join('.');
+};
+
+// lower case A-label form of a domain without the root dot, for comparing domains
+const normalizeDomainName = domain =>
+    toALabel((domain || '').toString().trim())
+        .toLowerCase()
+        .replace(/\.$/, '');
+
+// Whether `child` is `parent` or one of its subdomains
+const isSameOrSubdomain = (child, parent) => {
+    child = normalizeDomainName(child);
+    parent = normalizeDomainName(parent);
+    return !!child && !!parent && (child === parent || child.endsWith(`.${parent}`));
+};
+
 const writeToStream = async (stream, input, chunkSize) => {
     chunkSize = chunkSize || 64 * 1024;
 
@@ -253,26 +300,17 @@ const formatSignatureHeaderLine = (type, values, folded) => {
                 }
 
                 if (['d', 's'].includes(key)) {
-                    try {
-                        // convert to A-label if needed
-                        val = punycode.toASCII(val);
-                    } catch (err) {
-                        // ignore
-                    }
+                    // convert to A-label if needed
+                    val = toALabel(val);
                 }
 
                 if (key === 'i' && type === 'DKIM') {
                     val = val.toString();
-                    let atPos = val.indexOf('@');
+                    // the domain is what follows the last "@", a quoted local-part may hold one
+                    let atPos = val.lastIndexOf('@');
                     if (atPos >= 0) {
-                        let domainPart = val.substr(atPos + 1);
-                        try {
-                            // convert to A-label if needed
-                            domainPart = punycode.toASCII(domainPart);
-                        } catch (err) {
-                            // ignore
-                        }
-                        val = val.substr(0, atPos + 1) + domainPart;
+                        // convert to A-label if needed
+                        val = val.substr(0, atPos + 1) + toALabel(val.substr(atPos + 1));
                     }
                 }
 
@@ -287,11 +325,116 @@ const formatSignatureHeaderLine = (type, values, folded) => {
     return header;
 };
 
-const getPublicKey = async (type, name, minBitLength, resolver) => {
+/**
+ * Creates an Error with a code, and any extra properties copied onto it
+ *
+ * @param {String} message Error message
+ * @param {String} code Value for err.code
+ * @param {Object} [extra] Properties to add to the error
+ * @returns {Error}
+ */
+const createError = (message, code, extra) => {
+    let err = new Error(message);
+    err.code = code;
+    return extra ? Object.assign(err, extra) : err;
+};
+
+/**
+ * Appends every item that is not in the list yet, keeping the list free of duplicates
+ *
+ * @param {Array} list List to add to
+ * @param {...*} items Items to add
+ * @returns {Array} The same list
+ */
+const addWarning = (list, ...items) => {
+    for (let item of items) {
+        if (!list.includes(item)) {
+            list.push(item);
+        }
+    }
+    return list;
+};
+
+// The result comment for a key lookup that failed with one of these codes. The DKIM verifier
+// reports them as they are, the ARC validator adds "for <query domain>"
+const KEY_ERROR_COMMENTS = new Map([
+    ['ENOTFOUND', 'no key'],
+    ['ENODATA', 'no key'],
+    ['EINVALIDVER', 'unknown key version'],
+    ['EINVALIDTYPE', 'unknown key type'],
+    ['EINVALIDVAL', 'invalid public key'],
+    // the key record h= does not list the hash algorithm (RFC 6376 section 6.1.2)
+    ['EINVALIDHASH', 'inappropriate hash algorithm'],
+    // the key record s= does not list email (RFC 6376 section 3.6.1)
+    ['EINVALIDSERVICE', 'key not for email']
+]);
+
+// an error about a key record, with the record itself as err.rr when there is one
+const keyError = (message, code, rr, extra) => createError(message, code, Object.assign(rr ? { rr } : {}, extra));
+
+// splits a colon separated key record list (h=, s=, t=) into lower case entries
+const splitKeyList = value =>
+    (typeof value === 'string' ? value : '')
+        .split(':')
+        .map(entry => entry.trim().toLowerCase())
+        .filter(entry => entry);
+
+/**
+ * Exports a public key as PEM. RSA keys have always been returned in the PKCS#1 form, but some
+ * OpenSSL versions (Node.js 24.21) can not write a key that was read from a bare RSAPublicKey in
+ * that form, so SubjectPublicKeyInfo is used then. Both forms verify the same signatures
+ *
+ * @param {KeyObject} keyObj Public key
+ * @returns {String} PEM encoded key
+ */
+const exportPublicKey = keyObj => {
+    if (keyObj.asymmetricKeyType !== 'ed25519') {
+        try {
+            return keyObj.export({ type: 'pkcs1', format: 'pem' });
+        } catch (err) {
+            // fall back to SubjectPublicKeyInfo
+        }
+    }
+    return keyObj.export({ type: 'spki', format: 'pem' });
+};
+
+/**
+ * Tells a bare RSAPublicKey (RFC 3447 A.1.1, SEQUENCE of two INTEGERs) apart from a
+ * SubjectPublicKeyInfo (a SEQUENCE that starts with the AlgorithmIdentifier SEQUENCE) by the
+ * tag of the first element of the outer DER SEQUENCE
+ *
+ * @param {Buffer} der DER encoded key
+ * @returns {Boolean} true for a bare RSAPublicKey
+ */
+const isBareRsaPublicKey = der => {
+    if (der.length < 3 || der[0] !== 0x30) {
+        return false;
+    }
+    let headerLength = der[1] < 0x80 ? 2 : 2 + (der[1] & 0x7f);
+    return der[headerLength] === 0x02;
+};
+
+/**
+ * Fetches and validates a DKIM public key record (RFC 6376 section 3.6.1, RFC 8463)
+ *
+ * @param {String} type 'DKIM', 'ARC' (for an ARC-Message-Signature) or 'AS' (for an ARC-Seal)
+ * @param {String} name DNS name of the key record, "selector._domainkey.domain"
+ * @param {Number} [minBitLength=1024] Minimum RSA key size, smaller keys throw ESHORTKEY
+ * @param {Function} [resolver] DNS resolver
+ * @param {Object} [options]
+ * @param {Boolean} [options.strict=false] Apply the RFC 6376 key record syntax rules exactly
+ * @param {String} [options.hashAlgo] Hash algorithm of the signature ('sha256', 'sha1'). When set,
+ *        a key record h= tag that does not list it throws EINVALIDHASH (RFC 6376 section 6.1.2)
+ * @returns {Object} { publicKey, rr, modulusLength, keyType, flags, testing, warnings }
+ */
+const getPublicKey = async (type, name, minBitLength, resolver, options) => {
     minBitLength = minBitLength || 1024;
     resolver = resolver || dns.resolve;
+    options = options || {};
+    const strict = !!options.strict;
 
-    let list = await resolver(name, 'TXT');
+    // RFC 8616 section 3: a U-label is converted to an A-label before it is looked up
+    let list = await resolver(toALabel(name), 'TXT');
     let rr =
         list &&
         []
@@ -299,97 +442,177 @@ const getPublicKey = async (type, name, minBitLength, resolver) => {
             .join('')
             .replace(/\s+/g, '');
 
-    if (rr) {
-        // prefix value for parsing as there is no default value
-        let entry = parseDkimHeaders(`DNS: TXT;${rr}`);
+    if (!rr) {
+        throw keyError('Missing key value', 'EINVALIDVAL');
+    }
 
-        const publicKeyValue = entry?.parsed?.p?.value;
-        if (!publicKeyValue) {
-            let err = new Error('Missing key value');
-            err.code = 'EINVALIDVAL';
-            err.rr = rr;
-            throw err;
+    const warnings = [];
+    // A rule the strict mode enforces: throws in the strict mode, notes the warning otherwise
+    const violation = (message, code, warning) => {
+        if (strict) {
+            throw keyError(message, code, rr);
         }
+        addWarning(warnings, warning);
+    };
 
-        let validation = base64Schema.validate(publicKeyValue);
-        if (validation.error) {
-            let err = new Error('Invalid base64 format for public key');
-            err.code = 'EINVALIDVAL';
-            err.rr = rr;
-            err.details = validation.error;
-            throw err;
-        }
+    // tag names are case-sensitive, so strict mode reads them as they are
+    let entry = parseTagList(rr, { strict });
+    const tags = entry.parsed;
 
-        if (type === 'DKIM' && entry?.parsed?.v && (entry?.parsed?.v?.value || '').toString().toLowerCase().trim() !== 'dkim1') {
-            let err = new Error('Unknown key version');
-            err.code = 'EINVALIDVER';
-            err.rr = rr;
-            throw err;
+    if (entry.syntaxErrors.length) {
+        // RFC 6376 section 6.1.2 step 5: a key record that does not adhere to the format is ignored
+        violation(`Invalid key record syntax: ${entry.syntaxErrors[0]}`, 'EINVALIDVAL', 'key-syntax');
+    }
+
+    const publicKeyValue = tags.p?.value;
+    if (!publicKeyValue) {
+        // an empty p= means the key has been revoked
+        throw keyError('Missing key value', 'EINVALIDVAL', rr);
+    }
+
+    let validation = base64Schema.validate(publicKeyValue);
+    if (validation.error) {
+        throw keyError('Invalid base64 format for public key', 'EINVALIDVAL', rr, { details: validation.error });
+    }
+
+    // ARC signatures use the same DKIM key records (RFC 8617 section 4.1), so the version
+    // rules apply to them as well
+    if (tags.v) {
+        let version = (tags.v.value || '').toString();
+        if (version.toLowerCase().trim() !== 'dkim1') {
+            throw keyError('Unknown key version', 'EINVALIDVER', rr);
         }
 
-        let paddingNeeded = publicKeyValue.length % 4 ? 4 - (publicKeyValue.length % 4) : 0;
-        let paddedPublicKey = publicKeyValue + '='.repeat(paddingNeeded);
+        // key-v-tag is %x44.4B.49.4D.31, an exact string, and "MUST be the first tag"
+        if (version !== 'DKIM1' || entry.tags[0]?.name !== 'v') {
+            violation(version !== 'DKIM1' ? 'Unknown key version' : 'Key version tag is not the first tag', 'EINVALIDVER', 'key-v-syntax');
+        }
+    }
 
-        let rawPublicKey = Buffer.from(publicKeyValue, 'base64');
-        let publicKeyObj;
-        let publicKeyOpts;
+    // RFC 6376 section 3.6.1 s=: "Verifiers for a given service type MUST ignore this record
+    // if the appropriate type is not listed", applied in every mode, it is the key owner's choice
+    if (tags.s) {
+        let services = splitKeyList(tags.s.value);
+        if (!services.includes('email') && !services.includes('*')) {
+            throw keyError('Key is not meant for email', 'EINVALIDSERVICE', rr);
+        }
+    }
 
-        if (rawPublicKey.length === 32) {
-            // seems like an ed25519 key
-            rawPublicKey = Buffer.concat([Buffer.from('302A300506032B6570032100', 'hex'), rawPublicKey]);
-            publicKeyOpts = {
-                key: rawPublicKey,
-                format: 'der',
-                type: 'spki'
-            };
-        } else {
-            const publicKeyPem = Buffer.from(`-----BEGIN PUBLIC KEY-----\n${paddedPublicKey.replace(/.{64}/g, '$&\n').trim()}\n-----END PUBLIC KEY-----`);
-            publicKeyOpts = {
-                key: publicKeyPem,
-                format: 'pem'
-            };
+    // RFC 6376 section 6.1.2 step 6: the key owner can limit the hash algorithms the key
+    // is used with, which is also how a domain opts out of rsa-sha1 in the lenient mode
+    if (tags.h && options.hashAlgo) {
+        let hashes = splitKeyList(tags.h.value);
+        if (!hashes.includes(options.hashAlgo.toLowerCase())) {
+            throw keyError(`Key does not allow ${options.hashAlgo}`, 'EINVALIDHASH', rr);
         }
+    }
+
+    let declaredKeyType = tags.k ? (tags.k.value || '').toString().toLowerCase().trim() : false;
+
+    let rawPublicKey = Buffer.from(publicKeyValue, 'base64');
+    let publicKeyObj;
+
+    let candidates = [];
+    if (rawPublicKey.length === 32 && (!strict || declaredKeyType === 'ed25519')) {
+        // RFC 8463 section 4: the raw 32 byte ed25519 key
+        candidates.push({
+            key: Buffer.concat([Buffer.from('302A300506032B6570032100', 'hex'), rawPublicKey]),
+            format: 'der',
+            type: 'spki'
+        });
+    } else if (isBareRsaPublicKey(rawPublicKey)) {
+        // the bare RSAPublicKey of RFC 6376 section 3.6.1 (k=rsa), picked by its structure
+        candidates.push({ key: rawPublicKey, format: 'der', type: 'pkcs1' });
+    } else {
+        // a SubjectPublicKeyInfo structure is what is published in practice
+        candidates.push({ key: rawPublicKey, format: 'der', type: 'spki' });
+    }
 
+    let lastError;
+    let exportedKey;
+    for (let candidate of candidates) {
         try {
-            publicKeyObj = crypto.createPublicKey(publicKeyOpts);
+            let keyObj = crypto.createPublicKey(candidate);
+            exportedKey = exportPublicKey(keyObj);
+            publicKeyObj = keyObj;
+            break;
         } catch (err) {
-            let error = new Error('Unknown key type (${keyType})', { cause: err });
-            error.code = 'EINVALIDTYPE';
-            error.rr = rr;
-            throw error;
+            lastError = err;
         }
+    }
 
-        let keyType = publicKeyObj.asymmetricKeyType;
+    if (!publicKeyObj) {
+        let error = new Error('Unknown key type', { cause: lastError });
+        error.code = 'EINVALIDTYPE';
+        error.rr = rr;
+        throw error;
+    }
 
-        if (!['rsa', 'ed25519'].includes(keyType) || (entry?.parsed?.k && entry?.parsed?.k?.value?.toLowerCase() !== keyType)) {
-            let err = new Error('Unknown key type (${keyType})');
-            err.code = 'EINVALIDTYPE';
-            err.rr = rr;
-            throw err;
-        }
+    let keyType = publicKeyObj.asymmetricKeyType;
 
-        let modulusLength = publicKeyObj.asymmetricKeyDetails.modulusLength;
+    if (!['rsa', 'ed25519'].includes(keyType) || (declaredKeyType && declaredKeyType !== keyType)) {
+        throw keyError(`Unknown key type (${keyType})`, 'EINVALIDTYPE', rr);
+    }
 
-        if (keyType === 'rsa' && modulusLength < minBitLength) {
-            let err = new Error('RSA key too short');
-            err.code = 'ESHORTKEY';
-            err.rr = rr;
-            throw err;
-        }
+    if (!declaredKeyType && keyType !== 'rsa') {
+        // k= defaults to "rsa", an ed25519 key is only found by looking at the key data
+        violation(`Unknown key type (${keyType})`, 'EINVALIDTYPE', 'key-type-inferred');
+    }
 
-        return {
-            publicKey: publicKeyObj.export({
-                type: publicKeyObj.asymmetricKeyType === 'ed25519' ? 'spki' : 'pkcs1',
-                format: 'pem'
-            }),
-            rr,
-            modulusLength
-        };
+    if (strict && keyType === 'ed25519' && rawPublicKey.length !== 32) {
+        // RFC 8463 section 4 publishes the bare key, not a DER structure
+        throw keyError('Invalid ed25519 public key', 'EINVALIDVAL', rr);
+    }
+
+    let modulusLength = publicKeyObj.asymmetricKeyDetails.modulusLength;
+
+    if (keyType === 'rsa' && modulusLength < minBitLength) {
+        throw keyError('RSA key too short', 'ESHORTKEY', rr);
     }
 
-    let err = new Error('Missing key value');
-    err.code = 'EINVALIDVAL';
-    throw err;
+    // t= flags. "y" is the testing mode, "s" forbids an i= domain that is a subdomain of d=
+    let flags = splitKeyList(tags.t?.value);
+
+    return {
+        publicKey: exportedKey,
+        rr,
+        modulusLength,
+        keyType,
+        flags,
+        testing: flags.includes('y'),
+        warnings
+    };
+};
+
+/**
+ * Creates a key lookup cache for one message. DKIM-Signatures, the ARC-Message-Signature and the
+ * ARC-Seals that name the same key record share one getPublicKey() call, and so one DNS query.
+ * Everything that changes the outcome of the lookup is part of the cache key, so a result is
+ * never used for a different question
+ *
+ * @param {Function} [resolver] DNS resolver, used for every lookup of the cache
+ * @returns {Object} { resolver, get(type, name, minBitLength, options) }, `get` takes the
+ *          arguments of getPublicKey() without the resolver and returns the same promise for
+ *          the same question
+ */
+const createKeyCache = resolver => {
+    const cache = new Map();
+    return {
+        resolver,
+        get(type, name, minBitLength, options) {
+            options = options || {};
+            let key = [!!options.strict, minBitLength || '', options.hashAlgo || '', name].join(':');
+            let lookup = cache.get(key);
+            if (!lookup) {
+                lookup = getPublicKey(type, name, minBitLength, resolver, options);
+                // a prefetched lookup can fail before anything waits for it. Every caller that
+                // awaits the promise still gets the error
+                lookup.catch(() => false);
+                cache.set(key, lookup);
+            }
+            return lookup;
+        }
+    };
 };
 
 const getPrivateKey = privateKeyBuf => {
@@ -447,37 +670,158 @@ const fetch = url =>
             .on('error', reject);
     });
 
-const escapePropValue = value => {
-    value = (value || '')
+// RFC 2045 section 5.1 token: printable US-ASCII except SPACE and the tspecials ()<>@,;:\"/[]?=
+const RFC2045_TOKEN = /^[!#$%&'*+\-.0-9A-Z^_`a-z{|}~]+$/;
+// What the older formatter left unquoted: a token, or a token with "@" signs in it
+const LEGACY_UNQUOTED = /^[!#$%&'*+\-.0-9A-Z^_`a-z{|}~@]+$/;
+// RFC 5322 section 3.2.3 dot-atom-text
+const DOT_ATOM_TEXT = /^[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]+(?:\.[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~]+)*$/;
+// RFC 5322 section 3.2.4 quoted-string, without CFWS around it
+const QUOTED_STRING = /^"(?:[^"\\\r\n]|\\[\x20-\x7e\t])*"$/;
+// DOMAIN_NAME is the RFC 6376 section 3.5 domain-name, which RFC 8601 uses for pvalue
+
+// A generated header line has to stay under the 998 character limit of RFC 5322 section
+// 2.1.1, and a value with no whitespace in it can not be folded. A property value longer than
+// this is left out (RFC 8601 section 2.2 lets a propspec be omitted) rather than truncated
+// into a different identity, and a word of a comment is cut short, which only loses text
+const MAX_HEADER_VALUE_LENGTH = 900;
+const MAX_COMMENT_WORD_LENGTH = 400;
+
+const cleanHeaderText = value =>
+    (value || '')
         .toString()
-        .replace(/[\x00-\x1F]+/g, ' ')
+        // CTLs and DEL are not allowed anywhere in a structured field body, not even escaped
+        .replace(/[\x00-\x1F\x7F]+/g, ' ')
         .replace(/\s+/g, ' ')
         .trim();
 
-    if (!/[\s\x00-\x1F\x7F-\uFFFF()<>,;:\\"/[\]?=]/.test(value)) {
+const quoteString = value => `"${value.replace(/["\\]/g, c => `\\${c}`)}"`;
+
+// A header value that is either an RFC 5322 dot-atom-text or, for anything else, a
+// quoted-string, such as the key-value-pair values of Received-SPF (RFC 7208 section 9.1)
+const formatDotAtomOrQuoted = value => {
+    value = cleanHeaderText(value);
+    return DOT_ATOM_TEXT.test(value) ? value : quoteString(value);
+};
+
+/**
+ * Formats a property value for an Authentication-Results header (RFC 8601 section 2.2):
+ * pvalue = value / [ [ local-part ] "@" ] domain-name, where value is a token or a
+ * quoted-string. Returns an empty string when there is nothing to report.
+ *
+ * @param {String} value Property value
+ * @param {Boolean} [strict] If true, an email identity is always written in the
+ *        local-part@domain form that RFC 8601 section 2.2 requires, with the local-part quoted
+ *        when it is not a dot-atom. Otherwise the output is kept as it was in older versions
+ *        wherever that output was already valid, which quotes such identities as a whole
+ */
+const escapePropValue = (value, strict) => {
+    value = cleanHeaderText(value);
+
+    if (!value) {
+        return '';
+    }
+
+    if (RFC2045_TOKEN.test(value)) {
         // return token value
         return value;
     }
 
+    let atPos = value.lastIndexOf('@');
+    if (atPos >= 0) {
+        let localPart = value.substring(0, atPos);
+        let domain = value.substring(atPos + 1);
+
+        if (DOMAIN_NAME.test(domain)) {
+            if (!localPart || DOT_ATOM_TEXT.test(localPart)) {
+                // a valid [ [ local-part ] "@" ] domain-name as it is
+                if (strict || LEGACY_UNQUOTED.test(value)) {
+                    return value;
+                }
+            } else if (strict) {
+                return `${QUOTED_STRING.test(localPart) ? localPart : quoteString(localPart)}@${domain}`;
+            }
+        }
+    }
+
     // return quoted string with escaped quotes
-    return `"${value.replace(/["\\]/g, c => `\\${c}`)}"`;
+    return quoteString(value);
 };
 
+/**
+ * Makes a value safe to use as the content of an RFC 5322 comment. Both parentheses and the
+ * backslash are escaped, so the comment always stays balanced and ends where it should.
+ *
+ * @param {String} value Comment text
+ * @returns {String} Escaped comment text, without the parentheses around it
+ */
 const escapeCommentValue = value => {
-    value = (value || '')
-        .toString()
-        .replace(/[\x00-\x1F]+/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim();
+    value = cleanHeaderText(value)
+        .split(' ')
+        .map(word => {
+            if (Buffer.byteLength(word) <= MAX_COMMENT_WORD_LENGTH) {
+                return word;
+            }
+            // the limit is in octets, a line of UTF-8 text is measured in octets on the wire
+            let shortened = '';
+            for (let char of word) {
+                if (Buffer.byteLength(shortened + char) > MAX_COMMENT_WORD_LENGTH) {
+                    break;
+                }
+                shortened += char;
+            }
+            return shortened + '...';
+        })
+        .join(' ');
 
-    return `${value.replace(/[\\)]/g, c => `\\${c}`)}`;
+    return value.replace(/[\\()]/g, c => `\\${c}`);
 };
 
-const formatAuthHeaderRow = (method, status) => {
+/**
+ * Formats the authserv-id of an Authentication-Results header (RFC 8601 section 2.5). It is
+ * usually the host name of the MTA, which is a token, and an internationalized host name is
+ * converted to its A-label form. Any other value is written as a quoted-string, which RFC 8601
+ * allows (authserv-id = value). With strict set such a value throws instead, as a reader that
+ * splits the header on semicolons would still take a value such as "mx.example; dkim=pass"
+ * for a result
+ *
+ * @param {String} authservId Usually the host name of the MTA
+ * @param {Boolean} [strict] If true, throws for a value that is not a token
+ * @returns {String} The authserv-id
+ */
+const formatAuthservId = (authservId, strict) => {
+    let value = toALabel(cleanHeaderText(authservId));
+
+    if (value && value.length <= MAX_HEADER_VALUE_LENGTH && RFC2045_TOKEN.test(value)) {
+        return value;
+    }
+
+    if (!value || value.length > MAX_HEADER_VALUE_LENGTH || strict) {
+        let err = new TypeError(`Invalid authserv-id ${JSON.stringify((authservId || '').toString())}, expecting a host name`);
+        err.code = 'EINVALIDAUTHSERVID';
+        throw err;
+    }
+
+    return quoteString(value);
+};
+
+/**
+ * Formats a single resinfo of an Authentication-Results header (RFC 8601 section 2.2)
+ *
+ * @param {String} method Authentication method, eg. "dkim"
+ * @param {Object} status Result status: result, comment, and the policy/smtp/body/header ptypes
+ * @param {Object} [options]
+ * @param {Boolean} [options.strict] Format email identities in the RFC 8601 section 2.2 form
+ * @returns {String} Formatted resinfo, without the leading semicolon
+ */
+const formatAuthHeaderRow = (method, status, options) => {
     status = status || {};
+    options = options || {};
     let parts = [];
 
-    parts.push(`${method}=${status.result || 'none'}`);
+    // the result is a Keyword (RFC 8601 section 2.2)
+    let result = (status.result || '').toString().replace(/[^A-Za-z0-9-]+/g, '') || 'none';
+    parts.push(`${method}=${result}`);
 
     if (status.underSized) {
         parts.push(`(${escapeCommentValue(`undersized signature: ${status.underSized} bytes unsigned`)})`);
@@ -493,9 +837,17 @@ const formatAuthHeaderRow = (method, status) => {
         }
 
         for (let prop of Object.keys(status[ptype])) {
-            if (status[ptype][prop]) {
-                parts.push(`${ptype}.${prop}=${escapePropValue(status[ptype][prop])}`);
+            let propValue = status[ptype][prop];
+            if (!propValue || !['string', 'number', 'boolean'].includes(typeof propValue)) {
+                continue;
             }
+
+            let escaped = escapePropValue(propValue, options.strict);
+            if (!escaped || Buffer.byteLength(escaped) > MAX_HEADER_VALUE_LENGTH) {
+                continue;
+            }
+
+            parts.push(`${ptype}.${prop}=${escaped}`);
         }
     }
 
@@ -524,20 +876,43 @@ const formatRelaxedLine = (line, suffix) => {
     return Buffer.from(result, 'binary');
 };
 
-// RFC 6376 section 3.7: when the signature header is hashed, its own b= value is treated
-// as empty. The tag can be preceded by WSP and, in a header that has not been unfolded
-// yet, by the CRLF of a fold. Nothing else is whitespace here, for the same reason it is
-// not in formatRelaxedLine: a byte such as 0xA0 in front of b= is content, and matching it
-// would strip a decoy tag and leave the real signature inside the hashed header
-const stripSignatureValue = line => Buffer.from(line.toString('binary').replace(/([;: \t\r\n]+b=)[^;]+/, '$1'), 'binary');
+// RFC 6376 section 3.7: when the signature header is hashed, its own b= value "(including
+// all surrounding whitespace)" is treated as empty. The segment emptied here has to be the
+// exact one the tag-list parser (lib/parse-dkim-headers.js) takes the signature from, so the
+// line is read the same way: split on the semicolons, which can not occur inside a tag value,
+// and each tag name decoded as UTF-8 with the whitespace around it removed, as buildTagMap
+// does. Matching a "b=" anywhere in the line instead would strip the wrong value when it
+// appears inside another tag, such as a z= copy of a header or an unknown tag.
+//
+// The parser keeps the last value of a repeated tag. The lenient parser folds tag names to
+// lower case, so there the last tag named "b" or "B" is the signature, the strict parser reads
+// names case-sensitively (RFC 6376 section 3.2), so there it is the last tag named exactly "b".
+const stripSignatureValue = (line, strict) => {
+    let str = line.toString('binary');
+
+    let colonPos = str.indexOf(':');
+    let prefix = colonPos >= 0 ? str.substring(0, colonPos + 1) : '';
+    let segments = (colonPos >= 0 ? str.substring(colonPos + 1) : str).split(';');
+
+    for (let i = segments.length - 1; i >= 0; i--) {
+        let eqPos = segments[i].indexOf('=');
+        if (eqPos < 0) {
+            continue;
+        }
+        let name = Buffer.from(segments[i].substring(0, eqPos), 'binary').toString().replace(/\s+/g, ' ').trim();
+        if ((strict ? name : name.toLowerCase()) === 'b') {
+            segments[i] = segments[i].substring(0, eqPos + 1);
+            break;
+        }
+    }
+
+    return Buffer.from(prefix + segments.join(';'), 'binary');
+};
 
 const formatDomain = domain => {
-    domain = domain.toLowerCase().trim();
-    try {
-        domain = punycode.toASCII(domain).toLowerCase().trim();
-    } catch (err) {
-        // ignore punycode errors
-    }
+    // toALabel normalizes a U-label to NFC first, so this matches the d= and s= values the
+    // signer writes and the verifier reports for the same name
+    domain = toALabel(domain.toLowerCase().trim()).toLowerCase().trim();
     // the root label is not part of the name, so "example.com." and "example.com" are the same domain
     return domain.replace(/\.+$/, '');
 };
@@ -589,6 +964,22 @@ const getAlignment = (fromDomain, domainList, strict) => {
     return false;
 };
 
+// The signing and the hashing algorithm of an a= value such as "rsa-sha256", in lower case.
+// A value without a dash gives the same string for both
+const splitAlgorithm = algorithm => {
+    let parts = (algorithm || '').toString().split('-');
+    return {
+        signAlgo: parts[0].toLowerCase().trim(),
+        hashAlgo: parts[parts.length - 1].toLowerCase().trim()
+    };
+};
+
+// Whether a signing and hashing algorithm pair is one this library signs and verifies with:
+// rsa-sha256 and ed25519-sha256, and rsa-sha1 when `allowSha1` is set. RFC 8463 defines
+// ed25519-sha256 only, "ed25519-sha1" is not an algorithm
+const isSupportedAlgorithm = (signAlgo, hashAlgo, allowSha1) =>
+    ['rsa', 'ed25519'].includes(signAlgo) && (hashAlgo === 'sha256' || (!!allowSha1 && signAlgo === 'rsa' && hashAlgo === 'sha1'));
+
 const validateAlgorithm = (algorithm, strict) => {
     try {
         if (!algorithm || !/^[^-]+-[^-]+$/.test(algorithm)) {
@@ -603,7 +994,7 @@ const validateAlgorithm = (algorithm, strict) => {
             throw error;
         }
 
-        if (!['sha256'].concat(!strict ? 'sha1' : []).includes(hashAlgo)) {
+        if (!isSupportedAlgorithm(signAlgo, hashAlgo, !strict)) {
             let error = new Error('Unknown hashing algorithm');
             error.hashAlgo = hashAlgo;
             throw error;
@@ -827,6 +1218,10 @@ module.exports = {
     writeToStream,
     parseHeaders,
 
+    createError,
+    addWarning,
+    KEY_ERROR_COMMENTS,
+
     defaultDKIMFieldNames,
     defaultARCFieldNames,
     defaultASFieldNames,
@@ -834,19 +1229,30 @@ module.exports = {
     getSigningHeaderLines,
     formatSignatureHeaderLine,
     parseDkimHeaders,
+    parseTagList,
     getPublicKey,
     getPrivateKey,
     formatAuthHeaderRow,
     escapeCommentValue,
+    escapePropValue,
+    formatAuthservId,
+    MAX_HEADER_VALUE_LENGTH,
+    formatDotAtomOrQuoted,
     fetch,
 
     validateAlgorithm,
+    splitAlgorithm,
+    isSupportedAlgorithm,
+    createKeyCache,
 
     getAlignment,
 
     formatRelaxedLine,
     stripSignatureValue,
     formatDomain,
+    toALabel,
+    normalizeDomainName,
+    isSameOrSubdomain,
 
     getPtrHostname,