@dwp/govuk-casa 8.7.12 → 8.9.0

package/src/lib/waypoint-url.js

@@ -0,0 +1,126 @@
+/**
+ * @access private
+ * @typedef {import('./index').JourneyContext} JourneyContext
+ */
+
+/** @access private */
+const reUrlProtocolExtract = /^url:\/\/(.+)$/i
+
+/**
+ * Sanitise a waypoint string.
+ *
+ * @access private
+ * @param {string} w Waypoint
+ * @returns {string} Sanitised waypoint
+ */
+const sanitiseWaypoint = (w) => w.replace(/[^/a-z0-9_-]/ig, '').replace(/\/+/g, '/');
+
+/**
+ * Sanitise a waypoint string, with allowed URL parameters:
+ * contextid = JourneyContext ID
+ *
+ * @access private
+ * @param {string} w Waypoint and potential URL parameters
+ * @returns {string} Sanitised waypoint
+ */
+const sanitiseWaypointWithAllowedParams = (w) => {
+  // Extract URL params
+  const parts = w.split('?');
+  if (parts.length !== 2) {
+    return sanitiseWaypoint(w);
+  }
+  const [waypoint, rawParams] = parts;
+  const urlSearchParams = new URLSearchParams(rawParams);
+
+  // Strip all but those parameters allowed
+  const validatedUrlSearchParams = new URLSearchParams();
+  for (const pk of ['contextid']) {
+    if (urlSearchParams.has(pk)) {
+      validatedUrlSearchParams.set(pk, urlSearchParams.get(pk));
+    }
+  }
+
+  return `${sanitiseWaypoint(waypoint)}?${validatedUrlSearchParams.toString()}`.replace(/\?$/, '');
+}
+
+/**
+ * Generate a URL pointing at a particular waypoint.
+ *
+ * @example
+ * // generates: /path/details?edit&editorigin=%2Fsomewhere%2Felse
+ * waypointUrl({
+ *   mountUrl: '/path/',
+ *   waypoint: 'details',
+ *   edit: true,
+ *   editOrigin: '/somewhere/else'
+ * })
+ * @memberof module:@dwp/govuk-casa
+ * @param {object} obj Options
+ * @param {string} [obj.waypoint=""] Waypoint
+ * @param {string} [obj.mountUrl="/"] Mount URL
+ * @param {JourneyContext} [obj.journeyContext] JourneyContext
+ * @param {boolean} [obj.edit=false] Turn edit mode on or off
+ * @param {string} [obj.editOrigin] Edit mode original URL
+ * @param {boolean} [obj.skipTo] Skip to this waypoint from the current one
+ * @param {string} [obj.routeName=next] Plan route name; next | prev
+ * @returns {string} URL
+ */
+export default function waypointUrl({
+  waypoint = '',
+  mountUrl = '/',
+  journeyContext,
+  edit = false,
+  editOrigin,
+  skipTo,
+  routeName = 'next',
+} = Object.create(null)) {
+  const url = new URL('https://placeholder.test');
+
+  // Handle url:// protocol
+  // - This will generate a link to the root handler "_" for the given mount path
+  if (String(waypoint).substr(0, 7) === 'url:///') {
+    const m = waypoint.match(reUrlProtocolExtract);
+
+    const u = new URL(sanitiseWaypointWithAllowedParams(m[1]), 'https://placeholder.test/');
+    url.pathname = `${sanitiseWaypoint(u.pathname)}/_/`;
+
+    url.searchParams.set('refmount', `url://${mountUrl}`);
+    url.searchParams.set('route', routeName);
+    for (const [uk, uv] of u.searchParams.entries()) {
+      url.searchParams.append(uk, uv);
+    }
+  } else {
+    const u = new URL(sanitiseWaypointWithAllowedParams(`${mountUrl}${waypoint}`), 'https://placeholder.test/');
+    url.pathname = u.pathname;
+    url.search = u.search;
+  }
+
+  // Attach context ID as query parameter for non-default contexts.
+  // To avoid messy URLs with duplicated content, this parameter will _not_ be
+  // added if the context ID already appears in the url path, i.e. to avoid
+  // `/path/1234-abcd/waypoint?contextid=1234-abcd` scenarios
+  if (
+    journeyContext
+    && !journeyContext.isDefault()
+    && journeyContext.identity.id
+    && !mountUrl.includes(`/${journeyContext.identity.id}/`)
+  ) {
+    url.searchParams.set('contextid', journeyContext.identity.id);
+  }
+
+  // Attach edit mode flag
+  if (edit === true) {
+    url.searchParams.set('edit', 'true');
+  }
+
+  if (edit && editOrigin) {
+    url.searchParams.set('editorigin', sanitiseWaypointWithAllowedParams(editOrigin));
+  }
+
+  // Skipto
+  if (skipTo) {
+    url.searchParams.set('skipto', sanitiseWaypointWithAllowedParams(skipTo));
+  }
+
+  return `${sanitiseWaypoint(url.pathname)}${url.search}`;
+}

package/src/middleware/body-parser.js

@@ -0,0 +1,31 @@
+import { urlencoded as expressBodyParser } from 'express';
+
+const rProto = /__proto__/i;
+const rPrototype = /prototype[='"[\]]/i;
+const rConstructor = /constructor[='"[\]]/i;
+
+export function verifyBody(req, res, buf, encoding) {
+  const body = decodeURI(buf.toString(encoding)).replace(/[\s\u200B-\u200D\uFEFF]/g, '');
+  if (rProto.test(body)) {
+    throw new Error('Request body verification failed (__proto__)');
+  }
+  if (rPrototype.test(body)) {
+    throw new Error('Request body verification failed (prototype)');
+  }
+  if (rConstructor.test(body)) {
+    throw new Error('Request body verification failed (constructor)');
+  }
+}
+
+export default function bodyParserMiddleware() {
+  return [
+    expressBodyParser({
+      extended: true,
+      type: 'application/x-www-form-urlencoded',
+      inflate: true,
+      parameterLimit: 25, // TODO: make configurable?
+      limit: 1024 * 50, // TODO: make configurable?
+      verify: verifyBody,
+    }),
+  ];
+}

package/src/middleware/csrf.js

@@ -0,0 +1,29 @@
+import csurf from 'csurf';
+
+// 2 middleware: one to generate the csrf token and check its validity (POST
+// only), and one to provide that token to templates via the `casa.csrfToken`
+// variable.
+
+export default function csrfMiddleware() {
+  return [
+    csurf({
+      cookie: false,
+      sessionKey: 'session',
+      // value: (req) => {
+      //   // Here we clear the token after extracting to maintain cleaner data. It
+      //   // is only used for this CSRF purpose.
+      //   const token = String(req.body._csrf);
+      //   delete req.body._csrf;
+      //   return token;
+      //   /* eslint-enable no-underscore-dangle */
+      // },
+    }),
+    (req, res, next) => {
+      res.locals.casa = {
+        ...res.locals?.casa,
+        csrfToken: req.csrfToken(),
+      };
+      next();
+    },
+  ];
+}

package/src/middleware/data.js

@@ -0,0 +1,105 @@
+// Decorates the request with some contextual data about the user's journey
+// through the application. This is used by downstream middleware and templates.
+
+import lodash from 'lodash';
+import JourneyContext from '../lib/JourneyContext.js';
+import { validateUrlPath } from '../lib/utils.js';
+import waypointUrl from '../lib/waypoint-url.js';
+
+const { has } = lodash;
+
+const editOrigin = (req) => {
+  if (has(req.query, 'editorigin')) {
+    return waypointUrl({ waypoint: req.query.editorigin });
+  }
+  if (has(req?.body, 'editorigin')) {
+    return waypointUrl({ waypoint: req.body.editorigin });
+  }
+  return '';
+}
+
+export default function dataMiddleware({
+  plan,
+  events,
+}) {
+  return [
+    (req, res, next) => {
+      /* ------------------------------------------------ Request decorations */
+
+      // CASA
+      req.casa = {
+        ...req?.casa,
+
+        // The plan
+        plan,
+
+        // Current journey context, loaded from session, specified by
+        // `contextid` request parameter
+        journeyContext: JourneyContext.extractContextFromRequest(req).addEventListeners(events),
+
+        // Edit mode
+        editMode: (has(req?.query, 'edit') && has(req?.query, 'editorigin')) || (has(req?.body, 'edit') && has(req?.body, 'editorigin')),
+        editOrigin: editOrigin(req),
+      };
+
+      // Grab chosen language from session
+      req.casa.journeyContext.nav.language = req.session.language;
+
+      /* ------------------------------------------------- Template variables */
+
+      // Capture mount URL that will be used in generating all browser URLs
+      const mountUrl = validateUrlPath(`${req.baseUrl}/`.replace(/\/+/g, '/'));
+
+      // If this CASA app is mounted on a parameterised route, then all of its
+      // static assets (served by `staticRouter`) will, by default, be served
+      // from that dynamic path, for example:
+      //   markup:       <link href="{{ mountUrl }}css/static.css" />
+      //   resolved URL: /mount/<some-id-here>/css/static.css
+      //   baseUrl:      /mount/<some-id>
+      //
+      // From a performance point of view, this is very inefficient as we can't
+      // take advantage of any intermediate caches. So we instead provide am
+      // alternative URL path in the `staticMountUrl` property that excludes the
+      // parameterised element, eg:
+      //   markup:       <link href="{{ staticMountUrl }}css/static.css" />
+      //   resolved URL: /mount/css/static.css
+      //   baseUrl:      /mount
+      //
+      // As the staticRouter is mounted on both the CASA app, and its internal
+      // Router, the `baseUrl` is different in each case, so we cannot rely
+      // on it to be consistent. Hence the need for this property, which will
+      // always be the non-parameterised version of the baseUrl.
+      const staticMountUrl = validateUrlPath(`${req.unparameterisedBaseUrl}/`.replace(/\/+/g, '/'));
+
+      // CASA and userland templates
+      res.locals.casa = {
+        mountUrl,
+        staticMountUrl,
+        editMode: req.casa.editMode,
+        editOrigin: req.casa.editOrigin,
+      };
+      res.locals.locale = req.language;
+
+      // Used by govuk-frontend template
+      //   htmlLang = req.language is provided by i18n-http-middleware
+      //   assetPath = used for linking to static assets in the govuk-frontend module
+      res.locals.htmlLang = req.language;
+      res.locals.assetPath = `${staticMountUrl}govuk/assets`;
+
+      // Function for building URLs. This will be curried with the `mountUrl`,
+      // `journeyContext`, `edit` and `editOrigin` for convenience. This means
+      // the template author does not have to be concerned about the current
+      // "state" when generating URLs, but still has the ability to override
+      // these curried defaults if needs be.
+      res.locals.waypointUrl = (args) => waypointUrl({
+        mountUrl,
+        journeyContext: req.casa.journeyContext,
+        edit: req.casa.editMode,
+        editOrigin: req.casa.editOrigin,
+        ...args,
+      });
+
+      next();
+    },
+  ];
+}

package/src/middleware/dirname.cjs

@@ -0,0 +1 @@
+module.exports = __dirname;

package/src/middleware/gather-fields.js

@@ -0,0 +1,58 @@
+// Gather the field data from `req.body` into the current JourneyContext
+// - Store in the current session
+// - Update the user's journey context with the new data
+// - Remove validation date of JourneyContext so it can re-evaluted
+
+import JourneyContext from '../lib/JourneyContext.js';
+import { REQUEST_PHASE_GATHER } from '../lib/constants.js';
+
+/**
+ * @access private
+ * @typedef {import('../lib/field').PageField} PageField
+ */
+
+/**
+ * Gather the field data from `req.body` into the current JourneyContext
+ * - Store in the current session
+ * - Update the user's journey context with the new data
+ * - Remove validation date of JourneyContext so it can re-evaluted
+ *
+ * @param {object} obj Options
+ * @param {string} obj.waypoint Waypoint
+ * @param {PageField[]} [obj.fields=[]] Fields
+ * @returns {Array} Array of middleware
+ */
+export default ({
+  waypoint,
+  fields = [],
+}) => [
+  (req, res, next) => {
+    // Store a copy of the journey context before modifying it. This is useful
+    // for any comparison work that may be done in subsequent middleware.
+    req.casa.archivedJourneyContext = JourneyContext.fromContext(req.casa.journeyContext);
+
+    // Ignore data for any non-persistent fields
+    // ESLint disabled as `fields`, `i` and `name` are dev-controlled
+    /* eslint-disable security/detect-object-injection */
+    const persistentBody = Object.create(null);
+    for (let i = 0, l = fields.length; i < l; i++) {
+      if (fields[i].meta.persist && fields[i].getValue(req.body) !== undefined) {
+        persistentBody[fields[i].name] = fields[i].getValue(req.body);
+      }
+    }
+    /* eslint-enable security/detect-object-injection */
+
+    // Update data and validation context in the current request, and store.
+    // The validation state is removed here because we must assume the gathered
+    // data is invalid until proven otherwise when the validation step is run.
+    req.casa.journeyContext.setDataForPage(waypoint, persistentBody);
+    req.casa.journeyContext.removeValidationStateForPage(waypoint);
+    JourneyContext.putContext(req.session, req.casa.journeyContext, {
+      userInfo: {
+        casaRequestPhase: REQUEST_PHASE_GATHER,
+      },
+    });
+
+    next();
+  },
+];

package/src/middleware/i18n.js

@@ -0,0 +1,106 @@
+import i18next from 'i18next';
+import { LanguageDetector, handle } from 'i18next-http-middleware';
+import { resolve, basename } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import deepmerge from 'deepmerge';
+import yaml from 'js-yaml';
+import logger from '../lib/logger.js';
+
+const log = logger('middleware:i18n');
+
+const loadJson = (file) => {
+  // Strip out newlines (this is a legacy feature which we're keeping for
+  // backwards compatibility).
+  const json = readFileSync(file, 'utf8');
+  return JSON.parse(json.replace(/[\r\n]/g, ''));
+}
+
+const loadYaml = (file) => yaml.load(readFileSync(file, 'utf8'))
+
+const extract = (file) => {
+  const ext = /.yaml$/i.test(file) ? '.yaml' : '.json';
+  const data = ext === '.yaml' ? loadYaml(file) : loadJson(file);
+
+  return {
+    ns: basename(file, ext),
+    data,
+  };
+}
+
+const loadResources = (languages, directories) => {
+  const store = Object.create(null);
+
+  languages.forEach((language) => {
+    // ESLint disabled as `store`, `language` and `ns` are all dev-controlled,
+    // and this function is only called once, at boot-time.
+    /* eslint-disable security/detect-object-injection */
+    store[language] = Object.create(null);
+
+    directories.forEach((basedir) => {
+      const dir = resolve(basedir, language);
+      if (!existsSync(dir)) {
+        return;
+      }
+
+      log.info('Loading %s language from %s ...', language, dir);
+      readdirSync(dir).forEach((file) => {
+        const { ns, data } = extract(resolve(dir, file));
+
+        if (store[language][ns] === undefined) {
+          store[language][ns] = Object.create(null);
+        }
+
+        store[language][ns] = deepmerge(store[language][ns], data);
+      });
+    });
+    /* eslint-enable security/detect-object-injection */
+  });
+
+  return store;
+}
+
+export default function i18nMiddleware({
+  languages = ['en', 'cy'],
+  directories = [],
+}) {
+  // Load _all_ translations, from all directories into memory.
+  const resources = loadResources(languages, directories);
+
+  // Configure i18next
+  const i18nInstance = i18next.createInstance();
+  i18nInstance
+    .use(LanguageDetector)
+    .init({
+      initImmediate: false, // because we need synchronous loading
+      supportedLngs: languages,
+      fallbackLng: false,
+      defaultNS: 'common',
+      // debug: true,
+
+      // All translation resources
+      resources,
+
+      // LanguageDetector options
+      detection: {
+        lookupQuerystring: 'lang',
+        lookupSession: 'language',
+        order: ['querystring', 'session'],
+      },
+    });
+
+  // 2 middleware: one to read/set the session language, and one to enhance the
+  // req/res objects with i18n features
+  return [
+    (req, res, next) => {
+      if (!req.session.language) {
+        /* eslint-disable-next-line prefer-destructuring */
+        req.session.language = languages[0];
+      }
+      if (req?.query.lang && languages.includes(req.query.lang)) {
+        req.session.language = String(req.query.lang);
+      }
+      next();
+    },
+    handle(i18nInstance),
+  ];
+}

package/src/middleware/post.js

@@ -0,0 +1,61 @@
+// 2 middleware: one as a fallback 404 handler, one to handle thrown errors
+import logger from '../lib/logger.js';
+
+const log = logger('middleware:post');
+
+export default function postMiddleware() {
+  return [
+    (req, res) => {
+      res.status(404).render('casa/errors/404.njk');
+    },
+    /* eslint-disable-next-line no-unused-vars */
+    (err, req, res, next) => {
+      // In some cases, an error may have been thrown before the template assets
+      // have had a chance to initialise. So we use a hardcoded template in
+      // these cases to ensure the user sees an appropriate message.
+      let TEMPLATE = 'casa/errors/500.njk';
+      if (!res.locals.t) {
+        res.locals.t = () => ('');
+        res.locals.casa = {
+          ...res.locals?.casa,
+          mountUrl: `${req.baseUrl}/`,
+        };
+        TEMPLATE = 'casa/errors/static.njk';
+      }
+
+      // CSRF token is invalid in some way
+      if (err?.code === 'EBADCSRFTOKEN') {
+        log.info('CSRF validation has failed. This may be caused by the user submitting a stale form from a previous session [EBADCSRFTOKEN]');
+        return res.status(403).render(TEMPLATE, { errorCode: 'bad_csrf_token', error: err });
+      }
+
+      // Body parsing verification check failed
+      if (err?.type === 'entity.verify.failed') {
+        log.info('Body parser verification has failed. This has been caused by the user submitting a payload containing invalid data [entity.verify.failed]');
+        return res.status(403).render(TEMPLATE, { errorCode: 'invalid_payload', error: err });
+      }
+
+      // Too many parameters submitted
+      if (err?.type === 'parameters.too.many') {
+        log.info('The request contains more parameters than is currently allowed [parameters.too.many]');
+        return res.status(413).render(TEMPLATE, { errorCode: 'parameter_limit_exceeded', error: err });
+      }
+
+      // Overall payload too large
+      if (err?.type === 'entity.too.large') {
+        log.info(`The request payload is too large. Received ${err.length}b with a maximum of ${err.limit}b [parameters.too.many]`);
+        return res.status(413).render(TEMPLATE, { errorCode: 'payload_size_exceeded', error: err });
+      }
+
+      // Unaccept request method
+      if (err?.code === 'unaccepted_request_method') {
+        log.info(err.message);
+        return res.status(400).render(TEMPLATE, { errorCode: 'unaccepted_request_method', error: err });
+      }
+
+      // Unknown error
+      log.error(`Unknown error: ${err.message}; stacktrace: ${err.stack}`);
+      return res.status(200).render(TEMPLATE, { error: err });
+    },
+  ]
+}

package/src/middleware/pre.js

@@ -0,0 +1,91 @@
+import { randomBytes } from 'crypto';
+import helmet from 'helmet';
+
+/**
+ * @access private
+ * @typedef {import('../casa').HelmetConfigurator} HelmetConfigurator
+ */
+
+const GA_DOMAIN = '*.google-analytics.com';
+const GA_ANALYTICS_DOMAIN = '*.analytics.google.com';
+const GTM_DOMAIN = '*.googletagmanager.com';
+const GTM_PREVIEW_DOMAIN = 'https://tagmanager.google.com';
+
+/**
+ * Extracts the CSP nonce used in every template, and makes it available as a
+ * nonce value in the CSP header.
+ *
+ * IMPORTANT: Do not rename this function as it _might_ be used in consumer code
+ * to identify this function specifically, most likely to remove it from CSP
+ * headers for custom purposes.
+ *
+ * @param {import('express').Request} req Request
+ * @param {import('express').Response} res Response
+ * @returns {string} nonce value suitable for use in CSP header
+ */
+function casaCspNonce(req, res) {
+  return `'nonce-${res.locals.cspNonce}'`;
+}
+
+/**
+ * Pre middleware.
+ *
+ * @param {object} opts Options
+ * @param {HelmetConfigurator} opts.helmetConfigurator Function to customise Helmet configuration
+ * @returns {Function[]} List of middleware
+ */
+export default ({
+  helmetConfigurator = (config) => (config),
+} = {}) => [
+  // Only allow certain request methods
+  (req, res, next) => {
+    if (req.method !== 'GET' && req.method !== 'POST') {
+      const err = new Error(`Unaccepted request method, "${String(req.method).substr(0, 7)}"`);
+      err.code = 'unaccepted_request_method';
+      next(err);
+    } else {
+      next();
+    }
+  },
+
+  // Prevent caching response in any intermediaries by default, in case it
+  // contains sensitive data.
+  // The `no-store` setting is to specifically disable the bfcache and prevent
+  // possible leakage of information.
+  (req, res, next) => {
+    res.set('cache-control', 'no-cache, no-store, must-revalidate, private');
+    res.set('pragma', 'no-cache');
+    res.set('expires', 0);
+    res.set('x-robots-tag', 'noindex, nofollow');
+    next();
+  },
+
+  // Generate nonces ready for use in Content-Security-Policy header and
+  // govuk-frontend template. This same none can be used wherever required.
+  (req, res, next) => {
+    res.locals.cspNonce = randomBytes(16).toString('hex');
+    next();
+  },
+
+  // Helmet suite of headers
+  helmet(helmetConfigurator({
+    // Allows GA which is typically used, and a known inline script nonce
+    contentSecurityPolicy: {
+      useDefaults: true,
+      directives: {
+        'default-src': ["'none'"],
+        'script-src': ["'self'", GA_DOMAIN, GTM_DOMAIN, GTM_PREVIEW_DOMAIN, casaCspNonce],
+        'img-src': ["'self'", GA_DOMAIN, GA_ANALYTICS_DOMAIN, GTM_DOMAIN, 'https://ssl.gstatic.com', 'https://www.gstatic.com'],
+        'connect-src': ["'self'", GA_DOMAIN, GA_ANALYTICS_DOMAIN, GTM_DOMAIN],
+        'frame-src': ["'self'", GTM_DOMAIN],
+        'frame-ancestors': ["'self'"],
+        'form-action': ["'self'"],
+        'style-src': ["'self'", 'https://fonts.googleapis.com', GTM_PREVIEW_DOMAIN, casaCspNonce],
+        'font-src': ["'self'", 'data:', 'https://fonts.gstatic.com'],
+      },
+    },
+
+    // // Require referrer to aid navigation
+    // referrerPolicy: 'no-referrer, same-origin',
+  })),
+];