mailauth 3.0.0 → 3.0.3

package/README.md

@@ -10,10 +10,10 @@
 -   ARC sealing
     -   Sealing on authentication
     -   Sealing after modifications
--   **BIMI** resolving
+-   **BIMI** resolving and **VMC** validation
 -   **MTA-STS** helpers
 
-Pure JavaScript implementation, no external applications or compilation needed. It runs on any server/device that has Node 14+ installed.
+Pure JavaScript implementation, no external applications or compilation needed. It runs on any server/device that has Node 16+ installed.
 
 ## Command line usage
 

package/bin/mailauth.js

@@ -294,18 +294,25 @@ const argv = yargs(hideBin(process.argv))
         ['vmc'],
         'Validate VMC logo',
         yargs => {
-            yargs.option('authorityFile', {
-                alias: 'f',
-                type: 'string',
-                description: 'Path to a VMC file',
-                demandOption: false
-            });
-            yargs.option('authority', {
-                alias: 'a',
-                type: 'string',
-                description: 'URL to a VMC file',
-                demandOption: false
-            });
+            yargs
+                .option('authorityPath', {
+                    alias: 'p',
+                    type: 'string',
+                    description: 'Path to a VMC file',
+                    demandOption: false
+                })
+                .option('authority', {
+                    alias: 'a',
+                    type: 'string',
+                    description: 'URL to a VMC file',
+                    demandOption: false
+                })
+                .option('domain', {
+                    alias: 'd',
+                    type: 'string',
+                    description: 'Sending domain to validate',
+                    demandOption: false
+                });
         },
         argv => {
             commandVmc(argv)

package/cli.md

@@ -1,3 +1,7 @@
+![](https://github.com/postalsys/mailauth/raw/master/assets/mailauth.png)
+
+Command line utility and a [Node.js library](README.md) for email authentication.
+
 # CLI USAGE
 
 ## TOC
@@ -22,14 +26,6 @@ Download `mailauth` for your platform:
 -   [Windows](https://github.com/postalsys/mailauth/releases/latest/download/mailauth.exe)
 -   Or install from the NPM registry: `npm install -g mailauth`
 
-> **NB!** Downloadable files are quite large because these are packaged Node.js applications
-
-Alternatively you can install `mailauth` from [npm](https://npmjs.com/package/mailauth).
-
-```
-npm install -g mailauth
-```
-
 ## Help
 
 ```
@@ -224,25 +220,24 @@ Where
 **Options**
 
 -   `--authority <url>` or `-a <url>` is the URL for the VMC resource
--   `--authorityFile <path>` or `-f <path>` is the cached file for the authority URL to avoid network requests
+-   `--authorityPath <path>` or `-p <path>` is the cached file for the authority URL to avoid network requests
+-   `--domain <domain>` or `-d <domain>` is the sender domain to compare the certificate against
 
 **Example**
 
 ```
-$ mailauth vmc -a https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.pem
+$ mailauth vmc -a https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.pem -d cnn.com
 {
   "url": "https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.pem",
   "success": true,
+  "domainVerified": true,
   "vmc": {
     "mediaType": "image/svg+xml",
     "hashAlgo": "sha1",
     "hashValue": "ea8c81da633c66a16262134a78576cdf067638e9",
-    "logoFile": "PD94bWwgdmVyc...",
+    "logoFile": "<2300B base64 encoded file>",
     "validHash": true,
     "certificate": {
-      "subjectAltName": [
-        "cnn.com"
-      ],
       "subject": {
         "businessCategory": "Private Organization",
         "jurisdictionCountryName": "US",
@@ -257,8 +252,13 @@ $ mailauth vmc -a https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.
         "trademarkCountryOrRegionName": "US",
         "trademarkRegistration": "5817930"
       },
+      "subjectAltName": [
+        "cnn.com"
+      ],
       "fingerprint": "17:B3:94:97:E6:6B:C8:6B:33:B8:0A:D2:F0:79:6B:08:A2:A6:84:BD",
       "serialNumber": "0821B8FE0A9CBC3BAC10DA08C088EEF4",
+      "validFrom": "2021-08-12T00:00:00.000Z",
+      "validTo": "2022-08-12T23:59:59.000Z",
       "issuer": {
         "countryName": "US",
         "organizationName": "DigiCert, Inc.",
@@ -269,26 +269,55 @@ $ mailauth vmc -a https://amplify.valimail.com/bimi/time-warner/yV3KRIg4nJW-cnn.
 }
 ```
 
-If the certificate verification fails, then the contents are not returned.
+If the certificate verification fails, then the logo contents are not returned.
 
 ```
-$ mailauth vmc -f /path/to/random/cert-bundle.pem
+$ mailauth vmc -p /path/to/random/cert-bundle.pem
 {
   "success": false,
   "error": {
     "message": "Self signed certificate in certificate chain",
     "details": {
-      "subject": "CN=catchall.delivery",
-      "fingerprint": "35:EF:C9:9A:52:D5:A9:94:00:68:C6:D4:17:F1:26:61:01:0F:70:6D",
-      "fingerprint235": "09:AB:0F:6B:F5:4F:16:58:F8:94:80:DE:E2:1A:D1:47:CC:64:F2:BF:63:E7:73:E4:02:F9:D3:C3:F6:9E:CC:86",
-      "validFrom": "Jul  6 23:10:49 2022 GMT",
-      "validTo": "Oct  4 23:10:48 2022 GMT"
+      "certificate": {
+        "subject": {
+          "commonName": "postal.vmc.local",
+          "organizationName": "Postal Systems OU.",
+          "countryName": "EE"
+        },
+        "subjectAltName": [],
+        "fingerprint": "CC:49:83:ED:3F:6B:77:45:5B:A5:3B:9E:EC:99:0E:A1:EF:D7:FF:97",
+        "serialNumber": "B61FBFBA917B15D9",
+        "validFrom": "2022-07-09T06:13:33.000Z",
+        "validTo": "2023-07-09T06:13:33.000Z",
+        "issuer": {
+          "commonName": "postal.vmc.local",
+          "organizationName": "Postal Systems OU.",
+          "countryName": "EE"
+        }
+      }
     },
     "code": "SELF_SIGNED_CERT_IN_CHAIN"
   }
 }
 ```
 
+The embedded SVG file is also validated.
+
+```
+$ mailauth vmc -p /path/to/vmc-with-invalid-svg.pem
+{
+  "success": false,
+  "error": {
+    "message": "VMC logo SVG validation failed",
+    "details": {
+      "message": "Not a Tiny PS profile",
+      "code": "INVALID_BASE_PROFILE"
+    },
+    "code": "SVG_VALIDATION_FAILED"
+  }
+}
+```
+
 ### license
 
 Display licenses for `mailauth` and included modules.

package/lib/bimi/index.js

@@ -2,7 +2,7 @@
 
 const crypto = require('crypto');
 const dns = require('dns');
-const { formatAuthHeaderRow, parseDkimHeaders } = require('../tools');
+const { formatAuthHeaderRow, parseDkimHeaders, formatDomain, getAlignment } = require('../tools');
 const Joi = require('joi');
 const packageData = require('../../package.json');
 const httpsSchema = Joi.string().uri({
@@ -12,6 +12,7 @@ const httpsSchema = Joi.string().uri({
 const https = require('https');
 const http = require('http');
 const { vmc } = require('@postalsys/vmc');
+const { validateSvg } = require('./validate-svg');
 
 const lookup = async data => {
     let { dmarc, headers, resolver } = data;
@@ -244,26 +245,30 @@ const validateVMC = async bimiData => {
         return false;
     }
 
+    let selector = bimiData?.status?.header?.selector;
+    let d = bimiData?.status?.header?.d;
+
     let promises = [];
 
-    promises.push(downloadPromise(bimiData.location, bimiData.locationFile));
-    promises.push(downloadPromise(bimiData.authority, bimiData.authorityFile));
+    promises.push(downloadPromise(bimiData.location, bimiData.locationPath));
+    promises.push(downloadPromise(bimiData.authority, bimiData.authorityPath));
 
     if (!promises.length) {
         return false;
     }
 
-    let results = await Promise.allSettled(promises);
+    let [{ reason: locationError, value: locationValue, status: locationStatus }, { reason: authorityError, value: authorityValue, status: authorityStatus }] =
+        await Promise.allSettled(promises);
 
     let result = {};
-    if (results[0].value || results[0].reason) {
+    if (locationValue || locationError) {
         result.location = {
             url: bimiData.location,
-            success: results[0].status === 'fulfilled'
+            success: locationStatus === 'fulfilled'
         };
 
-        if (results[0].reason) {
-            let err = results[0].reason;
+        if (locationError) {
+            let err = locationError;
             result.location.error = { message: err.message };
             if (err.redirect) {
                 result.location.error.redirect = err.redirect;
@@ -274,18 +279,18 @@ const validateVMC = async bimiData => {
         }
 
         if (result.location.success) {
-            result.location.logoFile = results[0].value.toString('base64');
+            result.location.logoFile = locationValue.toString('base64');
         }
     }
 
-    if (results[1].value || results[1].reason) {
+    if (authorityValue || authorityError) {
         result.authority = {
             url: bimiData.authority,
-            success: results[1].status === 'fulfilled'
+            success: authorityStatus === 'fulfilled'
         };
 
-        if (results[1].reason) {
-            let err = results[1].reason;
+        if (authorityError) {
+            let err = authorityError;
             result.authority.error = { message: err.message };
             if (err.redirect) {
                 result.authority.error.redirect = err.redirect;
@@ -295,9 +300,90 @@ const validateVMC = async bimiData => {
             }
         }
 
-        if (results[1].value) {
+        if (authorityValue) {
             try {
-                result.authority.vmc = await vmc(results[1].value);
+                let vmcData = await vmc(authorityValue);
+
+                if (!vmcData.logoFile) {
+                    let error = new Error('VMC does not contain a log file');
+                    error.code = 'MISSING_VMC_LOGO';
+                    throw error;
+                }
+
+                if (vmcData?.mediaType?.toLowerCase() !== 'image/svg+xml') {
+                    let error = new Error('Invalid media type for the logo file');
+                    error.details = {
+                        mediaType: vmcData.mediaType
+                    };
+                    error.code = 'INVALID_MEDIATYPE';
+                    throw error;
+                }
+
+                if (!vmcData.validHash) {
+                    let error = new Error('VMC hash does not match logo file');
+                    error.details = {
+                        hashAlgo: vmcData.hashAlgo,
+                        hashValue: vmcData.hashValue,
+                        logoFile: vmcData.logoFile
+                    };
+                    error.code = 'INVALID_LOGO_HASH';
+                    throw error;
+                }
+
+                // throws on invalid logo file
+                try {
+                    validateSvg(Buffer.from(vmcData.logoFile, 'base64'));
+                } catch (err) {
+                    let error = new Error('VMC logo SVG validation failed');
+                    error.details = Object.assign(
+                        {
+                            message: err.message
+                        },
+                        error.details || {},
+                        err.code ? { code: err.code } : {}
+                    );
+                    error.code = 'SVG_VALIDATION_FAILED';
+                    throw error;
+                }
+
+                if (d) {
+                    // validate domain
+                    let selectorSet = [];
+                    let domainSet = [];
+                    vmcData?.certificate?.subjectAltName?.map(formatDomain)?.forEach(domain => {
+                        if (/\b_bimi\./.test(domain)) {
+                            selectorSet.push(domain);
+                        } else {
+                            domainSet.push(domain);
+                        }
+                    });
+
+                    let domainVerified = false;
+
+                    if (selector && selectorSet.includes(formatDomain(`${selector}._bimi.${d}`))) {
+                        domainVerified = true;
+                    } else {
+                        let alignedDomain = getAlignment(d, domainSet, false);
+                        if (alignedDomain) {
+                            domainVerified = true;
+                        }
+                    }
+
+                    if (!domainVerified) {
+                        let error = new Error('Domain can not be verified');
+                        error.details = {
+                            subjectAltName: vmcData?.certificate?.subjectAltName,
+                            selector,
+                            d
+                        };
+                        error.code = 'VMC_DOMAIN_MISMATCH';
+                        throw error;
+                    } else {
+                        result.authority.domainVerified = true;
+                    }
+                }
+
+                result.authority.vmc = vmcData;
             } catch (err) {
                 result.authority.success = false;
                 result.authority.error = { message: err.message };
@@ -313,7 +399,7 @@ const validateVMC = async bimiData => {
         if (result.location && result.location.success && result.authority.success) {
             try {
                 if (result.location.success && result.authority.vmc.hashAlgo && result.authority.vmc.validHash) {
-                    let hash = crypto.createHash(result.authority.vmc.hashAlgo).update(results[0].value).digest('hex');
+                    let hash = crypto.createHash(result.authority.vmc.hashAlgo).update(locationValue).digest('hex');
                     result.location.hashAlgo = result.authority.vmc.hashAlgo;
                     result.location.hashValue = hash;
                     result.authority.hashMatch = hash === result.authority.vmc.hashValue;

package/lib/bimi/validate-svg.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const { XMLParser } = require('fast-xml-parser');
+
+function validateSvg(logo) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: '@_'
+    });
+
+    let logoObj;
+    try {
+        logoObj = parser.parse(logo);
+        if (!logoObj) {
+            throw new Error('Emtpy file');
+        }
+    } catch (err) {
+        let error = new Error('Invalid SVG file');
+        error._err = err;
+        error.code = 'INVALID_XML_FILE';
+        throw error;
+    }
+
+    if (!logoObj.svg) {
+        let error = new Error('Invalid SVG file');
+        error.code = 'INVALID_SVG_FILE';
+        throw error;
+    }
+
+    if (logoObj.svg['@_baseProfile'] !== 'tiny-ps') {
+        let error = new Error('Not a Tiny PS profile');
+        error.code = 'INVALID_BASE_PROFILE';
+        throw error;
+    }
+
+    if (!logoObj.svg.title) {
+        let error = new Error('Logo file is missing title');
+        error.code = 'LOGO_MISSING_TITLE';
+        throw error;
+    }
+
+    if ('@_x' in logoObj.svg || '@_y' in logoObj.svg) {
+        let error = new Error('Logo root includes x/y attributes');
+        error.code = 'LOGO_INVALID_ROOT_ATTRS';
+        throw error;
+    }
+
+    let walkElm = (node, name, path) => {
+        if (!node) {
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (let entry of node) {
+                walkElm(entry, name, path + '.' + name + '[]');
+            }
+        } else if (typeof node === 'object') {
+            if (node['@_xlink:href'] && !/^#/.test(node['@_xlink:href'])) {
+                let error = new Error('External reference found from file');
+                error.details = {
+                    element: name,
+                    link: node['@_xlink:href'],
+                    path
+                };
+                error.code = 'LOGO_INCLUDES_REFERENCE';
+                throw error;
+            }
+
+            for (let key of Object.keys(node)) {
+                if (['script', 'animate', 'animatemotion', 'animatetransform', 'discard', 'set'].includes(key.toLowerCase())) {
+                    let error = new Error('Unallowed element found from file');
+                    error.details = {
+                        element: key,
+                        path: path + '.' + key
+                    };
+                    error.code = 'LOGO_INVALID_ELEMENT';
+                    throw error;
+                }
+
+                if (Array.isArray(node[key])) {
+                    for (let entry of node[key]) {
+                        walkElm(entry, key, path + '.' + key + '[]');
+                    }
+                } else if (node[key] && typeof node[key] === 'object') {
+                    walkElm(node[key], key, path + '.' + key);
+                }
+            }
+        }
+    };
+
+    walkElm(logoObj, 'root', '');
+
+    // all validations passed
+    return true;
+}
+
+module.exports = { validateSvg };

package/lib/commands/vmc.js

@@ -6,13 +6,18 @@ const fs = require('fs').promises;
 
 const cmd = async argv => {
     let bimiData = {};
-    if (argv.authorityFile) {
-        bimiData.authorityFile = await fs.readFile(argv.authorityFile);
+    if (argv.authorityPath) {
+        bimiData.authorityPath = await fs.readFile(argv.authorityPath);
     }
+
     if (argv.authority) {
         bimiData.authority = argv.authority;
     }
 
+    if (argv.domain) {
+        bimiData.status = { header: { d: argv.domain } };
+    }
+
     const result = await validateVMC(bimiData);
     process.stdout.write(JSON.stringify(result.authority, false, 2) + '\n');
 };

package/lib/mailauth.js

@@ -5,6 +5,7 @@ const { spf } = require('./spf');
 const { dmarc } = require('./dmarc');
 const { arc, createSeal } = require('./arc');
 const { bimi, validateVMC: validateBimiVmc } = require('./bimi');
+const { validateSvg: validateBimiSvg } = require('./bimi/validate-svg');
 const { parseReceived } = require('./parse-received');
 const { sealMessage } = require('./arc');
 const libmime = require('libmime');
@@ -180,4 +181,9 @@ const authenticate = async (input, opts) => {
     };
 };
 
-module.exports = { authenticate, sealMessage, validateBimiVmc };
+module.exports = {
+    authenticate,
+    sealMessage,
+    validateBimiVmc,
+    validateBimiSvg
+};

package/lib/tools.js

@@ -490,5 +490,6 @@ module.exports = {
 
     getAlignment,
 
-    formatRelaxedLine
+    formatRelaxedLine,
+    formatDomain
 };

package/licenses.txt

@@ -1,11 +1,12 @@
-name        license type               link                                              installed version  author
-----        ------------               ----                                              -----------------  ------
-@fidm/x509  MIT                        git+ssh://git@github.com/fidm/x509.git            1.2.1
-ipaddr.js   MIT                        git://github.com/whitequark/ipaddr.js.git         2.0.1              whitequark whitequark@whitequark.org
-joi         BSD-3-Clause               git://github.com/sideway/joi.git                  17.6.0
-libmime     MIT                        git://github.com/andris9/libmime.git              5.1.0              Andris Reinman andris@kreata.ee
-node-forge  (BSD-3-Clause OR GPL-2.0)  git+https://github.com/digitalbazaar/forge.git    1.3.1              Digital Bazaar, Inc. support@digitalbazaar.com http://digitalbazaar.com/
-nodemailer  MIT                        git+https://github.com/nodemailer/nodemailer.git  6.7.5              Andris Reinman
-psl         MIT                        git+ssh://git@github.com/lupomontero/psl.git      1.8.0              Lupo Montero lupomontero@gmail.com https://lupomontero.com/
-punycode    MIT                        git+https://github.com/bestiejs/punycode.js.git   2.1.1              Mathias Bynens https://mathiasbynens.be/
-yargs       MIT                        git+https://github.com/yargs/yargs.git            17.5.1
+name             license type               link                                                            installed version  author
+----             ------------               ----                                                            -----------------  ------
+@postalsys/vmc   MIT                        https://registry.npmjs.org/@postalsys/vmc/-/vmc-1.0.4.tgz       1.0.4              Postal Systems OÜ
+fast-xml-parser  MIT                        git+https://github.com/NaturalIntelligence/fast-xml-parser.git  4.0.9              Amit Gupta https://amitkumargupta.work/
+ipaddr.js        MIT                        git://github.com/whitequark/ipaddr.js.git                       2.0.1              whitequark whitequark@whitequark.org
+joi              BSD-3-Clause               git://github.com/sideway/joi.git                                17.6.0
+libmime          MIT                        git://github.com/andris9/libmime.git                            5.1.0              Andris Reinman andris@kreata.ee
+node-forge       (BSD-3-Clause OR GPL-2.0)  git+https://github.com/digitalbazaar/forge.git                  1.3.1              Digital Bazaar, Inc. support@digitalbazaar.com http://digitalbazaar.com/
+nodemailer       MIT                        git+https://github.com/nodemailer/nodemailer.git                6.7.7              Andris Reinman
+psl              MIT                        git+ssh://git@github.com/lupomontero/psl.git                    1.9.0              Lupo Montero lupomontero@gmail.com https://lupomontero.com/
+punycode         MIT                        git+https://github.com/bestiejs/punycode.js.git                 2.1.1              Mathias Bynens https://mathiasbynens.be/
+yargs            MIT                        git+https://github.com/yargs/yargs.git                          17.5.1

package/man/mailauth.1

@@ -1,4 +1,4 @@
-.TH "MAILAUTH" "1" "July 2022" "v2.3.4" "Mailauth Help"
+.TH "MAILAUTH" "1" "July 2022" "v3.0.2" "Mailauth Help"
 .SH "NAME"
 \fBmailauth\fR
 .QP

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mailauth",
-    "version": "3.0.0",
+    "version": "3.0.3",
     "description": "Email authentication library for Node.js",
     "main": "lib/mailauth.js",
     "scripts": {
@@ -33,7 +33,7 @@
     "homepage": "https://github.com/postalsys/mailauth",
     "devDependencies": {
         "chai": "4.3.6",
-        "eslint": "8.19.0",
+        "eslint": "8.20.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.5.0",
         "js-yaml": "4.1.0",
@@ -42,11 +42,11 @@
         "marked-man": "0.7.0",
         "mbox-reader": "1.1.5",
         "mocha": "10.0.0",
-        "pkg": "5.7.0"
+        "pkg": "5.8.0"
     },
     "dependencies": {
-        "@fidm/x509": "1.2.1",
-        "@postalsys/vmc": "1.0.1",
+        "@postalsys/vmc": "1.0.5",
+        "fast-xml-parser": "4.0.9",
         "ipaddr.js": "2.0.1",
         "joi": "17.6.0",
         "libmime": "5.1.0",