twilio 4.6.0 → 4.7.0

package/lib/webhooks/webhooks.d.ts

@@ -0,0 +1,136 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingHttpHeaders } from "http2";
+export interface Request {
+    protocol: string;
+    header(name: string): string | undefined;
+    headers: IncomingHttpHeaders;
+    originalUrl: string;
+    rawBody?: any;
+    body: any;
+}
+export interface RequestValidatorOptions {
+    /**
+     * The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
+     */
+    url?: string;
+    /**
+     * Manually specify the host name used by Twilio in a number's webhook config
+     */
+    host?: string;
+    /**
+     * Manually specify the protocol used by Twilio in a number's webhook config
+     */
+    protocol?: string;
+}
+export interface WebhookOptions {
+    /**
+     * Whether or not the middleware should validate the request
+     * came from Twilio.  Default true. If the request does not originate from
+     * Twilio, we will return a text body and a 403.  If there is no configured
+     * auth token and validate=true, this is an error condition, so we will return
+     * a 500.
+     */
+    validate?: boolean;
+    /**
+     * Add helpers to the response object to improve support for XML (TwiML) rendering.  Default true.
+     */
+    includeHelpers?: boolean;
+    /**
+     * The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
+     */
+    url?: string;
+    /**
+     * Manually specify the host name used by Twilio in a number's webhook config
+     */
+    host?: string;
+    /**
+     * Manually specify the protocol used by Twilio in a number's webhook config
+     */
+    protocol?: string;
+    /**
+     * Authentication token
+     */
+    authToken?: string;
+}
+/**
+ Utility function to get the expected signature for a given request
+
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param url - The full URL (with query string) you configured to handle
+ this request
+ @param params - the parameters sent with this request
+ @returns signature
+ */
+export declare function getExpectedTwilioSignature(authToken: string, url: string, params: Record<string, any>): string;
+/**
+ Utility function to get the expected body hash for a given request's body
+
+ @param body - The plain-text body of the request
+ */
+export declare function getExpectedBodyHash(body: string): string;
+/**
+ Utility function to validate an incoming request is indeed from Twilio
+
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param twilioHeader - The value of the X-Twilio-Signature header from the request
+ @param url - The full URL (with query string) you configured to handle this request
+ @param params - the parameters sent with this request
+ @returns valid
+ */
+export declare function validateRequest(authToken: string, twilioHeader: string, url: string, params: Record<string, any>): boolean;
+export declare function validateBody(body: string, bodyHash: any[] | string | Buffer): boolean;
+/**
+ Utility function to validate an incoming request is indeed from Twilio. This also validates
+ the request body against the bodySHA256 post parameter.
+
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param twilioHeader - The value of the X-Twilio-Signature header from the request
+ @param url - The full URL (with query string) you configured to handle this request
+ @param body - The body of the request
+ @returns valid
+ */
+export declare function validateRequestWithBody(authToken: string, twilioHeader: string, url: string, body: string): boolean;
+/**
+ Utility function to validate an incoming request is indeed from Twilio.
+ adapted from https://github.com/crabasa/twiliosig
+
+ @param request - A request object (based on Express implementation http://expressjs.com/api.html#req.params)
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param opts - options for request validation:
+    -> url: The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
+    -> host: manually specify the host name used by Twilio in a number's webhook config
+    -> protocol: manually specify the protocol used by Twilio in a number's webhook config
+ */
+export declare function validateIncomingRequest(request: Request, authToken: string, opts?: RequestValidatorOptions): boolean;
+export declare function validateExpressRequest(request: Request, authToken: string, opts?: RequestValidatorOptions): boolean;
+/**
+Express middleware to accompany a Twilio webhook. Provides Twilio
+request validation, and makes the response a little more friendly for our
+TwiML generator.  Request validation requires the express.urlencoded middleware
+to have been applied (e.g. app.use(express.urlencoded()); in your app config).
+
+Options:
+- validate: {Boolean} whether or not the middleware should validate the request
+    came from Twilio.  Default true. If the request does not originate from
+    Twilio, we will return a text body and a 403.  If there is no configured
+    auth token and validate=true, this is an error condition, so we will return
+    a 500.
+- host: manually specify the host name used by Twilio in a number's webhook config
+- protocol: manually specify the protocol used by Twilio in a number's webhook config
+- url: The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
+
+Returns a middleware function.
+
+Examples:
+var webhookMiddleware = twilio.webhook();
+var webhookMiddleware = twilio.webhook('asdha9dhjasd'); //init with auth token
+var webhookMiddleware = twilio.webhook({
+    validate:false // don't attempt request validation
+});
+var webhookMiddleware = twilio.webhook({
+    host: 'hook.twilio.com',
+    protocol: 'https'
+});
+ */
+export declare function webhook(opts?: string | WebhookOptions, authToken?: string | WebhookOptions): (req: any, res: any, next: any) => void;

package/lib/webhooks/webhooks.js

@@ -1,64 +1,191 @@
-'use strict';
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhook = exports.validateExpressRequest = exports.validateIncomingRequest = exports.validateRequestWithBody = exports.validateBody = exports.validateRequest = exports.getExpectedBodyHash = exports.getExpectedTwilioSignature = void 0;
+const scmp = require("scmp");
+const crypto_1 = __importDefault(require("crypto"));
+const url_1 = __importDefault(require("url"));
+const url_parse_1 = __importDefault(require("url-parse"));
+/**
+ * Utility function to construct the URL string, since Node.js url library won't include standard port numbers
+ *
+ * @param parsedUrl - The parsed url object that Twilio requested on your server
+ * @returns URL with standard port number included
+ */
+function buildUrlWithStandardPort(parsedUrl) {
+    let url = "";
+    const port = parsedUrl.protocol === "https:" ? ":443" : ":80";
+    url += parsedUrl.protocol ? parsedUrl.protocol + "//" : "";
+    url += parsedUrl.username;
+    url += parsedUrl.password ? ":" + parsedUrl.password : "";
+    url += parsedUrl.username || parsedUrl.password ? "@" : "";
+    url += parsedUrl.host ? parsedUrl.host + port : "";
+    url += parsedUrl.pathname + parsedUrl.query + parsedUrl.hash;
+    return url;
+}
+/**
+ Utility function to add a port number to a URL
+
+ @param parsedUrl - The parsed url object that Twilio requested on your server
+ @returns URL with port
+ */
+function addPort(parsedUrl) {
+    if (!parsedUrl.port) {
+        return buildUrlWithStandardPort(parsedUrl);
+    }
+    return parsedUrl.toString();
+}
+/**
+ Utility function to remove a port number from a URL
+
+ @param parsedUrl - The parsed url object that Twilio requested on your server
+ @returns URL without port
+ */
+function removePort(parsedUrl) {
+    parsedUrl.set("port", "");
+    return parsedUrl.toString();
+}
+/**
+ Utility function to convert request parameter to a string format
+
+ @param paramName - The request parameter name
+ @param paramValue - The request parameter value
+ @returns Formatted parameter string
+ */
+function toFormUrlEncodedParam(paramName, paramValue) {
+    if (paramValue instanceof Array) {
+        return Array.from(new Set(paramValue))
+            .sort()
+            .map((val) => toFormUrlEncodedParam(paramName, val))
+            .reduce((acc, val) => acc + val, "");
+    }
+    return paramName + paramValue;
+}
+/**
+ Utility function to get the expected signature for a given request
 
-var crypto = require('crypto');
-var _ = require('lodash');
-var scmp = require('scmp');
-var url = require('url');
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param url - The full URL (with query string) you configured to handle
+ this request
+ @param params - the parameters sent with this request
+ @returns signature
+ */
+function getExpectedTwilioSignature(authToken, url, params) {
+    if (url.indexOf("bodySHA256") !== -1 && params === null) {
+        params = {};
+    }
+    var data = Object.keys(params)
+        .sort()
+        .reduce((acc, key) => acc + toFormUrlEncodedParam(key, params[key]), url);
+    return crypto_1.default
+        .createHmac("sha1", authToken)
+        .update(Buffer.from(data, "utf-8"))
+        .digest("base64");
+}
+exports.getExpectedTwilioSignature = getExpectedTwilioSignature;
+/**
+ Utility function to get the expected body hash for a given request's body
 
+ @param body - The plain-text body of the request
+ */
+function getExpectedBodyHash(body) {
+    return crypto_1.default
+        .createHash("sha256")
+        .update(Buffer.from(body, "utf-8"))
+        .digest("hex");
+}
+exports.getExpectedBodyHash = getExpectedBodyHash;
 /**
  Utility function to validate an incoming request is indeed from Twilio
 
- @param {string} authToken - The auth token, as seen in the Twilio portal
- @param {string} twilioHeader - The value of the X-Twilio-Signature header from the request
- @param {string} url - The full URL (with query string) you configured to handle this request
- @param {object} params - the parameters sent with this request
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param twilioHeader - The value of the X-Twilio-Signature header from the request
+ @param url - The full URL (with query string) you configured to handle this request
+ @param params - the parameters sent with this request
+ @returns valid
  */
 function validateRequest(authToken, twilioHeader, url, params) {
-  Object.keys(params).sort().forEach(function(key) {
-      url = url + key + params[key];
-  });
-
-  return scmp(twilioHeader, crypto.createHmac('sha1', authToken).update(new Buffer(url, 'utf-8')).digest('Base64'));
+    twilioHeader = twilioHeader || "";
+    const urlObject = new url_parse_1.default(url);
+    const urlWithPort = addPort(urlObject);
+    const urlWithoutPort = removePort(urlObject);
+    /*
+     *  Check signature of the url with and without the port number
+     *  since signature generation on the back end is inconsistent
+     */
+    const signatureWithPort = getExpectedTwilioSignature(authToken, urlWithPort, params);
+    const signatureWithoutPort = getExpectedTwilioSignature(authToken, urlWithoutPort, params);
+    const validSignatureWithPort = scmp(Buffer.from(twilioHeader), Buffer.from(signatureWithPort));
+    const validSignatureWithoutPort = scmp(Buffer.from(twilioHeader), Buffer.from(signatureWithoutPort));
+    return validSignatureWithoutPort || validSignatureWithPort;
+}
+exports.validateRequest = validateRequest;
+function validateBody(body, bodyHash) {
+    var expectedHash = getExpectedBodyHash(body);
+    return scmp(Buffer.from(bodyHash), Buffer.from(expectedHash));
 }
+exports.validateBody = validateBody;
+/**
+ Utility function to validate an incoming request is indeed from Twilio. This also validates
+ the request body against the bodySHA256 post parameter.
 
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param twilioHeader - The value of the X-Twilio-Signature header from the request
+ @param url - The full URL (with query string) you configured to handle this request
+ @param body - The body of the request
+ @returns valid
+ */
+function validateRequestWithBody(authToken, twilioHeader, url, body) {
+    const urlObject = new url_parse_1.default(url, true);
+    return (validateRequest(authToken, twilioHeader, url, {}) &&
+        validateBody(body, urlObject.query.bodySHA256 || ""));
+}
+exports.validateRequestWithBody = validateRequestWithBody;
 /**
- Utility function to validate an incoming request is indeed from Twilio (for use with express).
+ Utility function to validate an incoming request is indeed from Twilio.
  adapted from https://github.com/crabasa/twiliosig
 
- @param {object} request - An expressjs request object (http://expressjs.com/api.html#req.params)
- @param {string} authToken - The auth token, as seen in the Twilio portal
- @param {object} opts - options for request validation:
-    - webhookUrl: The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
-    - host: manually specify the host name used by Twilio in a number's webhook config
-    - protocol: manually specify the protocol used by Twilio in a number's webhook config
+ @param request - A request object (based on Express implementation http://expressjs.com/api.html#req.params)
+ @param authToken - The auth token, as seen in the Twilio portal
+ @param opts - options for request validation:
+    -> url: The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
+    -> host: manually specify the host name used by Twilio in a number's webhook config
+    -> protocol: manually specify the protocol used by Twilio in a number's webhook config
  */
+function validateIncomingRequest(request, authToken, opts) {
+    var options = opts || {};
+    var webhookUrl;
+    if (options.url) {
+        // Let the user specify the full URL
+        webhookUrl = options.url;
+    }
+    else {
+        // Use configured host/protocol, or infer based on request
+        var protocol = options.protocol || request.protocol;
+        var host = options.host || request.headers.host;
+        webhookUrl = url_1.default.format({
+            protocol: protocol,
+            host: host,
+            pathname: request.originalUrl,
+        });
+        if (request.originalUrl.search(/\?/) >= 0) {
+            webhookUrl = webhookUrl.replace(/%3F/g, "?");
+        }
+    }
+    if (webhookUrl.indexOf("bodySHA256") > 0) {
+        return validateRequestWithBody(authToken, request.header("X-Twilio-Signature") || "", webhookUrl, request.rawBody || "{}");
+    }
+    else {
+        return validateRequest(authToken, request.header("X-Twilio-Signature") || "", webhookUrl, request.body || {});
+    }
+}
+exports.validateIncomingRequest = validateIncomingRequest;
 function validateExpressRequest(request, authToken, opts) {
-  var options = opts || {};
-  var webhookUrl;
-
-  if (options.url) {
-    // Let the user specify the full URL
-    webhookUrl = options.url;
-  } else {
-    // Use configured host/protocol, or infer based on request
-    var protocol = options.protocol || request.protocol;
-    var host = options.host || request.headers.host;
-
-    webhookUrl = url.format({
-        protocol: protocol,
-        host: host,
-        pathname: request.originalUrl
-    });
-  }
-
-  return validateRequest(
-    authToken,
-    request.header('X-Twilio-Signature'),
-    webhookUrl,
-    request.body || {}
-  );
+    return validateIncomingRequest(request, authToken, opts);
 }
-
+exports.validateExpressRequest = validateExpressRequest;
 /**
 Express middleware to accompany a Twilio webhook. Provides Twilio
 request validation, and makes the response a little more friendly for our
@@ -71,10 +198,9 @@ Options:
     Twilio, we will return a text body and a 403.  If there is no configured
     auth token and validate=true, this is an error condition, so we will return
     a 500.
-- includeHelpers: {Boolean} add helpers to the response object to improve support
-    for XML (TwiML) rendering.  Default true.
 - host: manually specify the host name used by Twilio in a number's webhook config
 - protocol: manually specify the protocol used by Twilio in a number's webhook config
+- url: The full URL (with query string) you used to configure the webhook with Twilio - overrides host/protocol options
 
 Returns a middleware function.
 
@@ -89,78 +215,88 @@ var webhookMiddleware = twilio.webhook({
     protocol: 'https'
 });
  */
-function webhook() {
-  var opts = {
-    validate: true,
-    includeHelpers: true
-  };
-
-  // Process arguments
-  var tokenString;
-  for (var i = 0, l = arguments.length; i < l; i++) {
-    var arg = arguments[i];
-    if (typeof arg === 'string') {
-      tokenString = arg;
-    } else {
-      opts = _.extend(opts, arg);
+function webhook(opts, authToken) {
+    let token;
+    let options = undefined;
+    // Narrowing the args
+    if (opts) {
+        if (typeof opts === "string") {
+            token = opts;
+        }
+        if (typeof opts === "object") {
+            options = opts;
+        }
     }
-  }
-
-  // set auth token from input or environment variable
-  opts.authToken = tokenString ? tokenString : process.env.TWILIO_AUTH_TOKEN;
-
-  // Create middleware function
-  return function hook(request, response, next) {
-    // Add helpers, unless disabled
-    if (opts.includeHelpers) {
-      var oldSend = response.send;
-      response.send = function() {
-        // This is a special TwiML-aware version of send.  If we detect
-        // A twiml response object, we'll set the content-type and
-        // automatically call .toString()
-        if (arguments.length === 1 && arguments[0].legalNodes) {
-          response.type('text/xml');
-          oldSend.call(response, arguments[0].toString());
-        } else {
-          // Continue with old version of send
-          oldSend.apply(response, arguments);
+    if (authToken) {
+        if (typeof authToken === "string") {
+            token = authToken;
+        }
+        if (typeof authToken === "object") {
+            options = authToken;
         }
-      };
     }
-
-    // Do validation if requested
-    if (opts.validate) {
-      // Check for a valid auth token
-      if (!opts.authToken) {
-        console.error('[Twilio]: Error - Twilio auth token is required for webhook request validation.');
-        response.type('text/plain')
-          .status(500)
-          .send('Webhook Error - we attempted to validate this request without first configuring our auth token.');
-      } else {
-        // Check that the request originated from Twilio
-        var valid = validateExpressRequest(request, opts.authToken, {
-          url: opts.url,
-          host: opts.host,
-          protocol: opts.protocol
-        });
-
-        if (valid) {
-            next();
-        } else {
-          return response
-            .type('text/plain')
-            .status(403)
-            .send('Twilio Request Validation Failed.');
+    if (!options) {
+        options = {
+            validate: true,
+        };
+    }
+    // Process arguments
+    var tokenString;
+    for (var i = 0, l = arguments.length; i < l; i++) {
+        var arg = arguments[i];
+        if (typeof arg === "string") {
+            tokenString = arg;
         }
-      }
-    } else {
-      next();
+        else {
+            options = Object.assign(options || {}, arg);
+        }
+    }
+    // set auth token from input or environment variable
+    if (options) {
+        options.authToken = tokenString
+            ? tokenString
+            : process.env.TWILIO_AUTH_TOKEN;
     }
-  };
+    // Create middleware function
+    return function hook(request, response, next) {
+        // Do validation if requested
+        if (options?.validate) {
+            // Check if the 'X-Twilio-Signature' header exists or not
+            if (!request.header("X-Twilio-Signature")) {
+                return response
+                    .type("text/plain")
+                    .status(400)
+                    .send("No signature header error - X-Twilio-Signature header does not exist, maybe this request is not coming from Twilio.");
+            }
+            // Check for a valid auth token
+            if (!options?.authToken) {
+                console.error("[Twilio]: Error - Twilio auth token is required for webhook request validation.");
+                response
+                    .type("text/plain")
+                    .status(500)
+                    .send("Webhook Error - we attempted to validate this request without first configuring our auth token.");
+            }
+            else {
+                // Check that the request originated from Twilio
+                var valid = validateExpressRequest(request, options?.authToken, {
+                    url: options?.url,
+                    host: options?.host,
+                    protocol: options?.protocol,
+                });
+                if (valid) {
+                    next();
+                }
+                else {
+                    return response
+                        .type("text/plain")
+                        .status(403)
+                        .send("Twilio Request Validation Failed.");
+                }
+            }
+        }
+        else {
+            next();
+        }
+    };
 }
-
-module.exports = {
-  validateRequest: validateRequest,
-  validateExpressRequest: validateExpressRequest,
-  webhook: webhook
-};
+exports.webhook = webhook;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "twilio",
   "description": "A Twilio helper library",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "author": "API Team <api@twilio.com>",
   "contributors": [
     {
@@ -20,37 +20,63 @@
     "url": "https://github.com/twilio/twilio-node.git"
   },
   "dependencies": {
-    "jsonwebtoken": "^7.4.1",
-    "lodash": "4.0.0",
-    "moment": "2.18.1",
-    "q": "2.0.x",
-    "request": "2.81.x",
-    "rootpath": "0.1.2",
-    "scmp": "0.0.3",
-    "xmlbuilder": "9.0.1",
-    "deprecate": "1.0.0"
+    "axios": "^0.26.1",
+    "dayjs": "^1.8.29",
+    "https-proxy-agent": "^5.0.0",
+    "jsonwebtoken": "^9.0.0",
+    "qs": "^6.9.4",
+    "scmp": "^2.1.0",
+    "url-parse": "^1.5.9",
+    "xmlbuilder": "^13.0.2"
   },
   "devDependencies": {
-    "express": "3.x",
-    "jasmine-node": "1.14.5",
-    "jshint": "2.8.x",
-    "jscs": "3.0.7",
-    "jsdoc": "3.4.x"
+    "@babel/preset-env": "^7.20.2",
+    "@babel/preset-typescript": "^7.18.6",
+    "@types/jest": "^29.2.5",
+    "@types/jsonwebtoken": "^9.0.0",
+    "@types/node": "^18.11.18",
+    "@types/qs": "^6.9.7",
+    "@types/url-parse": "^1.4.8",
+    "babel-plugin-replace-ts-export-assignment": "^0.0.2",
+    "eslint": "^8.31.0",
+    "express": "^4.17.1",
+    "jest": "^29.3.1",
+    "jshint": "^2.11.0",
+    "localtunnel": "^2.0.2",
+    "mock-fs": "^5.2.0",
+    "nock": "^13.2.9",
+    "node-mocks-http": "^1.8.1",
+    "prettier": "^2.7.1",
+    "ts-jest": "^29.0.5",
+    "typescript": "^4.7.2",
+    "typedoc": "^0.23.21"
   },
   "scripts": {
-    "test": "jasmine-node --captureExceptions spec",
-    "jshint": "jshint lib/rest/** lib/base/** lib/http/**",
-    "jscs": "jscs -c .jscsrc lib/base/** lib/http/** --fix",
-    "check": "npm run jshint; npm run jscs",
-    "jsdoc": "jsdoc -r lib -d docs"
+    "test": "npm run test:javascript && npm run test:typescript",
+    "test:javascript": "jest spec/* --coverage --detectOpenHandles",
+    "test:typescript": "tsc --noEmit",
+    "jshint": "jshint src/rest/** src/base/** src/http/**",
+    "jscs": "eslint src/base/**/**.js src/http/**/**.js --fix",
+    "prepublish": "npm run build",
+    "build": "tsc",
+    "check": "npm run jshint && npm run jscs",
+    "ci": "npm run test && npm run nsp && npm run prettier-check",
+    "nsp": "npm audit --production",
+    "prettier": "prettier --write .",
+    "prettier-check": "prettier --check .",
+    "cluster": "jest ./cluster_test.spec.ts --coverage",
+    "webhook-test": "jest ./webhook_cluster_test.spec.ts --coverage",
+    "typedoc": "typedoc --entryPointStrategy expand src --out docs --logLevel Error"
   },
   "files": [
     "lib",
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "main": "./lib",
+  "types": "./index.d.ts",
   "engines": {
-    "node": ">=0.12.0"
+    "node": ">=14.0"
   },
   "license": "MIT"
 }