feat: verify signature from event webhook

.travis.yml

@@ -3,7 +3,6 @@ node_js:
   - 10
 env:
   - version=6
-  - version=7
   - version=8
   - version=10
   - version=lts

package.json

@@ -31,6 +31,7 @@
     "test:helpers": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/helpers/**/*.spec.js\"",
     "test:client": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/client/**/*.spec.js\"",
     "test:mail": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/mail/**/*.spec.js\"",
+    "test:eventwebhook": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/eventwebhook/**/*.spec.js\"",
     "test:inbound": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/inbound-mail-parser/**/*.spec.js\"",
     "test:contact": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"packages/contact-importer/**/*.spec.js\"",
     "test:files": "babel-node ./node_modules/istanbul/lib/cli cover ./node_modules/mocha/bin/_mocha \"test/files.spec.js\"",

packages/client/package.json

@@ -24,7 +24,7 @@
   },
   "main": "index.js",
   "engines": {
-    "node": ">=6.0.0"
+    "node": "6.* || 8.* || >=10.*"
   },
   "dependencies": {
     "@sendgrid/helpers": "^7.0.1",

packages/contact-importer/package.json

@@ -20,7 +20,7 @@
   },
   "main": "src/importer.js",
   "engines": {
-    "node": ">=6.0.0"
+    "node": "6.* || 8.* || >=10.*"
   },
   "publishConfig": {
     "access": "public"

packages/eventwebhook/index.d.ts

@@ -0,0 +1,3 @@
+import EventWebhook = require('./src/eventwebhook');
+
+export = EventWebhook;

packages/eventwebhook/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const EventWebhook = require('./src/eventwebhook');
+
+module.exports = EventWebhook;

packages/eventwebhook/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sendgrid/eventwebhook",
+  "description": "Twilio SendGrid NodeJS Event Webhook",
+  "version": "1.0.0",
+  "author": "Twilio SendGrid <help@twilio.com> (sendgrid.com)",
+  "contributors": [
+    "Elise Shanholtz <eshanholtz@twilio.com>"
+  ],
+  "license": "MIT",
+  "homepage": "https://sendgrid.com",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/sendgrid/sendgrid-nodejs.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/eventwebhook.js",
+  "engines": {
+    "node": "6.* || 8.* || >=10.*"
+  },
+  "dependencies": {
+    "@starkbank/ecdsa": "^0.0.3"
+  },
+  "tags": [
+    "sendgrid"
+  ]
+}

packages/eventwebhook/src/eventwebhook.d.ts

@@ -0,0 +1,22 @@
+import {PublicKey} from "@starkbank/ecdsa";
+
+declare class EventWebhook {
+    /**
+     *
+     * @param {string} publicKey verification key under Mail Settings
+     * @return {PublicKey} A public key using the ECDSA algorithm
+     */
+    convertPublicKeyToECDSA(publicKey: string): PublicKey;
+
+    /**
+     *
+     * @param {PublicKey} publicKey elliptic curve public key
+     * @param {object|string} payload event payload in the request body
+     * @param {string} signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
+     * @param {string} timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
+     * @return {Boolean} true or false if signature is valid
+     */
+    verifySignature(publicKey: PublicKey, payload: object|string, signature: string, timestamp: string): boolean;
+}
+
+export = EventWebhook;

packages/eventwebhook/src/eventwebhook.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const ecdsa = require('@starkbank/ecdsa');
+const Ecdsa = ecdsa.Ecdsa;
+const Signature = ecdsa.Signature;
+const PublicKey = ecdsa.PublicKey;
+
+class EventWebhook {
+  /**
+   *
+   * @param {string} publicKey verification key under Mail Settings
+   * @return {PublicKey} A public key using the ECDSA algorithm
+   */
+  convertPublicKeyToECDSA(publicKey) {
+    return PublicKey.fromPem(publicKey);
+  }
+
+  /**
+   *
+   * @param {PublicKey} publicKey elliptic curve public key
+   * @param {Object|string} payload event payload in the request body
+   * @param {string} signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
+   * @param {string} timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
+   * @return {Boolean} true or false if signature is valid
+   */
+  verifySignature(publicKey, payload, signature, timestamp) {
+    let timestampPayload = typeof payload === 'object' ? JSON.stringify(payload) : payload;
+    timestampPayload = timestamp + timestampPayload;
+    const decodedSignature = Signature.fromBase64(signature);
+
+    return Ecdsa.verify(timestampPayload, decodedSignature, publicKey);
+  }
+}
+
+module.exports = EventWebhook;

packages/eventwebhook/src/eventwebhook.spec.js

@@ -0,0 +1,65 @@
+const EventWebhook = require('./eventwebhook');
+
+describe('EventWebhook', () => {
+  const PUBLIC_KEY = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==';
+  const SIGNATURE = 'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=';
+  const TIMESTAMP = '1588788367';
+  const PAYLOAD = {
+    event: 'test_event',
+    category: 'example_payload',
+    message_id: 'message_id',
+  };
+
+  describe('#verifySignature()', () => {
+    it('should verify a valid signature', () => {
+      expect(verify(
+        PUBLIC_KEY,
+        PAYLOAD,
+        SIGNATURE,
+        TIMESTAMP
+      )).to.be.true;
+    });
+
+    it('should reject for invalid key', () => {
+      expect(verify(
+        'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqTxd43gyp8IOEto2LdIfjRQrIbsd4SXZkLW6jDutdhXSJCWHw8REntlo7aNDthvj+y7GjUuFDb/R1NGe1OPzpA==',
+        PAYLOAD,
+        SIGNATURE,
+        TIMESTAMP
+      )).to.be.false;
+    });
+
+    it('should reject for bad payload', () => {
+      expect(verify(
+        PUBLIC_KEY,
+        'payload',
+        SIGNATURE,
+        TIMESTAMP
+      )).to.be.false;
+    });
+
+    it('should reject for bad signature', () => {
+      expect(verify(
+        PUBLIC_KEY,
+        PAYLOAD,
+        'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH3j/0=',
+        TIMESTAMP
+      )).to.be.false;
+    });
+
+    it('should reject for bad timestamp', () => {
+      expect(verify(
+        PUBLIC_KEY,
+        PAYLOAD,
+        SIGNATURE,
+        'timestamp'
+      )).to.be.false;
+    });
+  });
+});
+
+function verify(publicKey, payload, signature, timestamp) {
+  const ew = new EventWebhook();
+  const key = ew.convertPublicKeyToECDSA(publicKey);
+  return ew.verifySignature(key, payload, signature, timestamp);
+}

packages/inbound-mail-parser/package.json

@@ -23,7 +23,7 @@
   },
   "main": "src/parser.js",
   "engines": {
-    "node": ">=6.0.0"
+    "node": "6.* || 8.* || >=10.*"
   },
   "dependencies": {
     "@sendgrid/helpers": "^7.0.1",

packages/mail/package.json

@@ -21,7 +21,7 @@
   },
   "main": "index.js",
   "engines": {
-    "node": ">=6.0.0"
+    "node": "6.* || 8.* || >=10.*"
   },
   "publishConfig": {
     "access": "public"

packages/subscription-widget/package.json

@@ -21,6 +21,6 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=6.0.0"
+    "node": "6.* || 8.* || >=10.*"
   }
 }

test/typescript/eventwebhook.ts

@@ -0,0 +1,13 @@
+import EventWebhook = require('@sendgrid/eventwebhook');
+
+var ew = new EventWebhook();
+const PUBLIC_KEY = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==";
+const SIGNATURE = "MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=";
+const TIMESTAMP = "1588788367";
+const PAYLOAD = {
+    event: 'test_event',
+    category: 'example_payload',
+    message_id: 'message_id',
+};
+var key = ew.convertPublicKeyToECDSA(PUBLIC_KEY);
+console.log(ew.verifySignature(key, PAYLOAD, SIGNATURE, TIMESTAMP));