@commercetools-backend/express 21.6.0 → 21.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 commercetools GmbH
+Copyright (c) commercetools GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -14,72 +14,4 @@ This package is primarily built for HTTP servers used by Custom Applications and
 $ npm install --save @commercetools-backend/express
 ```
 
-## Session middleware
-
-This Express.js middleware should be used to handle the authentication exchange between the server and the `/proxy/forward-to` endpoint of the Merchant Center API Gateway.
-
-> You can read more about the "Proxy to External API" concepts [here](https://docs.commercetools.com/custom-applications/main-concepts/proxy-to-external-api).
-
-```js
-const {
-  createSessionMiddleware,
-  CLOUD_IDENTIFIERS,
-} = require('@commercetools-backend/express');
-
-app.use(
-  createSessionMiddleware({
-    audience: 'https://my-api-server.com',
-    issuer: CLOUD_IDENTIFIERS.GCP_EU,
-  })
-);
-app.use((request, response, next) => {
-  // `request.session` contains the useful information
-});
-```
-
-### Middleware options
-
-- `audience` (_string_): The public-facing URL of your API server. The value should only contain the origin URL (protocol, hostname, port), the request path is inferred from the incoming request.
-
-- `issuer` (_string_): Either a cloud identifier or a valid URL to the Merchant Center API Gateway. The cloud identifier maps to the Merchant Center API URL of the related [cloud region](https://docs.commercetools.com/custom-applications/concepts/merchant-center-api#cloud-regions).
-
-  - `gcp-au`: `https://mc-api.australia-southeast1.gcp.commercetools.com`
-  - `gcp-eu`: `https://mc-api.europe-west1.gcp.commercetools.com`
-  - `gcp-us`: `https://mc-api.us-central1.gcp.commercetools.com`
-  - `aws-fra`: `https://mc-api.eu-central-1.aws.commercetools.com`
-  - `aws-ohio`: `https://mc-api.us-east-2.aws.commercetools.com`
-
-- `inferIssuer` (_boolean_): Determines whether the issuer should be inferred from the custom request HTTP header `x-mc-api-cloud-identifier` which is sent by the Merchant Center API Gateway when forwarding the request. This might be useful in case the server is used in multiple regions.
-
-- `jwks` (_object_): See options of `jwks-rsa`.
-
-### Usage in Serverless Functions
-
-If your HTTP server runs as a Serverless Function, the Express.js middleware should not be needed. Instead you can use the underlying function that does not require the `next` callback.
-
-**Example for Google Cloud Functions**
-
-```js
-const {
-  createSessionAuthVerifier,
-  CLOUD_IDENTIFIERS,
-} = require('@commercetools-backend/express');
-
-const sessionAuthVerifier = createSessionAuthVerifier({
-  audience: 'https://my-api-server.com',
-  issuer: CLOUD_IDENTIFIERS.GCP_EU,
-});
-
-exports.handler = async function (request, response) {
-  try {
-    await sessionAuthVerifier(request, response);
-  } catch (error) {
-    response.status(401).send(JSON.stringify({ message: 'Unauthorized' }));
-    return;
-  }
-
-  // `request.session` contains the useful information
-};
-```
-
-> The same concept applies for serverless functions in other cloud providers.
+Check out the [documentation](https://docs.commercetools.com/custom-applications/concepts/integrate-with-your-own-api) for more information.

package/dist/commercetools-backend-express.cjs.dev.js

@@ -18,6 +18,9 @@ var _Object$defineProperties = require('@babel/runtime-corejs3/core-js-stable/ob
 var _Object$defineProperty = require('@babel/runtime-corejs3/core-js-stable/object/define-property');
 var jwksRsa = require('jwks-rsa');
 var expressJwt = require('express-jwt');
+var _slicedToArray = require('@babel/runtime-corejs3/helpers/slicedToArray');
+var _findInstanceProperty = require('@babel/runtime-corejs3/core-js-stable/instance/find');
+var _Object$entries = require('@babel/runtime-corejs3/core-js-stable/object/entries');
 var _Array$isArray = require('@babel/runtime-corejs3/core-js-stable/array/is-array');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
@@ -35,6 +38,8 @@ var _Object$getOwnPropertyDescriptors__default = /*#__PURE__*/_interopDefault(_O
 var _Object$defineProperties__default = /*#__PURE__*/_interopDefault(_Object$defineProperties);
 var _Object$defineProperty__default = /*#__PURE__*/_interopDefault(_Object$defineProperty);
 var jwksRsa__default = /*#__PURE__*/_interopDefault(jwksRsa);
+var _findInstanceProperty__default = /*#__PURE__*/_interopDefault(_findInstanceProperty);
+var _Object$entries__default = /*#__PURE__*/_interopDefault(_Object$entries);
 var _Array$isArray__default = /*#__PURE__*/_interopDefault(_Array$isArray);
 
 var CLOUD_IDENTIFIERS = {
@@ -56,12 +61,34 @@ var MC_API_PROXY_HEADERS = {
   CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
 };
 
-var getFirstOrThrow = function getFirstOrThrow(value, errorMessage) {
-  if (!value) {
+var getHeaderByCaseInsensitiveKey = function getHeaderByCaseInsensitiveKey(headers, headerKey) {
+  var _context;
+
+  var matchingHeader = _findInstanceProperty__default["default"](_context = _Object$entries__default["default"](headers)).call(_context, function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 1),
+        key = _ref2[0];
+
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+
+  if (matchingHeader && matchingHeader.length > 0) {
+    var _matchingHeader = _slicedToArray(matchingHeader, 2),
+        headerValue = _matchingHeader[1];
+
+    return _Array$isArray__default["default"](headerValue) ? headerValue[0] : headerValue;
+  }
+
+  return undefined;
+};
+
+var getFirstHeaderValueOrThrow = function getFirstHeaderValueOrThrow(headers, headerKey, errorMessage) {
+  var headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+
+  if (!headerValue) {
     throw new Error(errorMessage);
   }
 
-  return _Array$isArray__default["default"](value) ? value[0] : value;
+  return headerValue;
 };
 
 function ownKeys(object, enumerableOnly) { var keys = _Object$keys__default["default"](object); if (_Object$getOwnPropertySymbols__default["default"]) { var symbols = _Object$getOwnPropertySymbols__default["default"](object); enumerableOnly && (symbols = _filterInstanceProperty__default["default"](symbols).call(symbols, function (sym) { return _Object$getOwnPropertyDescriptor__default["default"](object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
@@ -162,16 +189,26 @@ var getConfiguredDefaultIssuer = function getConfiguredDefaultIssuer(options) {
 
 
 var getConfiguredAudience = function getConfiguredAudience(options, requestPath) {
-  var _context, _context2;
+  var _context;
 
   // remove the trailing slash
   var url = new _URL__default["default"](_concatInstanceProperty__default["default"](_context = "".concat(options.audience.replace(/\/?$/, ''))).call(_context, requestPath));
 
-  if (requestPath === '/') {
-    return url.origin;
-  }
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+
+    default:
+      {
+        var _context2;
 
-  return _concatInstanceProperty__default["default"](_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+        if (requestPath === '/') {
+          return url.origin;
+        }
+
+        return _concatInstanceProperty__default["default"](_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+      }
+  }
 };
 
 function createSessionAuthVerifier(options) {
@@ -189,11 +226,11 @@ function createSessionAuthVerifier(options) {
           switch (_context3.prev = _context3.next) {
             case 0:
               // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
-              cloudIdentifierHeader = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER], "Missing \"X-MC-API-Cloud-Identifier\" header.");
+              cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, "Missing \"X-MC-API-Cloud-Identifier\" header.");
               issuer = options.inferIssuer && cloudIdentifierHeader ? (_mapCloudIdentifierTo = mapCloudIdentifierToIssuer(cloudIdentifierHeader)) !== null && _mapCloudIdentifierTo !== void 0 ? _mapCloudIdentifierTo : configuredDefaultIssuer : configuredDefaultIssuer; // Get the `Accept-version` header, forwarded by the `/proxy/forward-to` endpoint.
               // The version should be sent by the client making the request, to use the features of v2.
 
-              proxyForwardVersion = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.FORWARD_TO_VERSION], "Missing \"X-MC-API-Forward-To-Version\" header.");
+              proxyForwardVersion = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.FORWARD_TO_VERSION, "Missing \"X-MC-API-Forward-To-Version\" header.");
 
               if (proxyForwardVersion === 'v1') {
                 // Fall back to legacy issuer domains

package/dist/commercetools-backend-express.cjs.prod.js

@@ -18,6 +18,9 @@ var _Object$defineProperties = require('@babel/runtime-corejs3/core-js-stable/ob
 var _Object$defineProperty = require('@babel/runtime-corejs3/core-js-stable/object/define-property');
 var jwksRsa = require('jwks-rsa');
 var expressJwt = require('express-jwt');
+var _slicedToArray = require('@babel/runtime-corejs3/helpers/slicedToArray');
+var _findInstanceProperty = require('@babel/runtime-corejs3/core-js-stable/instance/find');
+var _Object$entries = require('@babel/runtime-corejs3/core-js-stable/object/entries');
 var _Array$isArray = require('@babel/runtime-corejs3/core-js-stable/array/is-array');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
@@ -35,6 +38,8 @@ var _Object$getOwnPropertyDescriptors__default = /*#__PURE__*/_interopDefault(_O
 var _Object$defineProperties__default = /*#__PURE__*/_interopDefault(_Object$defineProperties);
 var _Object$defineProperty__default = /*#__PURE__*/_interopDefault(_Object$defineProperty);
 var jwksRsa__default = /*#__PURE__*/_interopDefault(jwksRsa);
+var _findInstanceProperty__default = /*#__PURE__*/_interopDefault(_findInstanceProperty);
+var _Object$entries__default = /*#__PURE__*/_interopDefault(_Object$entries);
 var _Array$isArray__default = /*#__PURE__*/_interopDefault(_Array$isArray);
 
 var CLOUD_IDENTIFIERS = {
@@ -56,12 +61,34 @@ var MC_API_PROXY_HEADERS = {
   CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
 };
 
-var getFirstOrThrow = function getFirstOrThrow(value, errorMessage) {
-  if (!value) {
+var getHeaderByCaseInsensitiveKey = function getHeaderByCaseInsensitiveKey(headers, headerKey) {
+  var _context;
+
+  var matchingHeader = _findInstanceProperty__default["default"](_context = _Object$entries__default["default"](headers)).call(_context, function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 1),
+        key = _ref2[0];
+
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+
+  if (matchingHeader && matchingHeader.length > 0) {
+    var _matchingHeader = _slicedToArray(matchingHeader, 2),
+        headerValue = _matchingHeader[1];
+
+    return _Array$isArray__default["default"](headerValue) ? headerValue[0] : headerValue;
+  }
+
+  return undefined;
+};
+
+var getFirstHeaderValueOrThrow = function getFirstHeaderValueOrThrow(headers, headerKey, errorMessage) {
+  var headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+
+  if (!headerValue) {
     throw new Error(errorMessage);
   }
 
-  return _Array$isArray__default["default"](value) ? value[0] : value;
+  return headerValue;
 };
 
 function ownKeys(object, enumerableOnly) { var keys = _Object$keys__default["default"](object); if (_Object$getOwnPropertySymbols__default["default"]) { var symbols = _Object$getOwnPropertySymbols__default["default"](object); enumerableOnly && (symbols = _filterInstanceProperty__default["default"](symbols).call(symbols, function (sym) { return _Object$getOwnPropertyDescriptor__default["default"](object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
@@ -162,16 +189,26 @@ var getConfiguredDefaultIssuer = function getConfiguredDefaultIssuer(options) {
 
 
 var getConfiguredAudience = function getConfiguredAudience(options, requestPath) {
-  var _context, _context2;
+  var _context;
 
   // remove the trailing slash
   var url = new _URL__default["default"](_concatInstanceProperty__default["default"](_context = "".concat(options.audience.replace(/\/?$/, ''))).call(_context, requestPath));
 
-  if (requestPath === '/') {
-    return url.origin;
-  }
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+
+    default:
+      {
+        var _context2;
 
-  return _concatInstanceProperty__default["default"](_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+        if (requestPath === '/') {
+          return url.origin;
+        }
+
+        return _concatInstanceProperty__default["default"](_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+      }
+  }
 };
 
 function createSessionAuthVerifier(options) {
@@ -189,11 +226,11 @@ function createSessionAuthVerifier(options) {
           switch (_context3.prev = _context3.next) {
             case 0:
               // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
-              cloudIdentifierHeader = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER], "Missing \"X-MC-API-Cloud-Identifier\" header.");
+              cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, "Missing \"X-MC-API-Cloud-Identifier\" header.");
               issuer = options.inferIssuer && cloudIdentifierHeader ? (_mapCloudIdentifierTo = mapCloudIdentifierToIssuer(cloudIdentifierHeader)) !== null && _mapCloudIdentifierTo !== void 0 ? _mapCloudIdentifierTo : configuredDefaultIssuer : configuredDefaultIssuer; // Get the `Accept-version` header, forwarded by the `/proxy/forward-to` endpoint.
               // The version should be sent by the client making the request, to use the features of v2.
 
-              proxyForwardVersion = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.FORWARD_TO_VERSION], "Missing \"X-MC-API-Forward-To-Version\" header.");
+              proxyForwardVersion = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.FORWARD_TO_VERSION, "Missing \"X-MC-API-Forward-To-Version\" header.");
 
               if (proxyForwardVersion === 'v1') {
                 // Fall back to legacy issuer domains

package/dist/commercetools-backend-express.esm.js

@@ -14,6 +14,9 @@ import _Object$defineProperties from '@babel/runtime-corejs3/core-js-stable/obje
 import _Object$defineProperty from '@babel/runtime-corejs3/core-js-stable/object/define-property';
 import jwksRsa from 'jwks-rsa';
 import { expressjwt } from 'express-jwt';
+import _slicedToArray from '@babel/runtime-corejs3/helpers/esm/slicedToArray';
+import _findInstanceProperty from '@babel/runtime-corejs3/core-js-stable/instance/find';
+import _Object$entries from '@babel/runtime-corejs3/core-js-stable/object/entries';
 import _Array$isArray from '@babel/runtime-corejs3/core-js-stable/array/is-array';
 
 var CLOUD_IDENTIFIERS = {
@@ -35,12 +38,34 @@ var MC_API_PROXY_HEADERS = {
   CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
 };
 
-var getFirstOrThrow = function getFirstOrThrow(value, errorMessage) {
-  if (!value) {
+var getHeaderByCaseInsensitiveKey = function getHeaderByCaseInsensitiveKey(headers, headerKey) {
+  var _context;
+
+  var matchingHeader = _findInstanceProperty(_context = _Object$entries(headers)).call(_context, function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 1),
+        key = _ref2[0];
+
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+
+  if (matchingHeader && matchingHeader.length > 0) {
+    var _matchingHeader = _slicedToArray(matchingHeader, 2),
+        headerValue = _matchingHeader[1];
+
+    return _Array$isArray(headerValue) ? headerValue[0] : headerValue;
+  }
+
+  return undefined;
+};
+
+var getFirstHeaderValueOrThrow = function getFirstHeaderValueOrThrow(headers, headerKey, errorMessage) {
+  var headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+
+  if (!headerValue) {
     throw new Error(errorMessage);
   }
 
-  return _Array$isArray(value) ? value[0] : value;
+  return headerValue;
 };
 
 function ownKeys(object, enumerableOnly) { var keys = _Object$keys(object); if (_Object$getOwnPropertySymbols) { var symbols = _Object$getOwnPropertySymbols(object); enumerableOnly && (symbols = _filterInstanceProperty(symbols).call(symbols, function (sym) { return _Object$getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
@@ -141,16 +166,26 @@ var getConfiguredDefaultIssuer = function getConfiguredDefaultIssuer(options) {
 
 
 var getConfiguredAudience = function getConfiguredAudience(options, requestPath) {
-  var _context, _context2;
+  var _context;
 
   // remove the trailing slash
   var url = new _URL(_concatInstanceProperty(_context = "".concat(options.audience.replace(/\/?$/, ''))).call(_context, requestPath));
 
-  if (requestPath === '/') {
-    return url.origin;
-  }
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+
+    default:
+      {
+        var _context2;
 
-  return _concatInstanceProperty(_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+        if (requestPath === '/') {
+          return url.origin;
+        }
+
+        return _concatInstanceProperty(_context2 = "".concat(url.origin)).call(_context2, url.pathname);
+      }
+  }
 };
 
 function createSessionAuthVerifier(options) {
@@ -168,11 +203,11 @@ function createSessionAuthVerifier(options) {
           switch (_context3.prev = _context3.next) {
             case 0:
               // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
-              cloudIdentifierHeader = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER], "Missing \"X-MC-API-Cloud-Identifier\" header.");
+              cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, "Missing \"X-MC-API-Cloud-Identifier\" header.");
               issuer = options.inferIssuer && cloudIdentifierHeader ? (_mapCloudIdentifierTo = mapCloudIdentifierToIssuer(cloudIdentifierHeader)) !== null && _mapCloudIdentifierTo !== void 0 ? _mapCloudIdentifierTo : configuredDefaultIssuer : configuredDefaultIssuer; // Get the `Accept-version` header, forwarded by the `/proxy/forward-to` endpoint.
               // The version should be sent by the client making the request, to use the features of v2.
 
-              proxyForwardVersion = getFirstOrThrow(request.headers[MC_API_PROXY_HEADERS.FORWARD_TO_VERSION], "Missing \"X-MC-API-Forward-To-Version\" header.");
+              proxyForwardVersion = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.FORWARD_TO_VERSION, "Missing \"X-MC-API-Forward-To-Version\" header.");
 
               if (proxyForwardVersion === 'v1') {
                 // Fall back to legacy issuer domains

package/dist/declarations/src/types.d.ts

@@ -3,16 +3,46 @@ import { CLOUD_IDENTIFIERS } from './constants';
 export declare type TAudience = string;
 export declare type TIssuer = string;
 export declare type TCloudIdentifier = typeof CLOUD_IDENTIFIERS[keyof typeof CLOUD_IDENTIFIERS];
+export declare type TAudiencePolicy = 'forward-url-full-path' | 'forward-url-origin';
 export interface TBaseRequest {
     headers: Record<string, string | string[] | undefined>;
     url?: string;
     originalUrl?: string;
 }
 export declare type TSessionMiddlewareOptions<Request extends TBaseRequest> = {
+    /**
+     * The public-facing URL used to connect to the server / serverless function.
+     * The value should only contain the origin URL (protocol, hostname, port),
+     * the request path is inferred from the incoming request.
+     */
     audience: TAudience;
+    /**
+     * How the audience value should be exchanged between the server and the client.
+     * By default it uses the full URL (origin + pathname).
+     */
+    audiencePolicy?: TAudiencePolicy;
+    /**
+     * The cloud identifier (see `CLOUD_IDENTIFIERS`) that maps to the MC API URL
+     * of the related cloud region or the MC API URL.
+     */
     issuer: TCloudIdentifier | TIssuer;
+    /**
+     * Determines whether the issuer should be inferred from the custom request
+     * HTTP header `x-mc-api-cloud-identifier` which is sent by the MC API when
+     * forwarding the request.
+     * This might be useful in case the server is used in multiple regions.
+     */
     inferIssuer?: boolean;
+    /**
+     * Options for the `jwksRsa.expressJwtSecret`
+     */
     jwks?: Omit<ExpressJwtOptions, 'jwksUri'>;
+    /**
+     * By default we assume that the `request` is a Node.js-like object having either
+     * an `originalUrl` or `url` properties.
+     * If that's not the case (for example in AWS Lambda functions) you need to correctly
+     * map the URL (URI path + query string) of the `request`.
+     */
     getRequestUrl?: (request: Request) => string;
 };
 export declare type TSession = {

package/dist/declarations/src/utils.d.ts

@@ -1,2 +1,3 @@
-declare const getFirstOrThrow: (value: string | string[] | undefined, errorMessage: string) => string;
-export { getFirstOrThrow };
+declare const getHeaderByCaseInsensitiveKey: (headers: Record<string, string | string[] | undefined>, headerKey: string) => string | undefined;
+declare const getFirstHeaderValueOrThrow: (headers: Record<string, string | string[] | undefined>, headerKey: string, errorMessage: string) => string;
+export { getHeaderByCaseInsensitiveKey, getFirstHeaderValueOrThrow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercetools-backend/express",
-  "version": "21.6.0",
+  "version": "21.8.0",
   "description": "Zero-config HTTP server as Express.js to facilitate development",
   "bugs": "https://github.com/commercetools/merchant-center-application-kit/issues",
   "repository": {
@@ -26,6 +26,7 @@
     "jwks-rsa": "2.1.1"
   },
   "devDependencies": {
+    "@tsconfig/node16": "^1.0.2",
     "@types/express-unless": "^0.5.3",
     "@types/jsonwebtoken": "^8.5.8",
     "jose": "2.0.5",