mailauth 7.1.0 → 7.2.0

package/index.d.ts

@@ -144,20 +144,22 @@ export interface ARCSealOptions {
     /**
      * Chain validation status for the ARC-Seal cv= tag: 'none', 'pass' or 'fail' (compared
      * case-insensitively). Defaults to 'none' for the first set and is required for any later
-     * set. `authenticate()` sets it from the ARC validation result
+     * set. `authenticate()` always sets it from the ARC validation result and ignores this value
      */
     cv?: 'none' | 'pass' | 'fail' | string;
 
     /**
      * ARC instance (i= tag), 1 to 50. Defaults to one more than the highest instance on the
      * message. An instance that already exists is refused, and one that leaves a gap is
-     * refused in strict mode (the default mode seals it and adds an `arc-instance-gap` warning)
+     * refused in strict mode (the default mode seals it and adds an `arc-instance-gap` warning).
+     * `authenticate()` ignores it and always uses the next instance
      */
     i?: number;
 
     /**
      * Authentication-Results payload for the ARC-Authentication-Results header (the part after
-     * "i=N;"). `authenticate()` sets it from its own results
+     * "i=N;"). Required, and a line break is only allowed as folding (CRLF followed by a space or
+     * tab). `authenticate()` always sets it from its own results and ignores this value
      */
     authResults?: string;
 
@@ -218,16 +220,20 @@ export interface AuthStatus {
  *
  * - `rsa-sha1`: the signature uses rsa-sha1 (RFC 8301 section 3.1)
  * - `tag-syntax`: the signature is not valid tag-list syntax (duplicate tags, upper case tag
- *   names, a malformed t=, x= or l= value, or a d= or s= that is not a domain name)
+ *   names, a malformed c=, t=, x= or l= value, an l= larger than the canonicalized body, or a d=
+ *   or s= that is not a domain name)
  * - `missing-v`, `missing-h` (and the other `missing-*`): a required tag is missing
  * - `invalid-v`: v= is not "1"
  * - `identity-domain`: the i= domain is not d= or its subdomain, or it is a subdomain while
  *   the key has t=s
  * - `invalid-expiration`: x= is equal to t=
  * - `query-method`: q= does not list dns/txt
- * - `key-syntax`: the key record is not valid tag-list syntax
+ * - `key-syntax`: the key record is not valid tag-list syntax, or a k=, s= or t= value has
+ *   whitespace inside it
  * - `key-v-syntax`: the key record v= is not the first tag, or not exactly "DKIM1"
  * - `key-type-inferred`: an ed25519 key was found from its length, without k=ed25519
+ * - `key-ed25519-spki`: an ed25519 key was published as a SubjectPublicKeyInfo structure, not
+ *   as the bare 32 octet key of RFC 8463 section 4.2
  */
 export type DKIMWarning =
     | 'rsa-sha1'
@@ -245,7 +251,8 @@ export type DKIMWarning =
     | 'query-method'
     | 'key-syntax'
     | 'key-v-syntax'
-    | 'key-type-inferred';
+    | 'key-type-inferred'
+    | 'key-ed25519-spki';
 
 /**
  * DKIM verification result for a single signature
@@ -307,7 +314,8 @@ export interface DKIMResult {
         /**
          * Signing domain if it aligns with the From domain, false otherwise. For a passing
          * signature this follows the DMARC verdict once DMARC found a record, before that it
-         * only guesses relaxed alignment from the Public Suffix List.
+         * only guesses relaxed alignment from the Public Suffix List. Always false when the From
+         * header field does not yield a single Author Domain, as DMARC requires.
          */
         aligned?: string | false;
 
@@ -430,6 +438,14 @@ export interface DKIMVerifyResult {
      */
     fromFields: number;
 
+    /**
+     * Syntax of the From header fields: "valid" (RFC 5322), "lax" (accepted only by the lenient
+     * parsing, such as an unquoted comma in a display name) or "invalid" (no reliable addresses,
+     * for example text after the angle-addr). DMARC is not evaluated for an "invalid" field, nor
+     * for a "lax" one in strict mode
+     */
+    fromSyntax: 'valid' | 'lax' | 'invalid';
+
     /**
      * Domain from Return-Path header
      */
@@ -542,6 +558,10 @@ export interface ARCResult {
      * Verification status
      */
     status: AuthStatus & {
+        /**
+         * Set for a failed chain: whether it is sealed with cv=fail, false when the newest
+         * ARC-Seal on the message already says cv=fail (RFC 8617 section 5.1 step 2)
+         */
         shouldSeal?: boolean;
     };
 
@@ -600,9 +620,11 @@ export interface DMARCResult {
 
     /**
      * Effective DMARC policy ('none', 'quarantine', 'reject'): p for the author domain's own
-     * record, np or sp for an inherited one, one level lower with t=y
+     * record, np or sp for an inherited one, one level lower with t=y. Like p, sp, testMode and
+     * alignment, only set when a policy record was applied, not for a none result or a
+     * temperror before a record was found
      */
-    policy: string;
+    policy?: string;
 
     /**
      * Domain whose DMARC record the policy was taken from
@@ -612,12 +634,12 @@ export interface DMARCResult {
     /**
      * Policy for organizational domain
      */
-    p: string;
+    p?: string;
 
     /**
      * Policy for subdomains
      */
-    sp: string;
+    sp?: string;
 
     /**
      * Policy for non-existent subdomains, if published
@@ -627,7 +649,7 @@ export interface DMARCResult {
     /**
      * True when the record has t=y, in which case policy is one level below the published one
      */
-    testMode: boolean;
+    testMode?: boolean;
 
     /**
      * DMARC DNS record
@@ -640,7 +662,7 @@ export interface DMARCResult {
     status: AuthStatus & {
         header?: {
             /**
-             * Author Domain
+             * Author Domain (RFC 9989 section 9.1 header.from)
              */
             from?: string;
 
@@ -652,16 +674,16 @@ export interface DMARCResult {
 
         policy?: {
             /**
-             * The policy that was applied (RFC 8601 section 2.7.2 policy.dmarc)
+             * The policy that was applied (RFC 9989 section 9.1 policy.dmarc)
              */
             dmarc?: string;
         };
     };
 
     /**
-     * Alignment results
+     * Alignment results, set when a policy record was applied
      */
-    alignment: {
+    alignment?: {
         spf: {
             /**
              * Aligned SPF domain, or undefined if no domain aligned
@@ -729,6 +751,18 @@ export interface BIMIResult {
      */
     authority?: string;
 
+    /**
+     * Avatar preference from the avp= tag, set only for the valid values
+     */
+    preference?: 'personal' | 'brand';
+
+    /**
+     * Assertion Record and BIMI-Selector syntax deviations that were accepted because `strict` was not set:
+     * 'record-version-case', 'record-tag-case', 'record-syntax', 'uri-comma', 'location-format',
+     * 'selector-version-case', 'selector-syntax'
+     */
+    warnings?: string[];
+
     /**
      * Authentication-Results formatted info
      */
@@ -870,9 +904,9 @@ export function authenticate(input: MessageInput, opts?: AuthenticateOptions): P
 // ============================================================================
 
 /**
- * DKIM signing options
+ * A single DKIM signature to create, an entry of `DKIMSignOptions.signatureData`
  */
-export interface DKIMSignOptions {
+export interface DKIMSignatureData {
     /**
      * Signing domain (d= tag)
      */
@@ -884,10 +918,44 @@ export interface DKIMSignOptions {
     selector: string;
 
     /**
-     * Private key for signing (PEM format)
+     * Private key for signing (PEM format). An entry without a key is not signed and gets an
+     * `ENOKEY` error
      */
     privateKey: string | Buffer;
 
+    /**
+     * Overrides the shared `canonicalization`
+     */
+    canonicalization?: string;
+
+    /**
+     * Overrides the shared `algorithm`
+     */
+    algorithm?: string;
+
+    /**
+     * Overrides the shared `headerList`
+     */
+    headerList?: string[] | string;
+
+    /**
+     * Maximum body length to sign (l= tag)
+     */
+    maxBodyLength?: number;
+
+    /**
+     * Identity (i= tag), an address whose domain is the signing domain or its subdomain.
+     * Given unencoded, it is written as dkim-quoted-printable (`jõgi@example.com` as
+     * `i=j=C3=B5gi@example.com`)
+     */
+    identity?: string;
+}
+
+/**
+ * DKIM signing options. The values of each signature are set in `signatureData`, the other
+ * options apply to all of them
+ */
+export interface DKIMSignOptions {
     /**
      * Canonicalization algorithm (default: 'relaxed/relaxed')
      * Format: 'header/body' where each can be 'simple' or 'relaxed'
@@ -903,7 +971,9 @@ export interface DKIMSignOptions {
 
     /**
      * Header fields to sign, as an array or a colon separated string. Default includes
-     * From, Subject, Date, To, etc. Set per signature in `signatureData` or for all of them
+     * From, Subject, Date, To, etc. Set per signature in `signatureData` or for all of them.
+     * A name listed more than once is over-signed: it appears in h= as many times as it is
+     * listed or as the message has that field, whichever is more (`'From:From'`)
      */
     headerList?: string[] | string;
 
@@ -918,19 +988,10 @@ export interface DKIMSignOptions {
     expires?: Date | string | number;
 
     /**
-     * Maximum body length to sign (l= tag)
+     * The signatures to create. Without any, nothing is signed and `errors` holds an
+     * `ENOSIGNATURE` error
      */
-    maxBodyLength?: number;
-
-    /**
-     * Identity (i= tag), an address whose domain is the signing domain or its subdomain
-     */
-    identity?: string;
-
-    /**
-     * Multiple signature configurations
-     */
-    signatureData?: DKIMSignOptions[];
+    signatureData: DKIMSignatureData[];
 
     /**
      * Follow the RFCs exactly (default: false). Strict mode refuses rsa-sha1, RSA keys
@@ -1119,7 +1180,7 @@ export interface DKIMSignError {
     /**
      * Why the signature was not created. `err.code` is eg. 'ENOFROM', 'EINVALIDALGO',
      * 'EINVALIDTYPE', 'ESHORTKEY', 'EINVALIDDOMAIN', 'EINVALIDSELECTOR', 'EINVALIDIDENTITY',
-     * 'EINVALIDTIME', 'EINVALIDCANON' or 'EINVALIDINSTANCE'
+     * 'EINVALIDTIME', 'EINVALIDCANON', 'EINVALIDINSTANCE', 'ENOKEY' or 'ENOSIGNATURE'
      */
     err: Error & { code?: string };
 
@@ -1138,9 +1199,11 @@ export interface DKIMSignError {
  * - `invalid-expiration`: the expiration is not after the signing time, or does not fit into x=
  * - `invalid-signtime`: the signing time does not fit into t=, which was left out
  * - `d-syntax`, `s-syntax`: d= or s= is not valid RFC 6376 syntax
+ * - `identity-syntax`: the identity is not valid RFC 6376 i= syntax
  * - `identity-domain`: the identity domain is not the signing domain or its subdomain
  */
-export type DKIMSignWarning = 'rsa-sha1' | 'weak-key' | 'invalid-expiration' | 'invalid-signtime' | 'd-syntax' | 's-syntax' | 'identity-domain';
+export type DKIMSignWarning =
+    'rsa-sha1' | 'weak-key' | 'invalid-expiration' | 'invalid-signtime' | 'd-syntax' | 's-syntax' | 'identity-syntax' | 'identity-domain';
 
 /**
  * DKIM signing result
@@ -1337,6 +1400,13 @@ export interface DMARCOptions {
      */
     fromFields?: number;
 
+    /**
+     * Syntax of the From header field the addresses came from (see DKIMVerifyResult.fromSyntax).
+     * With "invalid", or "lax" in strict mode, DMARC validation is not possible (reason
+     * "invalid-author-domain"). "lax" adds the "from-syntax" warning in the default mode
+     */
+    fromSyntax?: 'valid' | 'lax' | 'invalid';
+
     /**
      * Domains that passed SPF
      */
@@ -1398,6 +1468,13 @@ export interface ARCData {
      * Error encountered during ARC chain parsing
      */
     error?: Error;
+
+    /**
+     * The lower case cv= of the newest ARC-Seal in the header fields, or false if there is
+     * none, set by the DKIM verifier. Read from the header fields even when the chain could not
+     * be parsed, to decide whether a failed chain is sealed with cv=fail
+     */
+    latestCv?: string | false;
 }
 
 /**
@@ -1409,7 +1486,9 @@ export interface ARCSealError {
      * instance out of 1-50, a chain that already has 50 sets, one that already exists, or in
      * strict mode one that leaves a gap),
      * EARCCHAINFAILED (the newest ARC-Seal already has cv=fail, RFC 8617 section 5.1 step 2),
-     * EINVALIDALGO and EINVALIDTYPE (an algorithm that is not supported or does not match the key)
+     * EINVALIDALGO and EINVALIDTYPE (an algorithm that is not supported or does not match the key),
+     * EINVALIDAUTHRESULTS (a missing or empty authResults, or one with a line break that is not
+     * CRLF folding)
      */
     err: Error & { code?: string };
     type?: string;
@@ -1516,11 +1595,14 @@ export function verifyASChain(data: ARCData, opts: ARCOptions & { warnings?: str
  *
  * @param input - RFC822 formatted message or false for pre-calculated data
  * @param data - Seal creation data
- * @returns Seal headers (empty when no set was created), the errors that say why, and what the
+ * @returns Seal headers (empty when no set was created), the errors that say why, what the
  *          default mode sealed that strict mode would have refused ('arc-instance-gap',
- *          'arc-cv-instance', and the DKIM signing warnings)
+ *          'arc-cv-instance', and the DKIM signing warnings), and the instance (i=) of a created set
  */
-export function createSeal(input: MessageInput | false, data: ARCCreateSealData): Promise<{ headers: string[]; errors: ARCSealError[]; warnings: string[] }>;
+export function createSeal(
+    input: MessageInput | false,
+    data: ARCCreateSealData
+): Promise<{ headers: string[]; errors: ARCSealError[]; warnings: string[]; instance?: number }>;
 
 // ============================================================================
 // BIMI
@@ -1551,8 +1633,10 @@ export interface BIMIOptions {
     resolver?: DNSResolver;
 
     /**
-     * Format the Authentication-Results entry in the RFC 8601 section 2.2 form (default: false).
-     * BIMI has no other strict-only rules, the draft checks apply in both modes
+     * Parse the Assertion Record exactly (default: false): `v=BIMI1` and the tag names are
+     * case-sensitive, syntax errors such as duplicate tags fail the record, and so do an `l=` URI with
+     * another image format suffix and unencoded commas in URIs. Without it these are accepted and
+     * reported in `warnings`. Also formats the Authentication-Results entry in the RFC 8601 section 2.2 form
      */
     strict?: boolean;
 }
@@ -1589,6 +1673,11 @@ export interface VMCValidationResult {
              */
             code?: string;
 
+            /**
+             * Additional error details, for `SVG_VALIDATION_FAILED` the message and code of the SVG validation error
+             */
+            details?: any;
+
             /**
              * Redirect URL if logo location redirected
              */
@@ -1596,7 +1685,8 @@ export interface VMCValidationResult {
         };
 
         /**
-         * Base64-encoded SVG logo file content
+         * Base64-encoded SVG logo file content, uncompressed if the file was SVGZ. Set only when the
+         * file passed SVG validation
          */
         logoFile?: string;
 
@@ -1665,6 +1755,44 @@ export interface VMCValidationResult {
          */
         hashMatch?: boolean;
     };
+
+    /**
+     * The BIMI status of `bimiData` updated with the validation results (7.7): `fail` with a comment
+     * when the indicator or the evidence document failed, `policy.authority` set to `pass` or `fail`
+     * when an evidence document was checked. Set only when `bimiData.status.result` was `pass`
+     */
+    status?: BIMIResult['status'];
+
+    /**
+     * Authentication-Results entry for the updated status, use it instead of the `info` of `bimi()`
+     */
+    info?: string;
+
+    /**
+     * SVG Tiny PS profile deviations of the logo files that were accepted because `strict` was not set,
+     * for example 'svg-version'
+     */
+    warnings?: string[];
+
+    /**
+     * BIMI headers for the message, set only when the logo and the evidence document (if any) validated
+     */
+    headers?: {
+        /**
+         * BIMI-Indicator header with the base64-encoded SVG logo
+         */
+        indicator: string;
+
+        /**
+         * BIMI-Location header, with a= when the evidence document was verified
+         */
+        location: string;
+
+        /**
+         * BIMI-Logo-Preference header
+         */
+        preference?: string;
+    };
 }
 
 /**
@@ -1679,6 +1807,33 @@ export interface BIMIData extends BIMIResult {
  * VMC validation options
  */
 export interface VMCValidationOptions {
+    /**
+     * Validate the logo files exactly against the SVG Tiny PS profile (default: false). Without it,
+     * the deviations that do not make a logo unsafe are accepted and listed in `warnings`. Also
+     * formats `info` in the RFC 8601 section 2.2 form
+     */
+    strict?: boolean;
+
+    /**
+     * Maximum size of the logo file in bytes, also applied to an uncompressed SVGZ file (default: 65536)
+     */
+    maxLogoSize?: number;
+
+    /**
+     * Maximum size of the evidence document in bytes (default: 262144)
+     */
+    maxEvidenceSize?: number;
+
+    /**
+     * Time limit for each download in milliseconds, including redirects and the body (default: 30000)
+     */
+    timeout?: number;
+
+    /**
+     * undici Dispatcher used for the downloads
+     */
+    dispatcher?: any;
+
     /**
      * Custom VMC validation options passed to @postalsys/vmc
      */
@@ -1702,13 +1857,30 @@ export function bimi(opts: BIMIOptions): Promise<BIMIResult | false>;
  */
 export function validateBimiVmc(bimiData: BIMIData | null, opts?: VMCValidationOptions): Promise<VMCValidationResult | false>;
 
+/**
+ * SVG logo validation options
+ */
+export interface BIMISvgValidationOptions {
+    /**
+     * Apply the SVG Tiny PS profile exactly (default: false)
+     */
+    strict?: boolean;
+
+    /**
+     * Markers of the accepted profile deviations are added to this array when `strict` is not set
+     */
+    warnings?: string[];
+}
+
 /**
  * Validates BIMI SVG logo file
  *
  * @param logo - SVG logo file buffer
+ * @param opts - validation options
+ * @returns true
  * @throws Error if validation fails
  */
-export function validateBimiSvg(logo: Buffer): void;
+export function validateBimiSvg(logo: Buffer | string, opts?: BIMISvgValidationOptions): true;
 
 // ============================================================================
 // MTA-STS
@@ -1752,6 +1924,16 @@ export interface MTASTSPolicy {
      * Error encountered during policy fetch
      */
     error?: Error;
+
+    /**
+     * Policy ID from DNS that could not be fetched, set on a cached policy that is kept in use instead
+     */
+    retryId?: string;
+
+    /**
+     * ISO 8601 timestamp before which the policy for `retryId` is not fetched again (RFC 8461 3.3)
+     */
+    retryAfter?: string;
 }
 
 /**

package/lib/arc/index.d.ts

@@ -44,6 +44,10 @@ export function verifyASChain(data: ARCData, opts: ARCOptions & { warnings?: str
  *
  * @param input - RFC822 formatted message or false for pre-calculated data
  * @param data - Seal creation data
- * @returns Seal headers, empty if the ARC-Message-Signature could not be signed, and any errors
+ * @returns Seal headers, empty if the ARC-Message-Signature could not be signed, any errors, and
+ *          the instance (i=) of a created set
  */
-export function createSeal(input: MessageInput | false, data: ARCCreateSealData): Promise<{ headers: string[]; errors: ARCSealError[]; warnings: string[] }>;
+export function createSeal(
+    input: MessageInput | false,
+    data: ARCCreateSealData
+): Promise<{ headers: string[]; errors: ARCSealError[]; warnings: string[]; instance?: number }>;

package/lib/arc/index.js

@@ -14,7 +14,8 @@ const {
     addWarning,
     KEY_ERROR_COMMENTS,
     splitAlgorithm,
-    createKeyCache
+    createKeyCache,
+    isHostNameDomain
 } = require('../../lib/tools');
 const { TIMESTAMP, BODY_LENGTH, MAX_ARC_INSTANCE, ARC_HEADER_KEYS } = require('../dkim/syntax');
 const crypto = require('node:crypto');
@@ -472,6 +473,15 @@ const getARChain = (headers, opts) => {
             checkTagList(arcInstance, 'arc-message-signature', strict, warn);
         }
 
+        // A d= that is not a host name does not name the zone of its key record (RFC 6376
+        // section 3.5), so its key is never looked up and the chain fails in every mode
+        for (let headerKey of isNewest ? ['arc-seal', 'arc-message-signature'] : ['arc-seal']) {
+            let signingDomain = (arcInstance[headerKey].parsed?.d?.value || '').toString();
+            if (signingDomain && !isHostNameDomain(signingDomain)) {
+                throw createError(`i=${arcInstance.i} ${SHORT_NAMES[headerKey]} invalid d=`, 'invalid_arc_tags');
+            }
+        }
+
         let cv = getCv(arcInstance);
 
         if (i === 0 && cv !== 'none') {
@@ -605,8 +615,11 @@ const arc = async (data, opts) => {
         // all failures are permanent in the scope of ARC
         result.i = data?.lastEntry?.i || false;
         status.result = 'fail';
-        // if last entry was listed as passing then add our seal even if the validation failed
-        status.shouldSeal = ['pass', 'none'].includes(getCv(data?.lastEntry));
+        // RFC 8617 section 5.1 step 2: a failed chain is sealed with cv=fail unless its newest
+        // seal already says cv=fail. The DKIM verifier reads the newest seal from the header
+        // fields (latestCv), so a chain that failed the structure checks and could not be
+        // parsed is sealed as well. Data from elsewhere only has the parsed chain
+        status.shouldSeal = data?.latestCv !== undefined ? data.latestCv !== 'fail' : ['pass', 'none'].includes(getCv(data?.lastEntry));
 
         switch (err.code) {
             case 'invalid_arc_seal':
@@ -699,8 +712,8 @@ const arc = async (data, opts) => {
 
 const sealError = (seal, err) => ({
     type: 'ARC',
-    selector: seal?.selector,
-    signingDomain: seal?.signingDomain,
+    selector: seal.selector,
+    signingDomain: seal.signingDomain,
     err
 });
 
@@ -713,14 +726,17 @@ const isSet = value => typeof value !== 'undefined' && value !== null && value !
  * @param {ReadableStream|Buffer|String|false} input The message, or false to use `data.headers`
  *        and `seal.bodyHash` instead
  * @param {Object} data { headers, arc, seal, strict }
- * @returns {Object} { headers, errors, warnings }. `headers` is empty when no set was created,
- *          and `errors` says why
+ * @returns {Object} { headers, errors, warnings, instance }. `headers` is empty when no set was
+ *          created, and `errors` says why. `instance` is the i= of a created set
  */
 const createSeal = async (input, data) => {
-    let { headers, arc, seal } = data;
-    let bodyHash = seal?.bodyHash;
+    let { headers, arc } = data;
+    // a copy, the instance chosen below is stored on it and the caller's object, which may be
+    // reused for the next message, stays unchanged
+    let seal = Object.assign({}, data.seal);
+    let bodyHash = seal.bodyHash;
 
-    const strict = !!(data.strict || seal?.strict);
+    const strict = !!(data.strict || seal.strict);
     const warnings = [];
     const warn = warning => addWarning(warnings, warning);
 
@@ -761,6 +777,19 @@ const createSeal = async (input, data) => {
         }
     }
 
+    // RFC 8617 section 4.1.1, the payload of the ARC-Authentication-Results header. A line break
+    // is only allowed as folding (CRLF followed by whitespace and more content), anything else
+    // would start a new header field or end the header block
+    let authResults = isSet(seal.authResults) ? String(seal.authResults) : '';
+    if (!/\S/.test(authResults)) {
+        return refuse('The authResults value for the ARC-Authentication-Results header is missing', 'EINVALIDAUTHRESULTS');
+    }
+    // a CR that does not start folding, or an LF without a CR. A search for the bad line break,
+    // a pattern that matches the whole value runs out of stack on a large one
+    if (/\r(?!\n[ \t]+[^ \t\r\n])|(?<!\r)\n/.test(authResults)) {
+        return refuse('The authResults value contains a line break that is not header folding', 'EINVALIDAUTHRESULTS');
+    }
+
     // Step 1. Calculate ARC-Message-Signature
     dkimSigner = new DkimSigner({
         // headers and bodyHash are prepared values if we do not have the source message anymore
@@ -869,7 +898,7 @@ const createSeal = async (input, data) => {
         return { headers: [], errors: dkimSigner.errors, warnings: collectWarnings() };
     }
 
-    const authResults = `ARC-Authentication-Results: i=${seal.i}; ${seal.authResults}`;
+    const authResultsHeader = `ARC-Authentication-Results: i=${seal.i}; ${authResults}`;
 
     // the ARC-Seal uses the algorithm of the ARC-Message-Signature, which follows the key type
     // when no algorithm was given
@@ -881,7 +910,7 @@ const createSeal = async (input, data) => {
         arcSeal = await signAS(
             arc?.chain || [],
             {
-                'arc-authentication-results': authResults,
+                'arc-authentication-results': authResultsHeader,
                 'arc-message-signature': messageSignature
             },
             {
@@ -900,9 +929,10 @@ const createSeal = async (input, data) => {
     }
 
     return {
-        headers: [arcSeal, messageSignature, authResults],
+        headers: [arcSeal, messageSignature, authResultsHeader],
         errors: dkimSigner.errors,
-        warnings: collectWarnings()
+        warnings: collectWarnings(),
+        instance: seal.i
     };
 };
 
@@ -911,4 +941,4 @@ const sealMessage = async (input, seal) => {
     return headers.length ? Buffer.from(headers.join('\r\n') + '\r\n') : Buffer.from('');
 };
 
-module.exports = { getARChain, verifyASChain, arc, createSeal, sealMessage };
+module.exports = { getARChain, getHighestArcInstance, verifyASChain, arc, createSeal, sealMessage };