@dwp/govuk-casa 8.16.2 → 8.16.4

package/src/lib/waypoint-url.js

@@ -4,7 +4,7 @@
  */
 
 /** @access private */
-const reUrlProtocolExtract = /^url:\/\/(.+)$/i
+const reUrlProtocolExtract = /^url:\/\/(.+)$/i;
 
 /**
  * Sanitise a waypoint string.
@@ -13,7 +13,8 @@ const reUrlProtocolExtract = /^url:\/\/(.+)$/i
  * @param {string} w Waypoint
  * @returns {string} Sanitised waypoint
  */
-const sanitiseWaypoint = (w) => w.replace(/[^/a-z0-9_-]/ig, '').replace(/\/+/g, '/');
+const sanitiseWaypoint = (w) =>
+  w.replace(/[^/a-z0-9_-]/gi, "").replace(/\/+/g, "/");
 
 /**
  * Sanitise a waypoint string, with allowed URL parameters:
@@ -25,7 +26,7 @@ const sanitiseWaypoint = (w) => w.replace(/[^/a-z0-9_-]/ig, '').replace(/\/+/g,
  */
 const sanitiseWaypointWithAllowedParams = (w) => {
   // Extract URL params
-  const parts = w.split('?');
+  const parts = w.split("?");
   if (parts.length !== 2) {
     return sanitiseWaypoint(w);
   }
@@ -34,14 +35,17 @@ const sanitiseWaypointWithAllowedParams = (w) => {
 
   // Strip all but those parameters allowed
   const validatedUrlSearchParams = new URLSearchParams();
-  for (const pk of ['contextid']) {
+  for (const pk of ["contextid"]) {
     if (urlSearchParams.has(pk)) {
       validatedUrlSearchParams.set(pk, urlSearchParams.get(pk));
     }
   }
 
-  return `${sanitiseWaypoint(waypoint)}?${validatedUrlSearchParams.toString()}`.replace(/\?$/, '');
-}
+  return `${sanitiseWaypoint(waypoint)}?${validatedUrlSearchParams.toString()}`.replace(
+    /\?$/,
+    "",
+  );
+};
 
 /**
  * Generate a URL pointing at a particular waypoint.
@@ -56,41 +60,49 @@ const sanitiseWaypointWithAllowedParams = (w) => {
  * })
  * @memberof module:@dwp/govuk-casa
  * @param {object} obj Options
- * @param {string} [obj.waypoint=""] Waypoint
- * @param {string} [obj.mountUrl="/"] Mount URL
+ * @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 {boolean} [obj.edit] 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
+ * @param {string} [obj.routeName] 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');
+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:///') {
+  if (String(waypoint).substr(0, 7) === "url:///") {
     const m = waypoint.match(reUrlProtocolExtract);
 
-    const u = new URL(sanitiseWaypointWithAllowedParams(m[1]), 'https://placeholder.test/');
+    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);
+    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/');
+    const u = new URL(
+      sanitiseWaypointWithAllowedParams(`${mountUrl}${waypoint}`),
+      "https://placeholder.test/",
+    );
     url.pathname = u.pathname;
     url.search = u.search;
   }
@@ -100,26 +112,29 @@ export default function waypointUrl({
   // 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}/`)
+    journeyContext &&
+    !journeyContext.isDefault() &&
+    journeyContext.identity.id &&
+    !mountUrl.includes(`/${journeyContext.identity.id}/`)
   ) {
-    url.searchParams.set('contextid', journeyContext.identity.id);
+    url.searchParams.set("contextid", journeyContext.identity.id);
   }
 
   // Attach edit mode flag
   if (edit === true) {
-    url.searchParams.set('edit', 'true');
+    url.searchParams.set("edit", "true");
   }
 
   if (edit && editOrigin) {
-    url.searchParams.set('editorigin', sanitiseWaypointWithAllowedParams(editOrigin));
+    url.searchParams.set(
+      "editorigin",
+      sanitiseWaypointWithAllowedParams(editOrigin),
+    );
   }
 
   // Skipto
   if (skipTo) {
-    url.searchParams.set('skipto', sanitiseWaypointWithAllowedParams(skipTo));
+    url.searchParams.set("skipto", sanitiseWaypointWithAllowedParams(skipTo));
   }
 
   return `${sanitiseWaypoint(url.pathname)}${url.search}`;

package/src/middleware/body-parser.js

@@ -1,30 +1,64 @@
-import { urlencoded as expressBodyParser } from 'express';
+import { urlencoded as expressBodyParser } from "express";
+
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("express").Request} Request
+ * @access private
+ */
+
+/**
+ * @typedef {import("express").Response} Response
+ * @access private
+ */
 
 const rProto = /__proto__/i;
 const rPrototype = /prototype[='"[\]]/i;
 const rConstructor = /constructor[='"[\]]/i;
 
+/**
+ * Verify request body.
+ *
+ * @param {Request} req HTTP request
+ * @param {Response} res HTTP response
+ * @param {Buffer} buf Buffer
+ * @param {string} encoding Character encoding
+ * @returns {void}
+ * @throws {Error} For invalid bodies
+ */
 export function verifyBody(req, res, buf, encoding) {
-  const body = decodeURI(buf.toString(encoding)).replace(/[\s\u200B-\u200D\uFEFF]/g, '');
+  const body = decodeURI(buf.toString(encoding)).replace(
+    /[\s\u200B-\u200D\uFEFF]/g,
+    "",
+  );
   if (rProto.test(body)) {
-    throw new Error('Request body verification failed (__proto__)');
+    throw new Error("Request body verification failed (__proto__)");
   }
   if (rPrototype.test(body)) {
-    throw new Error('Request body verification failed (prototype)');
+    throw new Error("Request body verification failed (prototype)");
   }
   if (rConstructor.test(body)) {
-    throw new Error('Request body verification failed (constructor)');
+    throw new Error("Request body verification failed (constructor)");
   }
 }
 
-export default function bodyParserMiddleware({
-  formMaxParams,
-  formMaxBytes,
-}) {
+/**
+ * Body parsing middleware.
+ *
+ * @param {object} opts Options
+ * @param {number} opts.formMaxParams Max number of parameters that should be
+ *   parsed
+ * @param {number} opts.formMaxBytes Max bytes that should be read
+ * @returns {RequestHandler[]} Middleware functions
+ */
+export default function bodyParserMiddleware({ formMaxParams, formMaxBytes }) {
   return [
     expressBodyParser({
       extended: true,
-      type: 'application/x-www-form-urlencoded',
+      type: "application/x-www-form-urlencoded",
       inflate: true,
       parameterLimit: formMaxParams,
       limit: formMaxBytes,

package/src/middleware/csrf.js

@@ -1,9 +1,12 @@
-import { csrfSync } from 'csrf-sync';
+import { csrfSync } from "csrf-sync";
 
 // 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() {
   const { csrfSynchronisedProtection } = csrfSync({
     getTokenFromRequest: (req) => req.body._csrf,

package/src/middleware/data.js

@@ -1,28 +1,57 @@
 // 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';
+import lodash from "lodash";
+import JourneyContext from "../lib/JourneyContext.js";
+import { validateUrlPath } from "../lib/utils.js";
+import waypointUrl from "../lib/waypoint-url.js";
+
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").Plan} Plan
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").ContextEventHandler} ContextEventHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa.js").ContextIdGenerator} ContextIdGenerator
+ * @access private
+ */
 
 const { has } = lodash;
 
 const editOrigin = (req) => {
-  if (has(req.query, 'editorigin')) {
+  if (has(req.query, "editorigin")) {
     return waypointUrl({ waypoint: req.query.editorigin });
   }
-  if (has(req?.body, 'editorigin')) {
+  if (has(req?.body, "editorigin")) {
     return waypointUrl({ waypoint: req.body.editorigin });
   }
-  return '';
-}
-
-export default function dataMiddleware({
-  plan,
-  events,
-  contextIdGenerator,
-}) {
+  return "";
+};
+
+/**
+ * Data middleware.
+ *
+ * Decorates the request with some contextual data about the user's journey
+ * through the application. This is used by downstream middleware and
+ * templates.
+ *
+ * @param {object} opts Options
+ * @param {Plan} opts.plan CASA Plan
+ * @param {ContextEventHandler[]} opts.events Event handlers
+ * @param {ContextIdGenerator} opts.contextIdGenerator Content ID generator
+ * @returns {RequestHandler[]} Middleware functions
+ */
+export default function dataMiddleware({ plan, events, contextIdGenerator }) {
   return [
     (req, res, next) => {
       /* ------------------------------------------------ Request decorations */
@@ -36,10 +65,15 @@ export default function dataMiddleware({
 
         // Current journey context, loaded from session, specified by
         // `contextid` request parameter
-        journeyContext: JourneyContext.extractContextFromRequest(req).addEventListeners(events),
+        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')),
+        editMode:
+          (has(req?.query, "edit") && has(req?.query, "editorigin")) ||
+          (has(req?.body, "edit") && has(req?.body, "editorigin")),
         editOrigin: editOrigin(req),
       };
 
@@ -56,7 +90,7 @@ export default function dataMiddleware({
       /* ------------------------------------------------- Template variables */
 
       // Capture mount URL that will be used in generating all browser URLs
-      const mountUrl = validateUrlPath(`${req.baseUrl}/`.replace(/\/+/g, '/'));
+      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
@@ -77,7 +111,9 @@ export default function dataMiddleware({
       // 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, '/'));
+      const staticMountUrl = validateUrlPath(
+        `${req.unparameterisedBaseUrl}/`.replace(/\/+/g, "/"),
+      );
 
       // CASA and userland templates
       res.locals.casa = {
@@ -99,13 +135,14 @@ export default function dataMiddleware({
       // 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,
-      });
+      res.locals.waypointUrl = (args) =>
+        waypointUrl({
+          mountUrl,
+          journeyContext: req.casa.journeyContext,
+          edit: req.casa.editMode,
+          editOrigin: req.casa.editOrigin,
+          ...args,
+        });
 
       next();
     },

package/src/middleware/gather-fields.js

@@ -3,8 +3,8 @@
 // - 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';
+import JourneyContext from "../lib/JourneyContext.js";
+import { REQUEST_PHASE_GATHER } from "../lib/constants.js";
 
 /**
  * @access private
@@ -19,13 +19,10 @@ import { REQUEST_PHASE_GATHER } from '../lib/constants.js';
  *
  * @param {object} obj Options
  * @param {string} obj.waypoint Waypoint
- * @param {PageField[]} [obj.fields=[]] Fields
+ * @param {PageField[]} [obj.fields] Fields
  * @returns {Array} Array of middleware
  */
-export default ({
-  waypoint,
-  fields = [],
-}) => [
+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.
@@ -39,7 +36,10 @@ export default ({
     /* 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) {
+      if (
+        fields[i].meta.persist &&
+        fields[i].getValue(req.body) !== undefined
+      ) {
         persistentBody[fields[i].name] = fields[i].getValue(req.body);
       }
     }

package/src/middleware/i18n.js

@@ -1,33 +1,38 @@
-import { createInstance } 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';
+import { createInstance } 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 { load as jsYamlLoad } from "js-yaml";
+import logger from "../lib/logger.js";
 
-const log = logger('middleware:i18n');
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
+
+const log = logger("middleware:i18n");
 
 const loadJson = (file) => {
   // Strip out newlines (this is a legacy feature which we're keeping for
   // backwards compatibility).
   /* eslint-disable-next-line security/detect-non-literal-fs-filename */
-  const json = readFileSync(file, 'utf8');
-  return JSON.parse(json.replace(/[\r\n]/g, ''));
-}
+  const json = readFileSync(file, "utf8");
+  return JSON.parse(json.replace(/[\r\n]/g, ""));
+};
 
 /* eslint-disable-next-line security/detect-non-literal-fs-filename */
-const loadYaml = (file) => yaml.load(readFileSync(file, 'utf8'))
+const loadYaml = (file) => jsYamlLoad(readFileSync(file, "utf8"));
 
 const extract = (file) => {
-  const ext = /.yaml$/i.test(file) ? '.yaml' : '.json';
-  const data = ext === '.yaml' ? loadYaml(file) : loadJson(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);
@@ -45,7 +50,7 @@ const loadResources = (languages, directories) => {
         return;
       }
 
-      log.info('Loading %s language from %s ...', language, dir);
+      log.info("Loading %s language from %s ...", language, dir);
       /* eslint-disable-next-line security/detect-non-literal-fs-filename */
       readdirSync(dir).forEach((file) => {
         const { ns, data } = extract(resolve(dir, file));
@@ -61,10 +66,18 @@ const loadResources = (languages, directories) => {
   });
 
   return store;
-}
-
+};
+
+/**
+ * Internationalisation middleware.
+ *
+ * @param {object} opts Options
+ * @param {string[]} [opts.languages] Language codes
+ * @param {string[]} [opts.directories] Source translations directories
+ * @returns {RequestHandler[]} Middleware functions
+ */
 export default function i18nMiddleware({
-  languages = ['en', 'cy'],
+  languages = ["en", "cy"],
   directories = [],
 }) {
   // Load _all_ translations, from all directories into memory.
@@ -72,32 +85,29 @@ export default function i18nMiddleware({
 
   // Configure i18next
   const i18nInstance = 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'],
-      },
-    });
+  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)) {

package/src/middleware/post.js

@@ -1,61 +1,87 @@
 // 2 middleware: one as a fallback 404 handler, one to handle thrown errors
-import logger from '../lib/logger.js';
+import logger from "../lib/logger.js";
 
-const log = logger('middleware:post');
+/**
+ * @typedef {import("express").RequestHandler} RequestHandler
+ * @access private
+ */
 
+const log = logger("middleware:post");
+
+/** @returns {RequestHandler[]} Middleware functions */
 export default function postMiddleware() {
   return [
     (req, res) => {
-      res.status(404).render('casa/errors/404.njk');
+      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';
+      let TEMPLATE = "casa/errors/500.njk";
       if (!res.locals.t) {
-        res.locals.t = () => ('');
+        res.locals.t = () => "";
         res.locals.casa = {
           ...res.locals?.casa,
           mountUrl: `${req.baseUrl}/`,
         };
-        TEMPLATE = 'casa/errors/static.njk';
+        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 });
+      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 });
+      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 });
+      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 });
+      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') {
+      if (err?.code === "unaccepted_request_method") {
         log.info(err.message);
-        return res.status(400).render(TEMPLATE, { errorCode: 'unaccepted_request_method', error: err });
+        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 });
     },
-  ]
+  ];
 }