mailauth 7.1.1 → 7.3.0

package/index.d.ts

@@ -109,6 +109,24 @@ export interface AuthenticateOptions {
      * `warnings` array of the affected result. It is never written into the headers
      */
     strict?: boolean;
+
+    /**
+     * Verify DKIM2 header fields as well (default: false). Experimental, built against
+     * draft-ietf-dkim-dkim2-spec-06. The result is added to Authentication-Results with the
+     * `dkim2` method of draft-gondwana-dkim2-authres-00 and does not take part in DMARC
+     */
+    dkim2?: boolean;
+
+    /**
+     * RCPT TO addresses of the delivery, checked against the rt= tag of the highest
+     * DKIM2-Signature. `sender` is checked against its mf= tag
+     */
+    rcptTo?: string | string[];
+
+    /**
+     * Extra DKIM2 verifier options
+     */
+    dkim2Options?: Pick<DKIM2VerifyOptions, 'curTime' | 'maxSignatureAge' | 'maxFutureTime' | 'maxInstances' | 'checkReplay'>;
 }
 
 /**
@@ -144,20 +162,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 +238,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 +269,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 +332,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 +456,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 +576,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 +638,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 +652,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 +667,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 +680,7 @@ export interface DMARCResult {
     status: AuthStatus & {
         header?: {
             /**
-             * Author Domain
+             * Author Domain (RFC 9989 section 9.1 header.from)
              */
             from?: string;
 
@@ -652,16 +692,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 +769,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
      */
@@ -818,6 +870,11 @@ export interface AuthenticateResult {
      */
     dkim: DKIMVerifyResult;
 
+    /**
+     * DKIM2 verification result, false unless the `dkim2` option is set
+     */
+    dkim2: DKIM2VerifyResult | false;
+
     /**
      * SPF verification result
      */
@@ -870,9 +927,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 +941,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 +994,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 +1011,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 +1203,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 +1222,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
@@ -1255,6 +1341,342 @@ export interface DKIMVerifyOptions {
  */
 export function dkimVerify(input: MessageInput, options?: DKIMVerifyOptions): Promise<DKIMVerifyResult>;
 
+// ============================================================================
+// DKIM2 (experimental, draft-ietf-dkim-dkim2-spec-06, draft-ietf-dkim-dkim2-dns-00)
+// ============================================================================
+
+/**
+ * A DKIM2 Recipe (draft-ietf-dkim-dkim2-spec-06 section 5). Each step either copies a range of
+ * header fields (numbered from the bottom) or body lines (numbered from the top), or emits data
+ */
+export type DKIM2RecipeStep = { c: [number, number] } | { d: string[] };
+
+export interface DKIM2Recipe {
+    /**
+     * Steps per lower case header field name. An empty array removes every field of that name
+     */
+    h?: Record<string, DKIM2RecipeStep[]>;
+
+    /**
+     * Steps for the body, or null when the previous body can not be recreated
+     */
+    b?: DKIM2RecipeStep[] | null;
+}
+
+export interface DKIM2SignatureKey {
+    /**
+     * Key selector
+     */
+    selector: string;
+
+    /**
+     * Private key, PEM or a raw 32 byte Ed25519 key
+     */
+    privateKey: string | Buffer;
+
+    /**
+     * "rsa-sha256" or "ed25519-sha256", follows the key type when not set
+     */
+    algorithm?: 'rsa-sha256' | 'ed25519-sha256';
+}
+
+/**
+ * DKIM2 signing options
+ */
+export interface DKIM2SignOptions {
+    /**
+     * Signing domain (d= tag)
+     */
+    signingDomain: string;
+
+    /**
+     * Signing keys. At most two keys per algorithm, each with its own selector
+     */
+    signatureData?: DKIM2SignatureKey[];
+
+    /**
+     * Selector of a single key, used with `privateKey` when `signatureData` is not set
+     */
+    selector?: string;
+
+    /**
+     * A single private key, used with `selector` when `signatureData` is not set
+     */
+    privateKey?: string | Buffer;
+
+    /**
+     * Algorithm of the single key
+     */
+    algorithm?: 'rsa-sha256' | 'ed25519-sha256';
+
+    /**
+     * SMTP MAIL FROM the message is sent with (mf= tag), "" or "<>" for the null sender.
+     * Required unless `nextDomain` is set
+     */
+    mailFrom?: string;
+
+    /**
+     * SMTP RCPT TO addresses the message is sent to (rt= tag). Required unless `nextDomain` is set
+     */
+    rcptTo?: string | string[];
+
+    /**
+     * Domain of the next DKIM2-Signature for an imaginary hop (nd= tag), instead of mailFrom and rcptTo
+     */
+    nextDomain?: string;
+
+    /**
+     * Nonce (n= tag), at most 64 printable ASCII characters without ";"
+     */
+    nonce?: string;
+
+    /**
+     * Flags (f= tag), such as "donotmodify", "donotexplode", "exploded", "feedback" or "feedhere"
+     */
+    flags?: string[];
+
+    /**
+     * Hash algorithms of a new Message-Instance (default: ["sha256"])
+     */
+    hashAlgorithms?: ('sha256' | 'sha512')[];
+
+    /**
+     * Recipe that recreates the previous instance of a message that was changed since its
+     * highest Message-Instance. It is checked against that instance before signing
+     */
+    recipe?: DKIM2Recipe;
+
+    /**
+     * Signing time (t= tag), defaults to now
+     */
+    signTime?: Date | string | number;
+}
+
+/**
+ * DKIM2 signing result
+ */
+export interface DKIM2SignResult {
+    /**
+     * Header fields to prepend to the message, each ending with CRLF
+     */
+    signatures: string;
+
+    /**
+     * The new DKIM2-Signature header field
+     */
+    signature: string;
+
+    /**
+     * The new Message-Instance header field, null when the message did not change
+     */
+    messageInstance: string | null;
+
+    /**
+     * i= of the new signature
+     */
+    i: number;
+
+    /**
+     * m= of the new signature
+     */
+    m: number;
+}
+
+/**
+ * Signs a message with DKIM2. Rejects for invalid options, an invalid DKIM2 chain on the
+ * message, or a recipe that does not recreate the previous instance
+ */
+export function dkim2Sign(input: MessageInput, options: DKIM2SignOptions): Promise<DKIM2SignResult>;
+
+/**
+ * Transform stream that prepends the DKIM2 header fields to the message
+ */
+export class Dkim2SignStream extends Transform {
+    constructor(options: DKIM2SignOptions);
+}
+
+/**
+ * DKIM2 verification options
+ */
+export interface DKIM2VerifyOptions {
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+
+    /**
+     * SMTP MAIL FROM of the delivery, "" for the null sender. Compared with mf= of the highest
+     * DKIM2-Signature when set
+     */
+    mailFrom?: string;
+
+    /**
+     * SMTP RCPT TO addresses of the delivery, each of which has to be listed in rt= of the highest
+     * DKIM2-Signature
+     */
+    rcptTo?: string | string[];
+
+    /**
+     * Seconds after t= when a signature expires (default: 1209600, 14 days), false to not check
+     */
+    maxSignatureAge?: number | false;
+
+    /**
+     * Seconds a t= may be ahead of the current time (default: 300), false to not check. Section 8.4
+     * allows ignoring signatures from the future
+     */
+    maxFutureTime?: number | false;
+
+    /**
+     * Time to verify against (default: now)
+     */
+    curTime?: Date | string | number;
+
+    /**
+     * Most Message-Instance, and most DKIM2-Signature, header fields processed (default: 20)
+     */
+    maxInstances?: number;
+
+    /**
+     * Called with the replay key (the m=1 hashes) of the message. Return true when a message with
+     * the same key was seen before; without an exploded flag the result is then FAIL
+     */
+    checkReplay?: (replay: { key: string; exploded: boolean }) => Promise<boolean> | boolean;
+}
+
+export type DKIM2Result = 'pass' | 'fail' | 'permerror' | 'temperror';
+
+export type DKIM2Warning = 'mail-from-not-checked' | 'rcpt-to-not-checked';
+
+export interface DKIM2Error {
+    result: DKIM2Result;
+
+    /**
+     * Human-readable string of draft-ietf-dkim-dkim2-spec-06 section 11
+     */
+    message: string;
+
+    /**
+     * i= of the DKIM2-Signature the error is reported against
+     */
+    i?: number;
+
+    /**
+     * m= of the Message-Instance the error is about
+     */
+    m?: number;
+}
+
+export interface DKIM2InstanceResult {
+    m: number;
+    hashes: { algorithm: string; header: 'pass' | 'fail'; body: 'pass' | 'fail' | 'unknown' }[];
+    recipe?: { headers: string[]; body: 'unchanged' | 'recipe' | 'unrecoverable' };
+}
+
+export interface DKIM2SignatureValueResult {
+    selector: string;
+    algorithm: string;
+
+    /**
+     * "none" for an algorithm that is not supported and ignored
+     */
+    result?: DKIM2Result | 'none';
+    comment?: string;
+    rr?: string;
+    modulusLength?: number;
+
+    /**
+     * The key record has the t=y testing flag
+     */
+    testing?: boolean;
+}
+
+export interface DKIM2SignatureResult {
+    i: number;
+    m: number;
+    signingDomain: string;
+    timestamp: number;
+    signTime: string;
+    flags: string[];
+    mailFrom?: string;
+    rcptTo?: string[];
+    nextDomain?: string;
+    nonce?: string;
+    status: { result: DKIM2Result | 'skipped'; comment?: string };
+    values: DKIM2SignatureValueResult[];
+}
+
+/**
+ * DKIM2 verification result
+ */
+export interface DKIM2VerifyResult {
+    status: {
+        result: DKIM2Result | 'none';
+
+        /**
+         * The human-readable string of the reported failure
+         */
+        comment?: string;
+        header?: { d?: string; i?: number };
+
+        /**
+         * The parts of the SMTP envelope that were not given, so the highest DKIM2-Signature was
+         * not compared with them and an unchanged copy sent to someone else would pass as well.
+         * Only present when there is something to report, never written into `info`
+         */
+        warnings?: DKIM2Warning[];
+    };
+
+    /**
+     * Authentication-Results resinfo
+     */
+    info: string;
+    errors: DKIM2Error[];
+    instances: DKIM2InstanceResult[];
+    signatures: DKIM2SignatureResult[];
+
+    /**
+     * The key for replay detection and whether a signature allows copies
+     */
+    replay?: { key: string; exploded: boolean };
+}
+
+/**
+ * DKIM2 hashing options
+ */
+export interface DKIM2HashOptions {
+    /**
+     * Hash algorithms (default: ["sha256"])
+     */
+    algorithms?: ('sha256' | 'sha512')[];
+}
+
+/**
+ * DKIM2 hashes of a message
+ */
+export interface DKIM2HashResult {
+    /**
+     * Names of the hashed header fields, in the order they are hashed
+     */
+    headers: string[];
+
+    /**
+     * The hash-sets of the h= tag of a Message-Instance
+     */
+    hashes: { algorithm: 'sha256' | 'sha512'; headerHash: string; bodyHash: string }[];
+}
+
+/**
+ * Computes the DKIM2 header and body hashes of a message, as they go into the h= tag of a
+ * Message-Instance header field. Rejects for an unsupported hash algorithm
+ */
+export function dkim2Hash(input: MessageInput, options?: DKIM2HashOptions): Promise<DKIM2HashResult>;
+
+/**
+ * Verifies the DKIM2 header fields of a message
+ */
+export function dkim2Verify(input: MessageInput, options?: DKIM2VerifyOptions): Promise<DKIM2VerifyResult>;
+
 // ============================================================================
 // SPF
 // ============================================================================
@@ -1337,6 +1759,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 +1827,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 +1845,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 +1954,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 +1992,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 +2032,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 +2044,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 +2114,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 +2166,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 +2216,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 +2283,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;
 }
 
 /**