mailauth 4.11.0 → 4.12.0

package/index.d.ts

@@ -0,0 +1,1354 @@
+// Type definitions for mailauth
+// Project: https://github.com/postalsys/mailauth
+// Definitions by: Claude Code
+
+/// <reference types="node" />
+
+import { Readable, Transform } from 'stream';
+
+/**
+ * DNS resolver function type for custom DNS resolution
+ */
+export type DNSResolver = (domain: string, rrtype: string) => Promise<string[][] | string[]>;
+
+/**
+ * Input types accepted by mailauth functions
+ */
+export type MessageInput = Readable | Buffer | string;
+
+// ============================================================================
+// Main authenticate() function
+// ============================================================================
+
+/**
+ * Options for the authenticate() function
+ */
+export interface AuthenticateOptions {
+    /**
+     * If true, parse ip and helo values from Received header and sender value from Return-Path
+     */
+    trustReceived?: boolean;
+
+    /**
+     * Address from MAIL FROM
+     */
+    sender?: string;
+
+    /**
+     * Client IP address
+     */
+    ip?: string;
+
+    /**
+     * Hostname from EHLO/HELO
+     */
+    helo?: string;
+
+    /**
+     * MTA/MX hostname (defaults to os.hostname())
+     */
+    mta?: string;
+
+    /**
+     * Minimal allowed length of public keys in bits (default: 1024)
+     * If DKIM/ARC key is smaller, verification fails
+     */
+    minBitLength?: number;
+
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+
+    /**
+     * If true, do not perform ARC validation and sealing
+     */
+    disableArc?: boolean;
+
+    /**
+     * If true, do not perform DMARC check
+     */
+    disableDmarc?: boolean;
+
+    /**
+     * If true, do not perform BIMI check
+     */
+    disableBimi?: boolean;
+
+    /**
+     * Require aligned DKIM signature for BIMI
+     */
+    bimiWithAlignedDkim?: boolean;
+
+    /**
+     * ARC sealing options
+     */
+    seal?: ARCSealOptions;
+}
+
+/**
+ * ARC sealing options
+ */
+export interface ARCSealOptions {
+    /**
+     * ARC key domain name
+     */
+    signingDomain: string;
+
+    /**
+     * ARC key selector
+     */
+    selector: string;
+
+    /**
+     * Private key for signing (PEM format)
+     */
+    privateKey: string | Buffer;
+
+    /**
+     * Canonicalization algorithm (default: 'relaxed/relaxed')
+     */
+    canonicalization?: string;
+
+    /**
+     * Signing algorithm (default: 'rsa-sha256')
+     * Supported: 'rsa-sha256', 'ed25519-sha256'
+     */
+    algorithm?: string;
+
+    /**
+     * Headers to include in signature
+     */
+    headerList?: string[];
+
+    /**
+     * Signing timestamp
+     */
+    signTime?: Date | string | number;
+}
+
+/**
+ * Policy information attached to authentication status
+ */
+export interface AuthPolicy {
+    /**
+     * DKIM policy rules (e.g., 'weak-key' when key is undersized)
+     */
+    'dkim-rules'?: string;
+
+    /**
+     * Additional policy properties
+     */
+    [key: string]: string | undefined;
+}
+
+/**
+ * Status result from authentication checks
+ */
+export interface AuthStatus {
+    result: 'pass' | 'fail' | 'neutral' | 'none' | 'temperror' | 'temperr' | 'permerror' | 'policy' | 'softfail' | 'skipped';
+    comment?: string;
+    header?: Record<string, any>;
+    smtp?: {
+        mailfrom?: string;
+        helo?: string;
+    };
+    policy?: AuthPolicy;
+}
+
+/**
+ * DKIM verification result for a single signature
+ */
+export interface DKIMResult {
+    /**
+     * Signature identifier
+     */
+    id?: string;
+
+    /**
+     * Signing domain
+     */
+    signingDomain: string;
+
+    /**
+     * Key selector
+     */
+    selector?: string;
+
+    /**
+     * Verification status
+     */
+    status: AuthStatus & {
+        aligned?: boolean;
+        underSized?: boolean;
+    };
+
+    /**
+     * Authentication-Results formatted info
+     */
+    info: string;
+
+    /**
+     * Signature algorithm
+     */
+    algorithm?: string;
+
+    /**
+     * Canonicalization method
+     */
+    canonicalization?: string;
+
+    /**
+     * Signing timestamp
+     */
+    signingTime?: Date;
+
+    /**
+     * Signature expiration
+     */
+    expiration?: Date;
+}
+
+/**
+ * DKIM verification results
+ */
+export interface DKIMVerifyResult {
+    /**
+     * Domain from From header
+     */
+    headerFrom: string[];
+
+    /**
+     * Domain from Return-Path header
+     */
+    envelopeFrom: string | false;
+
+    /**
+     * Individual signature verification results
+     */
+    results: DKIMResult[];
+
+    /**
+     * Parsed message headers (non-enumerable property)
+     * Access with result.headers or Object.getOwnPropertyDescriptor()
+     */
+    readonly headers?: {
+        parsed: Array<{ key: string; line: string }>;
+        [key: string]: any;
+    };
+
+    /**
+     * ARC chain data for sealing (non-enumerable property)
+     * Access with result.arc or Object.getOwnPropertyDescriptor()
+     */
+    readonly arc?: ARCSigningData;
+
+    /**
+     * ARC sealing options passed to dkimVerify (non-enumerable property)
+     * Access with result.seal or Object.getOwnPropertyDescriptor()
+     */
+    readonly seal?: ARCSealOptions;
+}
+
+/**
+ * SPF verification result
+ */
+export interface SPFResult {
+    /**
+     * Sender domain
+     */
+    domain: string;
+
+    /**
+     * Client IP address
+     */
+    'client-ip': string;
+
+    /**
+     * HELO/EHLO hostname
+     */
+    helo?: string;
+
+    /**
+     * Envelope sender address
+     */
+    'envelope-from'?: string;
+
+    /**
+     * Verification status
+     */
+    status: AuthStatus;
+
+    /**
+     * SPF record used for verification
+     */
+    rr?: string;
+
+    /**
+     * Formatted Received-SPF header
+     */
+    header: string;
+
+    /**
+     * Authentication-Results formatted info
+     */
+    info: string;
+
+    /**
+     * DNS lookup statistics
+     */
+    lookups?: {
+        limit: number;
+        count: number;
+        void: number;
+        subqueries: Record<string, number>;
+    };
+}
+
+/**
+ * ARC verification result
+ */
+export interface ARCResult {
+    /**
+     * ARC instance number
+     */
+    i: number | false;
+
+    /**
+     * Verification status
+     */
+    status: AuthStatus & {
+        shouldSeal?: boolean;
+    };
+
+    /**
+     * ARC-Message-Signature verification result
+     */
+    signature?: DKIMResult | false;
+
+    /**
+     * Parsed Authentication-Results from ARC chain
+     */
+    authenticationResults?: Record<string, any>;
+
+    /**
+     * Authentication-Results formatted info
+     */
+    info?: string;
+
+    /**
+     * Formatted Authentication-Results header value
+     */
+    authResults?: string;
+
+    /**
+     * ARC chain entries (non-enumerable property)
+     * Access with result.chain or Object.getOwnPropertyDescriptor()
+     */
+    readonly chain?: ARCChainEntry[];
+}
+
+/**
+ * DMARC verification result
+ */
+export interface DMARCResult {
+    /**
+     * Organization domain
+     */
+    domain: string;
+
+    /**
+     * DMARC policy ('none', 'quarantine', 'reject')
+     */
+    policy: string;
+
+    /**
+     * Policy for organizational domain
+     */
+    p: string;
+
+    /**
+     * Policy for subdomains
+     */
+    sp: string;
+
+    /**
+     * Percentage of messages subject to filtering (0-100)
+     */
+    pct?: number;
+
+    /**
+     * DMARC DNS record
+     */
+    rr?: string;
+
+    /**
+     * Verification status
+     */
+    status: AuthStatus;
+
+    /**
+     * Alignment results
+     */
+    alignment: {
+        spf: {
+            result: string | false;
+            strict: boolean;
+        };
+        dkim: {
+            result: string | false;
+            strict: boolean;
+            underSized?: boolean;
+        };
+    };
+
+    /**
+     * Authentication-Results formatted info
+     */
+    info: string;
+
+    /**
+     * Error message if verification failed
+     */
+    error?: string;
+}
+
+/**
+ * BIMI verification result
+ */
+export interface BIMIResult {
+    /**
+     * Verification status
+     */
+    status: AuthStatus;
+
+    /**
+     * BIMI DNS record
+     */
+    rr?: string;
+
+    /**
+     * Logo location URL
+     */
+    location?: string;
+
+    /**
+     * VMC (Verified Mark Certificate) authority URL
+     */
+    authority?: string;
+
+    /**
+     * Authentication-Results formatted info
+     */
+    info: string;
+}
+
+/**
+ * Parsed Received header information
+ */
+export interface ReceivedChainEntry {
+    /**
+     * Hostname/IP that sent the message
+     */
+    from?: {
+        /**
+         * Hostname or IP address
+         */
+        value: string;
+
+        /**
+         * Additional comment (often contains IP in parentheses)
+         */
+        comment?: string;
+    };
+
+    /**
+     * Hostname that received the message
+     */
+    by?: {
+        /**
+         * Receiving hostname
+         */
+        value: string;
+
+        /**
+         * Additional comment
+         */
+        comment?: string;
+    };
+
+    /**
+     * Protocol used for transmission (e.g., 'SMTP', 'ESMTP', 'ESMTPS')
+     */
+    with?: {
+        value: string;
+    };
+
+    /**
+     * Message ID assigned by the receiving server
+     */
+    id?: {
+        value: string;
+    };
+
+    /**
+     * Recipient address
+     */
+    for?: {
+        value: string;
+    };
+
+    /**
+     * Envelope sender address from MAIL FROM
+     */
+    'envelope-from'?: {
+        value: string;
+    };
+
+    /**
+     * Timestamp when the message was received
+     */
+    date?: Date;
+
+    /**
+     * Additional parsed Received header fields
+     */
+    [key: string]: any;
+}
+
+/**
+ * Result from authenticate() function
+ */
+export interface AuthenticateResult {
+    /**
+     * DKIM verification results
+     */
+    dkim: DKIMVerifyResult;
+
+    /**
+     * SPF verification result
+     */
+    spf: SPFResult | false;
+
+    /**
+     * DMARC verification result
+     */
+    dmarc: DMARCResult | false;
+
+    /**
+     * ARC verification result
+     */
+    arc: ARCResult | false;
+
+    /**
+     * BIMI verification result
+     */
+    bimi: BIMIResult | false;
+
+    /**
+     * Parsed Received header chain
+     */
+    receivedChain?: ReceivedChainEntry[];
+
+    /**
+     * Combined authentication headers to prepend to message
+     */
+    headers: string;
+}
+
+/**
+ * Verifies DKIM, SPF, DMARC, ARC, and BIMI for an email message
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param opts - Authentication options
+ * @returns Authentication results including all protocol checks
+ */
+export function authenticate(input: MessageInput, opts?: AuthenticateOptions): Promise<AuthenticateResult>;
+
+// ============================================================================
+// DKIM Sign
+// ============================================================================
+
+/**
+ * DKIM signing options
+ */
+export interface DKIMSignOptions {
+    /**
+     * Signing domain (d= tag)
+     */
+    signingDomain: string;
+
+    /**
+     * Key selector (s= tag)
+     */
+    selector: string;
+
+    /**
+     * Private key for signing (PEM format)
+     */
+    privateKey: string | Buffer;
+
+    /**
+     * Canonicalization algorithm (default: 'relaxed/relaxed')
+     * Format: 'header/body' where each can be 'simple' or 'relaxed'
+     */
+    canonicalization?: string;
+
+    /**
+     * Signing algorithm (default: 'rsa-sha256')
+     * Supported: 'rsa-sha256', 'rsa-sha1', 'ed25519-sha256'
+     */
+    algorithm?: string;
+
+    /**
+     * List of header fields to sign
+     * Default includes From, Subject, Date, To, etc.
+     */
+    headerList?: string[];
+
+    /**
+     * Signing timestamp (defaults to current time)
+     */
+    signTime?: Date | string | number;
+
+    /**
+     * Signature expiration time
+     */
+    expires?: Date | string | number;
+
+    /**
+     * Maximum body length to sign (l= tag)
+     */
+    maxBodyLength?: number;
+
+    /**
+     * Identity (i= tag)
+     */
+    identity?: string;
+
+    /**
+     * Multiple signature configurations
+     */
+    signatureData?: DKIMSignOptions[];
+}
+
+/**
+ * Parsed DKIM/ARC header tag-value pair
+ */
+export interface ParsedHeaderValue {
+    /**
+     * Tag name
+     */
+    key?: string;
+
+    /**
+     * Tag value
+     */
+    value?: string | number;
+}
+
+/**
+ * Parsed DKIM/ARC header structure
+ */
+export interface ParsedHeader {
+    /**
+     * Original header line
+     */
+    original?: string;
+
+    /**
+     * Parsed tag-value pairs
+     */
+    parsed?: {
+        /**
+         * Instance number (i= tag for ARC)
+         */
+        i?: ParsedHeaderValue;
+
+        /**
+         * Algorithm (a= tag)
+         */
+        a?: ParsedHeaderValue;
+
+        /**
+         * Signature data (b= tag)
+         */
+        b?: ParsedHeaderValue;
+
+        /**
+         * Body hash (bh= tag)
+         */
+        bh?: ParsedHeaderValue;
+
+        /**
+         * Canonicalization (c= tag)
+         */
+        c?: ParsedHeaderValue;
+
+        /**
+         * Signing domain (d= tag)
+         */
+        d?: ParsedHeaderValue;
+
+        /**
+         * Selector (s= tag)
+         */
+        s?: ParsedHeaderValue;
+
+        /**
+         * Signed headers (h= tag)
+         */
+        h?: ParsedHeaderValue;
+
+        /**
+         * Chain validation result (cv= tag for ARC-Seal)
+         */
+        cv?: ParsedHeaderValue;
+
+        /**
+         * Timestamp (t= tag)
+         */
+        t?: ParsedHeaderValue;
+
+        /**
+         * Additional parsed properties
+         */
+        [key: string]: ParsedHeaderValue | undefined;
+    };
+
+    /**
+     * Signing algorithm type (e.g., 'rsa', 'ed25519')
+     */
+    signAlgo?: string;
+
+    /**
+     * Full algorithm (e.g., 'rsa-sha256')
+     */
+    algorithm?: string;
+}
+
+/**
+ * ARC chain entry representing a single ARC set (i=N)
+ */
+export interface ARCChainEntry {
+    /**
+     * ARC instance number
+     */
+    i: number;
+
+    /**
+     * ARC-Seal header
+     */
+    'arc-seal'?: ParsedHeader;
+
+    /**
+     * ARC-Message-Signature header
+     */
+    'arc-message-signature'?: ParsedHeader;
+
+    /**
+     * ARC-Authentication-Results header
+     */
+    'arc-authentication-results'?: ParsedHeader;
+
+    /**
+     * Message signature verification result (for last entry)
+     */
+    messageSignature?: DKIMResult;
+}
+
+/**
+ * ARC signing data returned from DKIM signing
+ */
+export interface ARCSigningData {
+    /**
+     * ARC chain from message headers (false if no chain found)
+     */
+    chain: ARCChainEntry[] | false;
+
+    /**
+     * Last entry in the ARC chain
+     */
+    lastEntry?: ARCChainEntry;
+
+    /**
+     * ARC instance number for signing
+     */
+    instance?: number;
+
+    /**
+     * Generated ARC-Message-Signature header
+     */
+    messageSignature?: string;
+
+    /**
+     * Error encountered during ARC processing
+     */
+    error?: Error;
+
+    /**
+     * ARC signing domain (from options)
+     */
+    signingDomain?: string;
+
+    /**
+     * ARC key selector (from options)
+     */
+    selector?: string;
+
+    /**
+     * ARC private key (from options)
+     */
+    privateKey?: string | Buffer;
+}
+
+/**
+ * DKIM signing result
+ */
+export interface DKIMSignResult {
+    /**
+     * DKIM-Signature header(s) to prepend to message
+     */
+    signatures: string;
+
+    /**
+     * ARC chain information (if ARC signing was performed)
+     */
+    arc?: ARCSigningData;
+
+    /**
+     * Any errors encountered during signing
+     */
+    errors: Error[];
+}
+
+/**
+ * Signs an email message with DKIM signature(s)
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param options - DKIM signing options
+ * @returns DKIM signature header(s) and any errors
+ */
+export function dkimSign(input: MessageInput, options: DKIMSignOptions): Promise<DKIMSignResult>;
+
+/**
+ * Transform stream for DKIM signing
+ * Prepends DKIM-Signature header to the message stream
+ */
+export class DkimSignStream extends Transform {
+    /**
+     * Creates a DKIM signing stream
+     *
+     * @param options - DKIM signing options
+     */
+    constructor(options: DKIMSignOptions);
+
+    /**
+     * Any errors encountered during signing
+     */
+    errors: Error[] | null;
+}
+
+// ============================================================================
+// DKIM Verify
+// ============================================================================
+
+/**
+ * DKIM verification options
+ */
+export interface DKIMVerifyOptions {
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+
+    /**
+     * Sender address (defaults to Return-Path header)
+     */
+    sender?: string;
+
+    /**
+     * Minimal allowed public key length in bits (default: 1024)
+     */
+    minBitLength?: number;
+
+    /**
+     * Current time for signature expiration checks
+     */
+    curTime?: Date | string | number;
+
+    /**
+     * ARC sealing options (if sealing should be prepared)
+     */
+    seal?: ARCSealOptions;
+}
+
+/**
+ * Verifies DKIM signatures in an email message
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param options - DKIM verification options
+ * @returns DKIM verification results
+ */
+export function dkimVerify(input: MessageInput, options?: DKIMVerifyOptions): Promise<DKIMVerifyResult>;
+
+// ============================================================================
+// SPF
+// ============================================================================
+
+/**
+ * SPF verification options
+ */
+export interface SPFOptions {
+    /**
+     * Email address from MAIL FROM
+     */
+    sender?: string;
+
+    /**
+     * Client IP address
+     */
+    ip: string;
+
+    /**
+     * Client EHLO/HELO hostname
+     */
+    helo?: string;
+
+    /**
+     * MTA hostname (defaults to os.hostname())
+     */
+    mta?: string;
+
+    /**
+     * Maximum DNS lookups allowed (default: 10)
+     */
+    maxResolveCount?: number;
+
+    /**
+     * Maximum void DNS lookups allowed (default: 2)
+     */
+    maxVoidCount?: number;
+
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+}
+
+/**
+ * Verifies SPF for a sender
+ *
+ * @param opts - SPF verification options
+ * @returns SPF verification result
+ */
+export function spf(opts: SPFOptions): Promise<SPFResult>;
+
+// ============================================================================
+// DMARC
+// ============================================================================
+
+/**
+ * DMARC verification options
+ */
+export interface DMARCOptions {
+    /**
+     * Domain from From header
+     */
+    headerFrom: string | string[];
+
+    /**
+     * Domains that passed SPF
+     */
+    spfDomains?: string[];
+
+    /**
+     * Domains and alignment info from DKIM signatures
+     */
+    dkimDomains?: Array<{
+        id?: string;
+        domain: string;
+        aligned?: boolean;
+        underSized?: boolean;
+    }>;
+
+    /**
+     * ARC verification result
+     */
+    arcResult?: ARCResult;
+
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+}
+
+/**
+ * Verifies DMARC policy for a message
+ *
+ * @param opts - DMARC verification options
+ * @returns DMARC verification result
+ */
+export function dmarc(opts: DMARCOptions): Promise<DMARCResult | false>;
+
+// ============================================================================
+// ARC
+// ============================================================================
+
+/**
+ * ARC data structure
+ */
+export interface ARCData {
+    /**
+     * ARC chain entries
+     */
+    chain: ARCChainEntry[];
+
+    /**
+     * Last entry in the ARC chain
+     */
+    lastEntry?: ARCChainEntry;
+
+    /**
+     * Error encountered during ARC chain parsing
+     */
+    error?: Error;
+}
+
+/**
+ * ARC verification options
+ */
+export interface ARCOptions {
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+
+    /**
+     * Minimal allowed public key length in bits (default: 1024)
+     */
+    minBitLength?: number;
+}
+
+/**
+ * Verifies ARC chain in a message
+ *
+ * @param data - ARC chain data
+ * @param opts - ARC verification options
+ * @returns ARC verification result
+ */
+export function arc(data: ARCData, opts?: ARCOptions): Promise<ARCResult>;
+
+/**
+ * Seals a message with ARC headers
+ *
+ * @param input - RFC822 formatted message (stream, buffer, or string)
+ * @param seal - ARC sealing options
+ * @returns ARC headers to prepend
+ */
+export function sealMessage(input: MessageInput, seal: ARCSealOptions): Promise<Buffer>;
+
+/**
+ * Gets ARC chain from parsed headers
+ *
+ * @param headers - Parsed message headers
+ * @returns ARC chain or false if no chain found
+ */
+export function getARChain(headers: any): ARCChainEntry[] | false;
+
+/**
+ * Verifies ARC seal chain
+ *
+ * @param data - ARC chain data
+ * @param opts - ARC verification options
+ * @returns true if chain is valid
+ */
+export function verifyASChain(data: ARCData, opts: ARCOptions): Promise<boolean>;
+
+/**
+ * Creates ARC seal headers
+ *
+ * @param input - RFC822 formatted message or false for pre-calculated data
+ * @param data - Seal creation data
+ * @returns Seal headers
+ */
+export function createSeal(input: MessageInput | false, data: any): Promise<{ headers: string[] }>;
+
+// ============================================================================
+// BIMI
+// ============================================================================
+
+/**
+ * BIMI lookup options
+ */
+export interface BIMIOptions {
+    /**
+     * DMARC verification result
+     */
+    dmarc?: DMARCResult;
+
+    /**
+     * Parsed message headers
+     */
+    headers?: any;
+
+    /**
+     * Require aligned DKIM signature
+     */
+    bimiWithAlignedDkim?: boolean;
+
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+}
+
+/**
+ * VMC (Verified Mark Certificate) validation result
+ */
+export interface VMCValidationResult {
+    /**
+     * Logo file fetch and validation result
+     */
+    location?: {
+        /**
+         * URL the logo was fetched from
+         */
+        url: string;
+
+        /**
+         * Whether the logo was successfully fetched and validated
+         */
+        success: boolean;
+
+        /**
+         * Error information if fetch/validation failed
+         */
+        error?: {
+            /**
+             * Human-readable error message
+             */
+            message: string;
+
+            /**
+             * Error code
+             */
+            code?: string;
+
+            /**
+             * Redirect URL if logo location redirected
+             */
+            redirect?: string;
+        };
+
+        /**
+         * Base64-encoded SVG logo file content
+         */
+        logoFile?: string;
+
+        /**
+         * Hash algorithm used for logo verification (e.g., 'sha256')
+         */
+        hashAlgo?: string;
+
+        /**
+         * Hash value of the logo file
+         */
+        hashValue?: string;
+    };
+
+    /**
+     * VMC certificate fetch and validation result
+     */
+    authority?: {
+        /**
+         * URL the VMC certificate was fetched from
+         */
+        url: string;
+
+        /**
+         * Whether the certificate was successfully fetched and validated
+         */
+        success: boolean;
+
+        /**
+         * Error information if fetch/validation failed
+         */
+        error?: {
+            /**
+             * Human-readable error message
+             */
+            message: string;
+
+            /**
+             * Error code
+             */
+            code?: string;
+
+            /**
+             * Additional error details
+             */
+            details?: any;
+
+            /**
+             * Redirect URL if authority location redirected
+             */
+            redirect?: string;
+        };
+
+        /**
+         * Parsed VMC certificate data
+         */
+        vmc?: any;
+
+        /**
+         * Whether the domain in the certificate matches the sender domain
+         */
+        domainVerified?: boolean;
+
+        /**
+         * Whether the logo hash in the certificate matches the fetched logo
+         */
+        hashMatch?: boolean;
+    };
+}
+
+/**
+ * BIMI data for VMC validation
+ */
+export interface BIMIData extends BIMIResult {
+    locationPath?: Buffer;
+    authorityPath?: Buffer;
+}
+
+/**
+ * VMC validation options
+ */
+export interface VMCValidationOptions {
+    /**
+     * Custom VMC validation options passed to @postalsys/vmc
+     */
+    [key: string]: any;
+}
+
+/**
+ * Resolves BIMI record and logo location for a domain
+ *
+ * @param opts - BIMI lookup options
+ * @returns BIMI verification result
+ */
+export function bimi(opts: BIMIOptions): Promise<BIMIResult | false>;
+
+/**
+ * Validates BIMI VMC (Verified Mark Certificate) and logo file
+ *
+ * @param bimiData - BIMI data including location and authority URLs
+ * @param opts - VMC validation options
+ * @returns VMC validation result
+ */
+export function validateBimiVmc(bimiData: BIMIData | null, opts?: VMCValidationOptions): Promise<VMCValidationResult | false>;
+
+/**
+ * Validates BIMI SVG logo file
+ *
+ * @param logo - SVG logo file buffer
+ * @throws Error if validation fails
+ */
+export function validateBimiSvg(logo: Buffer): void;
+
+// ============================================================================
+// MTA-STS
+// ============================================================================
+
+/**
+ * MTA-STS policy
+ */
+export interface MTASTSPolicy {
+    /**
+     * Policy ID from DNS (undefined when returned from parsePolicy)
+     */
+    id?: string | false;
+
+    /**
+     * Policy version (should be 'STSv1')
+     */
+    version?: string;
+
+    /**
+     * Policy mode ('enforce', 'testing', 'none')
+     */
+    mode: 'enforce' | 'testing' | 'none';
+
+    /**
+     * Maximum age in seconds
+     */
+    maxAge?: number;
+
+    /**
+     * List of allowed MX hostnames (may include wildcards like *.example.com)
+     */
+    mx?: string[];
+
+    /**
+     * Policy expiration timestamp
+     */
+    expires?: string;
+
+    /**
+     * Error encountered during policy fetch
+     */
+    error?: Error;
+}
+
+/**
+ * MTA-STS policy fetch result
+ */
+export interface MTASTSPolicyResult {
+    /**
+     * Fetched or renewed policy
+     */
+    policy: MTASTSPolicy;
+
+    /**
+     * Status of the fetch operation
+     */
+    status: 'found' | 'renewed' | 'not_found' | 'errored';
+}
+
+/**
+ * MTA-STS MX validation result
+ */
+export interface MTASTSValidationResult {
+    /**
+     * Whether the MX hostname is valid according to policy
+     */
+    valid: boolean;
+
+    /**
+     * Policy mode
+     */
+    mode: string;
+
+    /**
+     * Matching policy pattern (if valid)
+     */
+    match?: string;
+
+    /**
+     * Whether policy is in testing mode
+     */
+    testing: boolean;
+}
+
+/**
+ * MTA-STS options
+ */
+export interface MTASTSOptions {
+    /**
+     * Custom DNS resolver function
+     */
+    resolver?: DNSResolver;
+}
+
+// Note: MTA-STS functions (resolvePolicy, fetchPolicy, parsePolicy, validateMx, getPolicy)
+// are not exported from the main module. Import them directly from 'mailauth/lib/mta-sts'.