mailauth 7.2.0 → 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'>;
 }
 
 /**
@@ -852,6 +870,11 @@ export interface AuthenticateResult {
      */
     dkim: DKIMVerifyResult;
 
+    /**
+     * DKIM2 verification result, false unless the `dkim2` option is set
+     */
+    dkim2: DKIM2VerifyResult | false;
+
     /**
      * SPF verification result
      */
@@ -1318,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
 // ============================================================================

package/lib/commands/dkim2-hash.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { dkim2Hash } = require('../dkim2/hash');
+const fs = require('node:fs');
+
+const cmd = async argv => {
+    let source = argv.email;
+    if (argv.verbose) {
+        console.error(`Reading email message from ${source || 'standard input'}`);
+    }
+
+    let { headers, hashes } = await dkim2Hash(source ? fs.createReadStream(source) : process.stdin, { algorithms: argv.algo });
+
+    if (argv.verbose) {
+        console.error(`Hashed header fields: ${headers.join(', ') || '(none)'}`);
+        console.error('--------');
+    }
+
+    // the hash-sets of the h= tag of a Message-Instance (section 7.3)
+    for (let { algorithm, headerHash, bodyHash } of hashes) {
+        process.stdout.write(`${algorithm}:${headerHash}:${bodyHash}\n`);
+    }
+};
+
+module.exports = cmd;

package/lib/commands/dkim2-sign.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { dkim2Sign } = require('../dkim2/sign');
+const { GathererStream } = require('../gatherer-stream');
+const fs = require('node:fs');
+
+const cmd = async argv => {
+    let source = argv.email;
+    let stream;
+
+    if (argv.verbose) {
+        console.error(`Reading email message from ${source || 'standard input'}`);
+    }
+
+    stream = source ? fs.createReadStream(source) : process.stdin;
+
+    let privateKeys = argv.privateKey || [];
+    let selectors = argv.selector || [];
+    if (privateKeys.length !== selectors.length) {
+        let err = new Error('Every --private-key needs a --selector, in the same order');
+        throw err;
+    }
+
+    let gatherer = new GathererStream({ gather: !argv.headersOnly });
+    stream.pipe(gatherer);
+    stream.on('error', err => gatherer.emit('error', err));
+
+    let signatureData = [];
+    for (let i = 0; i < privateKeys.length; i++) {
+        signatureData.push({ selector: selectors[i], privateKey: await fs.promises.readFile(privateKeys[i], 'utf-8') });
+    }
+
+    let options = {
+        signingDomain: argv.domain,
+        signatureData,
+        signTime: argv.time ? new Date(argv.time * 1000) : new Date(),
+        flags: argv.flag,
+        nonce: argv.nonce
+    };
+
+    if (argv.hash?.length) {
+        options.hashAlgorithms = argv.hash;
+    }
+
+    if (argv.nextDomain) {
+        options.nextDomain = argv.nextDomain;
+    } else {
+        options.mailFrom = argv.mailFrom;
+        options.rcptTo = argv.rcptTo;
+    }
+
+    if (argv.recipe) {
+        options.recipe = JSON.parse(await fs.promises.readFile(argv.recipe, 'utf-8'));
+    }
+
+    if (argv.verbose) {
+        console.error(`Signing domain: ${options.signingDomain}`);
+        console.error(`Selectors:      ${selectors.join(', ')}`);
+        console.error(`Signing time:   ${options.signTime.toISOString()}`);
+        console.error('--------');
+    }
+
+    let signResult = await dkim2Sign(gatherer, options);
+
+    process.stdout.write(signResult.signatures);
+    if (!argv.headersOnly) {
+        // print the full message as well
+        await new Promise((resolve, reject) => {
+            let msgStream = gatherer.replay();
+            msgStream.pipe(process.stdout, { end: false });
+            msgStream.on('end', resolve);
+            msgStream.on('error', reject);
+        });
+    }
+};
+
+module.exports = cmd;

package/lib/commands/dkim2-verify.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { dkim2Verify } = require('../dkim2/verify');
+const { createResolver } = require('./resolver');
+const fs = require('node:fs');
+
+const cmd = async argv => {
+    let source = argv.email;
+
+    if (argv.verbose) {
+        console.error(`Reading email message from ${source || 'standard input'}`);
+    }
+
+    let stream = source ? fs.createReadStream(source) : process.stdin;
+
+    let opts = {
+        resolver: await createResolver(argv),
+        rcptTo: argv.rcptTo
+    };
+
+    if (typeof argv.mailFrom === 'string') {
+        opts.mailFrom = argv.mailFrom;
+    }
+
+    if (typeof argv.time === 'number') {
+        opts.curTime = new Date(argv.time * 1000);
+    }
+
+    if (typeof argv.maxAge === 'number') {
+        // 0 turns the expiration check off
+        opts.maxSignatureAge = argv.maxAge || false;
+    }
+
+    if (typeof argv.maxFuture === 'number') {
+        // 0 turns the check off, like --max-age
+        opts.maxFutureTime = argv.maxFuture || false;
+    }
+
+    if (typeof argv.maxInstances === 'number') {
+        opts.maxInstances = argv.maxInstances;
+    }
+
+    let result = await dkim2Verify(stream, opts);
+
+    if (argv.verbose) {
+        for (let warning of result.status.warnings || []) {
+            console.error(`Warning: ${warning}`);
+        }
+    }
+
+    if (argv.headersOnly) {
+        process.stdout.write(result.info + '\n');
+        return;
+    }
+
+    process.stdout.write(JSON.stringify(result, false, 2) + '\n');
+};
+
+module.exports = cmd;

package/lib/commands/report.js

@@ -2,7 +2,7 @@
 
 const { authenticate } = require('../mailauth');
 const fs = require('node:fs');
-const { resolve } = require('node:dns').promises;
+const { createResolver } = require('./resolver');
 
 const cmd = async argv => {
     let source = argv.email;
@@ -27,9 +27,14 @@ const cmd = async argv => {
     const opts = {
         trustReceived: true,
         strict: !!argv.strict,
-        rejectRsaSha1: !!argv.rejectRsaSha1
+        rejectRsaSha1: !!argv.rejectRsaSha1,
+        dkim2: !!argv.dkim2
     };
 
+    if (argv.rcptTo) {
+        opts.rcptTo = argv.rcptTo;
+    }
+
     if (argv.clientIp) {
         opts.ip = argv.clientIp;
     }
@@ -48,37 +53,7 @@ const cmd = async argv => {
         }
     }
 
-    if (argv.dnsCache) {
-        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
-
-        opts.resolver = async (name, rr) => {
-            let match = dnsCache?.[name]?.[rr];
-
-            if (argv.verbose) {
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
-            }
-
-            if (!match) {
-                let err = new Error('Error');
-                err.code = 'ENOTFOUND';
-                throw err;
-            }
-
-            return match;
-        };
-    } else if (argv.verbose) {
-        opts.resolver = async (name, rr) => {
-            let match;
-            try {
-                match = await resolve(name, rr);
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
-                return match;
-            } catch (err) {
-                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
-                throw err;
-            }
-        };
-    }
+    opts.resolver = await createResolver(argv);
 
     let result = await authenticate(stream, opts);
     process.stdout.write(JSON.stringify(result, false, 2) + '\n');

package/lib/commands/resolver.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const fs = require('node:fs');
+const { resolve } = require('node:dns').promises;
+
+/**
+ * The DNS resolver for a command: answers from the --dns-cache file, or real DNS queries that are
+ * logged with --verbose. Undefined when neither is set, so the library uses its default resolver
+ *
+ * @param {Object} argv Command options
+ * @returns {Function|undefined} async (name, rrtype) resolver
+ */
+const createResolver = async argv => {
+    if (argv.dnsCache) {
+        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
+
+        return async (name, rr) => {
+            let match = dnsCache?.[name]?.[rr];
+
+            if (argv.verbose) {
+                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
+            }
+
+            if (!match) {
+                let err = new Error('Error');
+                err.code = 'ENOTFOUND';
+                throw err;
+            }
+
+            return match;
+        };
+    }
+
+    if (argv.verbose) {
+        return async (name, rr) => {
+            let match;
+            try {
+                match = await resolve(name, rr);
+                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
+                return match;
+            } catch (err) {
+                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
+                throw err;
+            }
+        };
+    }
+
+    return undefined;
+};
+
+module.exports = { createResolver };

package/lib/commands/seal.js

@@ -5,7 +5,7 @@ const { authenticate } = require('../mailauth');
 const { createSeal } = require('../arc');
 const fs = require('node:fs');
 const { GathererStream } = require('../gatherer-stream');
-const { resolve } = require('node:dns').promises;
+const { createResolver } = require('./resolver');
 
 const writeMessageBody = async gatherer =>
     new Promise((resolve, reject) => {
@@ -161,37 +161,7 @@ const cmd = async argv => {
         }
     }
 
-    if (argv.dnsCache) {
-        let dnsCache = JSON.parse(await fs.promises.readFile(argv.dnsCache, 'utf-8'));
-
-        opts.resolver = async (name, rr) => {
-            let match = dnsCache?.[name]?.[rr];
-
-            if (argv.verbose) {
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'} (using cache)`);
-            }
-
-            if (!match) {
-                let err = new Error('Error');
-                err.code = 'ENOTFOUND';
-                throw err;
-            }
-
-            return match;
-        };
-    } else if (argv.verbose) {
-        opts.resolver = async (name, rr) => {
-            let match;
-            try {
-                match = await resolve(name, rr);
-                console.error(`DNS query for ${rr} ${name}: ${match ? JSON.stringify(match) : 'not found'}`);
-                return match;
-            } catch (err) {
-                console.error(`DNS query for ${rr} ${name}: ${err.message}${err.code ? ` [${err.code}]` : ''}`);
-                throw err;
-            }
-        };
-    }
+    opts.resolver = await createResolver(argv);
 
     let result = await authenticate(gatherer, opts);