@commercetools-backend/express 0.0.0-CRAFT-1791-20251006162610

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @commercetools-backend/express
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@commercetools-backend/express"><img src="https://badgen.net/npm/v/@commercetools-backend/express" alt="Latest release (latest dist-tag)" /></a> <a href="https://www.npmjs.com/package/@commercetools-backend/express"><img src="https://badgen.net/npm/v/@commercetools-backend/express/next" alt="Latest release (next dist-tag)" /></a> <a href="https://bundlephobia.com/result?p=@commercetools-backend/express"><img src="https://badgen.net/bundlephobia/minzip/@commercetools-backend/express" alt="Minified + GZipped size" /></a> <a href="https://github.com/commercetools/merchant-center-application-kit/blob/main/LICENSE"><img src="https://badgen.net/github/license/commercetools/merchant-center-application-kit" alt="GitHub license" /></a>
+</p>
+
+Zero-config HTTP server as Express.js to facilitate development.
+
+This package is primarily built for HTTP servers used by Custom Applications and it provides a set of components to facilitate the development of the HTTP server.
+
+## Install
+
+```bash
+$ npm install --save @commercetools-backend/express
+```
+
+Check out the [documentation](https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api) for more information.

package/dist/commercetools-backend-express.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29tbWVyY2V0b29scy1iYWNrZW5kLWV4cHJlc3MuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

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

@@ -0,0 +1,237 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _URL = require('@babel/runtime-corejs3/core-js-stable/url');
+var _Map = require('@babel/runtime-corejs3/core-js-stable/map');
+var _startsWithInstanceProperty = require('@babel/runtime-corejs3/core-js-stable/instance/starts-with');
+var jose = require('jose');
+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 }; }
+
+var _URL__default = /*#__PURE__*/_interopDefault(_URL);
+var _Map__default = /*#__PURE__*/_interopDefault(_Map);
+var _startsWithInstanceProperty__default = /*#__PURE__*/_interopDefault(_startsWithInstanceProperty);
+var _findInstanceProperty__default = /*#__PURE__*/_interopDefault(_findInstanceProperty);
+var _Object$entries__default = /*#__PURE__*/_interopDefault(_Object$entries);
+var _Array$isArray__default = /*#__PURE__*/_interopDefault(_Array$isArray);
+
+const CLOUD_IDENTIFIERS = {
+  GCP_AU: 'gcp-au',
+  GCP_EU: 'gcp-eu',
+  GCP_US: 'gcp-us',
+  AWS_EU: 'aws-eu',
+  AWS_US: 'aws-us',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  AWS_FRA: 'aws-fra',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  AWS_OHIO: 'aws-ohio'
+};
+const MC_API_URLS = {
+  [CLOUD_IDENTIFIERS.GCP_AU]: 'https://mc-api.australia-southeast1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_EU]: 'https://mc-api.europe-west1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_US]: 'https://mc-api.us-central1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_EU]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_US]: 'https://mc-api.us-east-2.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_FRA]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_OHIO]: 'https://mc-api.us-east-2.aws.commercetools.com'
+};
+const MC_API_PROXY_HEADERS = {
+  FORWARD_TO_VERSION: 'x-mc-api-forward-to-version',
+  CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
+};
+
+const getHeaderByCaseInsensitiveKey = (headers, headerKey) => {
+  var _context;
+  const matchingHeader = _findInstanceProperty__default["default"](_context = _Object$entries__default["default"](headers)).call(_context, _ref => {
+    let _ref2 = _slicedToArray(_ref, 1),
+      key = _ref2[0];
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+  if (matchingHeader && matchingHeader.length > 0) {
+    const _matchingHeader = _slicedToArray(matchingHeader, 2),
+      headerValue = _matchingHeader[1];
+    return _Array$isArray__default["default"](headerValue) ? headerValue[0] : headerValue;
+  }
+  return undefined;
+};
+const getFirstHeaderValueOrThrow = (headers, headerKey, errorMessage) => {
+  const headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+  if (!headerValue) {
+    throw new Error(errorMessage);
+  }
+  return headerValue;
+};
+
+// Assign a session object to the request object.
+const writeSessionContext = (request, verifiedToken) => {
+  const publicClaimForProjectKey = `${verifiedToken.iss}/claims/project_key`;
+  const publicClaimForUserPermissionsKey = `${verifiedToken.iss}/claims/user_permissions`;
+  request.session = {
+    userId: verifiedToken.sub,
+    projectKey: verifiedToken[publicClaimForProjectKey]
+  };
+  const userPermissions = verifiedToken[publicClaimForUserPermissionsKey];
+  if (Boolean(userPermissions?.length)) {
+    request.session.userPermissions = userPermissions;
+  }
+};
+
+// Given a cloud identifier, try to map it to one of the supported
+// environments and return the MC API URL for that environment.
+// The URL points to the new hostnames.
+// https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames
+const mapCloudIdentifierToIssuer = issuer => {
+  switch (issuer) {
+    case CLOUD_IDENTIFIERS.GCP_AU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_AU];
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_EU];
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_US];
+    case CLOUD_IDENTIFIERS.AWS_EU:
+    case CLOUD_IDENTIFIERS.AWS_FRA:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_EU];
+    case CLOUD_IDENTIFIERS.AWS_US:
+    case CLOUD_IDENTIFIERS.AWS_OHIO:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_US];
+    default:
+      return undefined;
+  }
+};
+// Given a cloud identifier, try to map it to a legacy hostname.
+// This is for backwards compatibility.
+const mapToLegacyIssuer = cloudIdentifier => {
+  switch (cloudIdentifier) {
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return 'https://mc-api.commercetools.com';
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return 'https://mc-api.commercetools.co';
+    default:
+      return undefined;
+  }
+};
+// Verifies that the issuer is a valid URL.
+const throwIfIssuerIsNotAValidUrl = issuer => {
+  try {
+    new _URL__default["default"](issuer);
+  } catch (error) {
+    throw new Error(`Invalid issuer URL "${issuer}". Expected a valid URL to the Merchant Center API Gateway, or a cloud identifier to one of the available cloud regions. See https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames.`);
+  }
+};
+// Validates required option values.
+const validateRequiredValues = options => {
+  if (!options.audience) {
+    throw new Error(`Missing required option "audience"`);
+  }
+  if (!options.issuer) {
+    throw new Error(`Missing required option "issuer"`);
+  }
+};
+// Attempt to parse the given issuer. If the value is a cloud identifier, it will
+// be mapped to one of the supported values. If not, we assume the value is a valid URL.
+const getConfiguredDefaultIssuer = options => {
+  const issuer = mapCloudIdentifierToIssuer(options.issuer);
+  if (!issuer) {
+    throwIfIssuerIsNotAValidUrl(options.issuer);
+    return options.issuer;
+  }
+  return issuer;
+};
+
+// Construct the audience from the given option + the request path.
+// If the request path is `/`, do not append it to the audience, otherwise
+// the token validation might fail because of mismatching audiences.
+const getConfiguredAudience = (options, requestPath) => {
+  // remove the trailing slash
+  const url = new _URL__default["default"](`${options.audience.replace(/\/?$/, '')}${requestPath}`);
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+    default:
+      {
+        if (requestPath === '/') {
+          return url.origin;
+        }
+        return `${url.origin}${url.pathname}`;
+      }
+  }
+};
+const jwksClientByIssuer = new _Map__default["default"]();
+function getJwksClientByIssuer(issuer) {
+  const client = jwksClientByIssuer.get(issuer);
+  if (client) {
+    return client;
+  }
+  const newClient = jose.createRemoteJWKSet(new _URL__default["default"](`/.well-known/jwks.json`, issuer));
+  jwksClientByIssuer.set(issuer, newClient);
+  return newClient;
+}
+function createSessionAuthVerifier(options) {
+  validateRequiredValues(options);
+  const configuredDefaultIssuer = getConfiguredDefaultIssuer(options);
+
+  // Returns an async HTTP handler.
+  return async request => {
+    // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
+    const cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, `Missing "X-MC-API-Cloud-Identifier" header.`);
+    let issuer = options.inferIssuer && cloudIdentifierHeader ? mapCloudIdentifierToIssuer(cloudIdentifierHeader) ?? 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.
+    const 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
+      issuer = mapToLegacyIssuer(cloudIdentifierHeader) ?? issuer;
+    }
+    const requestUrlPath = options.getRequestUrl ? options.getRequestUrl(request) : request.originalUrl ?? request.url;
+    if (!requestUrlPath || !_startsWithInstanceProperty__default["default"](requestUrlPath).call(requestUrlPath, '/')) {
+      throw new Error(`Invalid request URI path "${requestUrlPath}". Please make sure that the "request" object has either a property "originalUrl" or "url". If not, you should implement the "getRequestUrl" function and make sure to return a valid URI path value starting with "/". More info at https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api#validating-the-json-web-token`);
+    }
+    const audience = getConfiguredAudience(options, requestUrlPath);
+    const authorizationHeader = request.headers['authorization'];
+    if (typeof authorizationHeader !== 'string') {
+      throw new Error(`Missing "authorization" header`);
+    }
+    const exchangeToken = authorizationHeader.replace(/^Bearer (.*)$/, '$1');
+    const jwksClient = getJwksClientByIssuer(issuer);
+    const verifiedToken = await jose.jwtVerify(exchangeToken, jwksClient, {
+      algorithms: ['RS256'],
+      audience,
+      issuer
+    });
+    writeSessionContext(request, verifiedToken.payload);
+    return;
+  };
+}
+
+function createSessionMiddleware(options) {
+  const sessionAuthVerifier = createSessionAuthVerifier(options);
+  return async (request, _response, next) => {
+    try {
+      await sessionAuthVerifier(request);
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+exports.CLOUD_IDENTIFIERS = CLOUD_IDENTIFIERS;
+exports.MC_API_URLS = MC_API_URLS;
+exports.createSessionAuthVerifier = createSessionAuthVerifier;
+exports.createSessionMiddleware = createSessionMiddleware;

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

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./commercetools-backend-express.cjs.prod.js");
+} else {
+  module.exports = require("./commercetools-backend-express.cjs.dev.js");
+}

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

@@ -0,0 +1,237 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _URL = require('@babel/runtime-corejs3/core-js-stable/url');
+var _Map = require('@babel/runtime-corejs3/core-js-stable/map');
+var _startsWithInstanceProperty = require('@babel/runtime-corejs3/core-js-stable/instance/starts-with');
+var jose = require('jose');
+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 }; }
+
+var _URL__default = /*#__PURE__*/_interopDefault(_URL);
+var _Map__default = /*#__PURE__*/_interopDefault(_Map);
+var _startsWithInstanceProperty__default = /*#__PURE__*/_interopDefault(_startsWithInstanceProperty);
+var _findInstanceProperty__default = /*#__PURE__*/_interopDefault(_findInstanceProperty);
+var _Object$entries__default = /*#__PURE__*/_interopDefault(_Object$entries);
+var _Array$isArray__default = /*#__PURE__*/_interopDefault(_Array$isArray);
+
+const CLOUD_IDENTIFIERS = {
+  GCP_AU: 'gcp-au',
+  GCP_EU: 'gcp-eu',
+  GCP_US: 'gcp-us',
+  AWS_EU: 'aws-eu',
+  AWS_US: 'aws-us',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  AWS_FRA: 'aws-fra',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  AWS_OHIO: 'aws-ohio'
+};
+const MC_API_URLS = {
+  [CLOUD_IDENTIFIERS.GCP_AU]: 'https://mc-api.australia-southeast1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_EU]: 'https://mc-api.europe-west1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_US]: 'https://mc-api.us-central1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_EU]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_US]: 'https://mc-api.us-east-2.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_FRA]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_OHIO]: 'https://mc-api.us-east-2.aws.commercetools.com'
+};
+const MC_API_PROXY_HEADERS = {
+  FORWARD_TO_VERSION: 'x-mc-api-forward-to-version',
+  CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
+};
+
+const getHeaderByCaseInsensitiveKey = (headers, headerKey) => {
+  var _context;
+  const matchingHeader = _findInstanceProperty__default["default"](_context = _Object$entries__default["default"](headers)).call(_context, _ref => {
+    let _ref2 = _slicedToArray(_ref, 1),
+      key = _ref2[0];
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+  if (matchingHeader && matchingHeader.length > 0) {
+    const _matchingHeader = _slicedToArray(matchingHeader, 2),
+      headerValue = _matchingHeader[1];
+    return _Array$isArray__default["default"](headerValue) ? headerValue[0] : headerValue;
+  }
+  return undefined;
+};
+const getFirstHeaderValueOrThrow = (headers, headerKey, errorMessage) => {
+  const headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+  if (!headerValue) {
+    throw new Error(errorMessage);
+  }
+  return headerValue;
+};
+
+// Assign a session object to the request object.
+const writeSessionContext = (request, verifiedToken) => {
+  const publicClaimForProjectKey = `${verifiedToken.iss}/claims/project_key`;
+  const publicClaimForUserPermissionsKey = `${verifiedToken.iss}/claims/user_permissions`;
+  request.session = {
+    userId: verifiedToken.sub,
+    projectKey: verifiedToken[publicClaimForProjectKey]
+  };
+  const userPermissions = verifiedToken[publicClaimForUserPermissionsKey];
+  if (Boolean(userPermissions?.length)) {
+    request.session.userPermissions = userPermissions;
+  }
+};
+
+// Given a cloud identifier, try to map it to one of the supported
+// environments and return the MC API URL for that environment.
+// The URL points to the new hostnames.
+// https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames
+const mapCloudIdentifierToIssuer = issuer => {
+  switch (issuer) {
+    case CLOUD_IDENTIFIERS.GCP_AU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_AU];
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_EU];
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_US];
+    case CLOUD_IDENTIFIERS.AWS_EU:
+    case CLOUD_IDENTIFIERS.AWS_FRA:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_EU];
+    case CLOUD_IDENTIFIERS.AWS_US:
+    case CLOUD_IDENTIFIERS.AWS_OHIO:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_US];
+    default:
+      return undefined;
+  }
+};
+// Given a cloud identifier, try to map it to a legacy hostname.
+// This is for backwards compatibility.
+const mapToLegacyIssuer = cloudIdentifier => {
+  switch (cloudIdentifier) {
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return 'https://mc-api.commercetools.com';
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return 'https://mc-api.commercetools.co';
+    default:
+      return undefined;
+  }
+};
+// Verifies that the issuer is a valid URL.
+const throwIfIssuerIsNotAValidUrl = issuer => {
+  try {
+    new _URL__default["default"](issuer);
+  } catch (error) {
+    throw new Error(`Invalid issuer URL "${issuer}". Expected a valid URL to the Merchant Center API Gateway, or a cloud identifier to one of the available cloud regions. See https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames.`);
+  }
+};
+// Validates required option values.
+const validateRequiredValues = options => {
+  if (!options.audience) {
+    throw new Error(`Missing required option "audience"`);
+  }
+  if (!options.issuer) {
+    throw new Error(`Missing required option "issuer"`);
+  }
+};
+// Attempt to parse the given issuer. If the value is a cloud identifier, it will
+// be mapped to one of the supported values. If not, we assume the value is a valid URL.
+const getConfiguredDefaultIssuer = options => {
+  const issuer = mapCloudIdentifierToIssuer(options.issuer);
+  if (!issuer) {
+    throwIfIssuerIsNotAValidUrl(options.issuer);
+    return options.issuer;
+  }
+  return issuer;
+};
+
+// Construct the audience from the given option + the request path.
+// If the request path is `/`, do not append it to the audience, otherwise
+// the token validation might fail because of mismatching audiences.
+const getConfiguredAudience = (options, requestPath) => {
+  // remove the trailing slash
+  const url = new _URL__default["default"](`${options.audience.replace(/\/?$/, '')}${requestPath}`);
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+    default:
+      {
+        if (requestPath === '/') {
+          return url.origin;
+        }
+        return `${url.origin}${url.pathname}`;
+      }
+  }
+};
+const jwksClientByIssuer = new _Map__default["default"]();
+function getJwksClientByIssuer(issuer) {
+  const client = jwksClientByIssuer.get(issuer);
+  if (client) {
+    return client;
+  }
+  const newClient = jose.createRemoteJWKSet(new _URL__default["default"](`/.well-known/jwks.json`, issuer));
+  jwksClientByIssuer.set(issuer, newClient);
+  return newClient;
+}
+function createSessionAuthVerifier(options) {
+  validateRequiredValues(options);
+  const configuredDefaultIssuer = getConfiguredDefaultIssuer(options);
+
+  // Returns an async HTTP handler.
+  return async request => {
+    // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
+    const cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, `Missing "X-MC-API-Cloud-Identifier" header.`);
+    let issuer = options.inferIssuer && cloudIdentifierHeader ? mapCloudIdentifierToIssuer(cloudIdentifierHeader) ?? 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.
+    const 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
+      issuer = mapToLegacyIssuer(cloudIdentifierHeader) ?? issuer;
+    }
+    const requestUrlPath = options.getRequestUrl ? options.getRequestUrl(request) : request.originalUrl ?? request.url;
+    if (!requestUrlPath || !_startsWithInstanceProperty__default["default"](requestUrlPath).call(requestUrlPath, '/')) {
+      throw new Error(`Invalid request URI path "${requestUrlPath}". Please make sure that the "request" object has either a property "originalUrl" or "url". If not, you should implement the "getRequestUrl" function and make sure to return a valid URI path value starting with "/". More info at https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api#validating-the-json-web-token`);
+    }
+    const audience = getConfiguredAudience(options, requestUrlPath);
+    const authorizationHeader = request.headers['authorization'];
+    if (typeof authorizationHeader !== 'string') {
+      throw new Error(`Missing "authorization" header`);
+    }
+    const exchangeToken = authorizationHeader.replace(/^Bearer (.*)$/, '$1');
+    const jwksClient = getJwksClientByIssuer(issuer);
+    const verifiedToken = await jose.jwtVerify(exchangeToken, jwksClient, {
+      algorithms: ['RS256'],
+      audience,
+      issuer
+    });
+    writeSessionContext(request, verifiedToken.payload);
+    return;
+  };
+}
+
+function createSessionMiddleware(options) {
+  const sessionAuthVerifier = createSessionAuthVerifier(options);
+  return async (request, _response, next) => {
+    try {
+      await sessionAuthVerifier(request);
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+exports.CLOUD_IDENTIFIERS = CLOUD_IDENTIFIERS;
+exports.MC_API_URLS = MC_API_URLS;
+exports.createSessionAuthVerifier = createSessionAuthVerifier;
+exports.createSessionMiddleware = createSessionMiddleware;

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

@@ -0,0 +1,221 @@
+import _URL from '@babel/runtime-corejs3/core-js-stable/url';
+import _Map from '@babel/runtime-corejs3/core-js-stable/map';
+import _startsWithInstanceProperty from '@babel/runtime-corejs3/core-js-stable/instance/starts-with';
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+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';
+
+const CLOUD_IDENTIFIERS = {
+  GCP_AU: 'gcp-au',
+  GCP_EU: 'gcp-eu',
+  GCP_US: 'gcp-us',
+  AWS_EU: 'aws-eu',
+  AWS_US: 'aws-us',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  AWS_FRA: 'aws-fra',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  AWS_OHIO: 'aws-ohio'
+};
+const MC_API_URLS = {
+  [CLOUD_IDENTIFIERS.GCP_AU]: 'https://mc-api.australia-southeast1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_EU]: 'https://mc-api.europe-west1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.GCP_US]: 'https://mc-api.us-central1.gcp.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_EU]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  [CLOUD_IDENTIFIERS.AWS_US]: 'https://mc-api.us-east-2.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_EU` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_FRA]: 'https://mc-api.eu-central-1.aws.commercetools.com',
+  /**
+   * @deprecated: use `AWS_US` instead
+   */
+  [CLOUD_IDENTIFIERS.AWS_OHIO]: 'https://mc-api.us-east-2.aws.commercetools.com'
+};
+const MC_API_PROXY_HEADERS = {
+  FORWARD_TO_VERSION: 'x-mc-api-forward-to-version',
+  CLOUD_IDENTIFIER: 'x-mc-api-cloud-identifier'
+};
+
+const getHeaderByCaseInsensitiveKey = (headers, headerKey) => {
+  var _context;
+  const matchingHeader = _findInstanceProperty(_context = _Object$entries(headers)).call(_context, _ref => {
+    let _ref2 = _slicedToArray(_ref, 1),
+      key = _ref2[0];
+    return headerKey.toLowerCase() === key.toLowerCase();
+  });
+  if (matchingHeader && matchingHeader.length > 0) {
+    const _matchingHeader = _slicedToArray(matchingHeader, 2),
+      headerValue = _matchingHeader[1];
+    return _Array$isArray(headerValue) ? headerValue[0] : headerValue;
+  }
+  return undefined;
+};
+const getFirstHeaderValueOrThrow = (headers, headerKey, errorMessage) => {
+  const headerValue = getHeaderByCaseInsensitiveKey(headers, headerKey);
+  if (!headerValue) {
+    throw new Error(errorMessage);
+  }
+  return headerValue;
+};
+
+// Assign a session object to the request object.
+const writeSessionContext = (request, verifiedToken) => {
+  const publicClaimForProjectKey = `${verifiedToken.iss}/claims/project_key`;
+  const publicClaimForUserPermissionsKey = `${verifiedToken.iss}/claims/user_permissions`;
+  request.session = {
+    userId: verifiedToken.sub,
+    projectKey: verifiedToken[publicClaimForProjectKey]
+  };
+  const userPermissions = verifiedToken[publicClaimForUserPermissionsKey];
+  if (Boolean(userPermissions?.length)) {
+    request.session.userPermissions = userPermissions;
+  }
+};
+
+// Given a cloud identifier, try to map it to one of the supported
+// environments and return the MC API URL for that environment.
+// The URL points to the new hostnames.
+// https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames
+const mapCloudIdentifierToIssuer = issuer => {
+  switch (issuer) {
+    case CLOUD_IDENTIFIERS.GCP_AU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_AU];
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_EU];
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.GCP_US];
+    case CLOUD_IDENTIFIERS.AWS_EU:
+    case CLOUD_IDENTIFIERS.AWS_FRA:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_EU];
+    case CLOUD_IDENTIFIERS.AWS_US:
+    case CLOUD_IDENTIFIERS.AWS_OHIO:
+      return MC_API_URLS[CLOUD_IDENTIFIERS.AWS_US];
+    default:
+      return undefined;
+  }
+};
+// Given a cloud identifier, try to map it to a legacy hostname.
+// This is for backwards compatibility.
+const mapToLegacyIssuer = cloudIdentifier => {
+  switch (cloudIdentifier) {
+    case CLOUD_IDENTIFIERS.GCP_EU:
+      return 'https://mc-api.commercetools.com';
+    case CLOUD_IDENTIFIERS.GCP_US:
+      return 'https://mc-api.commercetools.co';
+    default:
+      return undefined;
+  }
+};
+// Verifies that the issuer is a valid URL.
+const throwIfIssuerIsNotAValidUrl = issuer => {
+  try {
+    new _URL(issuer);
+  } catch (error) {
+    throw new Error(`Invalid issuer URL "${issuer}". Expected a valid URL to the Merchant Center API Gateway, or a cloud identifier to one of the available cloud regions. See https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#hostnames.`);
+  }
+};
+// Validates required option values.
+const validateRequiredValues = options => {
+  if (!options.audience) {
+    throw new Error(`Missing required option "audience"`);
+  }
+  if (!options.issuer) {
+    throw new Error(`Missing required option "issuer"`);
+  }
+};
+// Attempt to parse the given issuer. If the value is a cloud identifier, it will
+// be mapped to one of the supported values. If not, we assume the value is a valid URL.
+const getConfiguredDefaultIssuer = options => {
+  const issuer = mapCloudIdentifierToIssuer(options.issuer);
+  if (!issuer) {
+    throwIfIssuerIsNotAValidUrl(options.issuer);
+    return options.issuer;
+  }
+  return issuer;
+};
+
+// Construct the audience from the given option + the request path.
+// If the request path is `/`, do not append it to the audience, otherwise
+// the token validation might fail because of mismatching audiences.
+const getConfiguredAudience = (options, requestPath) => {
+  // remove the trailing slash
+  const url = new _URL(`${options.audience.replace(/\/?$/, '')}${requestPath}`);
+  switch (options.audiencePolicy) {
+    case 'forward-url-origin':
+      return url.origin;
+    default:
+      {
+        if (requestPath === '/') {
+          return url.origin;
+        }
+        return `${url.origin}${url.pathname}`;
+      }
+  }
+};
+const jwksClientByIssuer = new _Map();
+function getJwksClientByIssuer(issuer) {
+  const client = jwksClientByIssuer.get(issuer);
+  if (client) {
+    return client;
+  }
+  const newClient = createRemoteJWKSet(new _URL(`/.well-known/jwks.json`, issuer));
+  jwksClientByIssuer.set(issuer, newClient);
+  return newClient;
+}
+function createSessionAuthVerifier(options) {
+  validateRequiredValues(options);
+  const configuredDefaultIssuer = getConfiguredDefaultIssuer(options);
+
+  // Returns an async HTTP handler.
+  return async request => {
+    // Get the cloud identifier header, forwarded by the `/proxy/forward-to` endpoint.
+    const cloudIdentifierHeader = getFirstHeaderValueOrThrow(request.headers, MC_API_PROXY_HEADERS.CLOUD_IDENTIFIER, `Missing "X-MC-API-Cloud-Identifier" header.`);
+    let issuer = options.inferIssuer && cloudIdentifierHeader ? mapCloudIdentifierToIssuer(cloudIdentifierHeader) ?? 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.
+    const 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
+      issuer = mapToLegacyIssuer(cloudIdentifierHeader) ?? issuer;
+    }
+    const requestUrlPath = options.getRequestUrl ? options.getRequestUrl(request) : request.originalUrl ?? request.url;
+    if (!requestUrlPath || !_startsWithInstanceProperty(requestUrlPath).call(requestUrlPath, '/')) {
+      throw new Error(`Invalid request URI path "${requestUrlPath}". Please make sure that the "request" object has either a property "originalUrl" or "url". If not, you should implement the "getRequestUrl" function and make sure to return a valid URI path value starting with "/". More info at https://docs.commercetools.com/merchant-center-customizations/concepts/integrate-with-your-own-api#validating-the-json-web-token`);
+    }
+    const audience = getConfiguredAudience(options, requestUrlPath);
+    const authorizationHeader = request.headers['authorization'];
+    if (typeof authorizationHeader !== 'string') {
+      throw new Error(`Missing "authorization" header`);
+    }
+    const exchangeToken = authorizationHeader.replace(/^Bearer (.*)$/, '$1');
+    const jwksClient = getJwksClientByIssuer(issuer);
+    const verifiedToken = await jwtVerify(exchangeToken, jwksClient, {
+      algorithms: ['RS256'],
+      audience,
+      issuer
+    });
+    writeSessionContext(request, verifiedToken.payload);
+    return;
+  };
+}
+
+function createSessionMiddleware(options) {
+  const sessionAuthVerifier = createSessionAuthVerifier(options);
+  return async (request, _response, next) => {
+    try {
+      await sessionAuthVerifier(request);
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+export { CLOUD_IDENTIFIERS, MC_API_URLS, createSessionAuthVerifier, createSessionMiddleware };

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

@@ -0,0 +1,12 @@
+import type { TSessionMiddlewareOptions, TSession, TBaseRequest } from "./types.js";
+export type TDecodedJWT = {
+    sub: string;
+    iss: string;
+    [property: string]: string | string[];
+};
+declare const writeSessionContext: <Request extends TBaseRequest>(request: Request & {
+    session?: TSession;
+}, verifiedToken: TDecodedJWT) => void;
+export declare const getConfiguredAudience: <Request extends TBaseRequest>(options: TSessionMiddlewareOptions<Request>, requestPath: string) => string;
+declare function createSessionAuthVerifier<Request extends TBaseRequest>(options: TSessionMiddlewareOptions<Request>): (request: Request) => Promise<void>;
+export { createSessionAuthVerifier, writeSessionContext };

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

@@ -0,0 +1,34 @@
+export declare const CLOUD_IDENTIFIERS: {
+    readonly GCP_AU: "gcp-au";
+    readonly GCP_EU: "gcp-eu";
+    readonly GCP_US: "gcp-us";
+    readonly AWS_EU: "aws-eu";
+    readonly AWS_US: "aws-us";
+    /**
+     * @deprecated: use `AWS_EU` instead
+     */
+    readonly AWS_FRA: "aws-fra";
+    /**
+     * @deprecated: use `AWS_US` instead
+     */
+    readonly AWS_OHIO: "aws-ohio";
+};
+export declare const MC_API_URLS: {
+    readonly "gcp-au": "https://mc-api.australia-southeast1.gcp.commercetools.com";
+    readonly "gcp-eu": "https://mc-api.europe-west1.gcp.commercetools.com";
+    readonly "gcp-us": "https://mc-api.us-central1.gcp.commercetools.com";
+    readonly "aws-eu": "https://mc-api.eu-central-1.aws.commercetools.com";
+    readonly "aws-us": "https://mc-api.us-east-2.aws.commercetools.com";
+    /**
+     * @deprecated: use `AWS_EU` instead
+     */
+    readonly "aws-fra": "https://mc-api.eu-central-1.aws.commercetools.com";
+    /**
+     * @deprecated: use `AWS_US` instead
+     */
+    readonly "aws-ohio": "https://mc-api.us-east-2.aws.commercetools.com";
+};
+export declare const MC_API_PROXY_HEADERS: {
+    readonly FORWARD_TO_VERSION: "x-mc-api-forward-to-version";
+    readonly CLOUD_IDENTIFIER: "x-mc-api-cloud-identifier";
+};

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

@@ -0,0 +1,3 @@
+export { CLOUD_IDENTIFIERS, MC_API_URLS } from "./constants.js";
+export { createSessionAuthVerifier } from "./auth.js";
+export { default as createSessionMiddleware } from "./middlewares/session-middleware.js";

package/dist/declarations/src/middlewares/session-middleware.d.ts

@@ -0,0 +1,4 @@
+import type { Response, NextFunction } from 'express';
+import type { TBaseRequest, TSessionMiddlewareOptions } from "../types.js";
+declare function createSessionMiddleware<Request extends TBaseRequest>(options: TSessionMiddlewareOptions<Request>): (request: Request, _response: Response, next: NextFunction) => Promise<void>;
+export default createSessionMiddleware;

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

@@ -0,0 +1,53 @@
+import { CLOUD_IDENTIFIERS } from "./constants.js";
+export type TAudience = string;
+export type TIssuer = string;
+export type TCloudIdentifier = (typeof CLOUD_IDENTIFIERS)[keyof typeof CLOUD_IDENTIFIERS];
+export type TAudiencePolicy = 'forward-url-full-path' | 'forward-url-origin';
+export interface TBaseRequest {
+    headers: Record<string, string | string[] | undefined>;
+    url?: string;
+    originalUrl?: string;
+}
+export 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`
+     *
+     * @deprecated
+     */
+    jwks?: unknown;
+    /**
+     * 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 type TSession = {
+    userId: string;
+    projectKey: string;
+    userPermissions?: string[];
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@commercetools-backend/express",
+  "version": "0.0.0-CRAFT-1791-20251006162610",
+  "description": "Zero-config HTTP server as Express.js to facilitate development",
+  "bugs": "https://github.com/commercetools/merchant-center-application-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commercetools/merchant-center-application-kit.git",
+    "directory": "packages-backend/express"
+  },
+  "homepage": "https://docs.commercetools.com/merchant-center-customizations",
+  "keywords": [
+    "javascript",
+    "nodejs",
+    "express",
+    "http",
+    "server",
+    "toolkit"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/commercetools-backend-express.cjs.js",
+  "module": "dist/commercetools-backend-express.esm.js",
+  "files": [
+    "dist",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@babel/runtime": "^7.22.15",
+    "@babel/runtime-corejs3": "^7.22.15",
+    "@types/express": "^4.17.17",
+    "@types/node": "^22.13.2",
+    "express": "^4.21.2",
+    "jose": "^5.10.0"
+  },
+  "devDependencies": {
+    "@tsconfig/node22": "^22.0.0",
+    "msw": "^1.3.5",
+    "typescript": "^5.2.2"
+  },
+  "engines": {
+    "node": "18.x || 20.x || >=22.0.0"
+  }
+}