@dwp/govuk-casa 8.7.12 → 8.9.0

package/src/middleware/progress-journey.js

@@ -0,0 +1,96 @@
+// Determine where to take the user next
+// We assume that the waypoint has been validated prior to reaching this
+// middleware.
+
+import Plan from '../lib/Plan.js';
+import JourneyContext from '../lib/JourneyContext.js';
+import waypointUrl from '../lib/waypoint-url.js';
+import logger from '../lib/logger.js';
+import { REQUEST_PHASE_REDIRECT } from '../lib/constants.js';
+
+const log = logger('middleware:progress-journey');
+
+const saveAndRedirect = (session, journeyContext, url, res, next) => {
+  JourneyContext.putContext(session, journeyContext, {
+    userInfo: {
+      casaRequestPhase: REQUEST_PHASE_REDIRECT,
+    },
+  });
+
+  session.save((err) => {
+    if (err) {
+      next(err);
+    }
+    res.redirect(302, url);
+  });
+};
+
+export default ({
+  waypoint,
+  plan,
+}) => [
+  (req, res, next) => {
+    // Determine the next available waypoint after the current one
+    const traversed = plan.traverse(req.casa.journeyContext);
+    const currentIndex = traversed.indexOf(waypoint);
+    const nextIndex = Math.max(
+      currentIndex < 0 ? traversed.length - 1 : 0,
+      Math.min(currentIndex + 1, traversed.length - 1),
+    );
+    const nextWaypoint = traversed[parseInt(nextIndex, 10)];
+    log.trace(`currentIndex = ${currentIndex}, nextIndex = ${nextIndex}, currentWaypoint = ${waypoint}, nextWaypoint = ${nextWaypoint}`);
+
+    // Edit mode
+    // Attempt to take the user back to their original URL. We rely on the
+    // `steer-journey` middleware to prevent the user going too far ahead in
+    // their permitted journey. Bear in mind that the `editOrigin` may not be
+    // a waypoint at all, but a route path for a custom endpoint, so we can't
+    // safely do a traversal check here.
+    //
+    // The edit mode URL params will be kept on this redirect. This means the
+    // user can keep "jumping" to the next _changed_ waypoint, until they get
+    // back to the original URL.
+    //
+    // Devs should use the `events` mechanism to mark waypoints as invalid if
+    // they want to force the user to re-visit particular waypoints during this
+    // "jumping" phase.
+    if (req.casa.editMode && req.casa.editOrigin) {
+      const url = new URL(req.casa.editOrigin, 'https://placeholder.test/');
+      url.searchParams.append('edit', 'true');
+      url.searchParams.append('editorigin', req.casa.editOrigin);
+      const redirectUrl = waypointUrl({ waypoint: url.pathname }) + url.search.toString();
+
+      log.debug(`Edit mode detected; redirecting to ${redirectUrl}`);
+
+      return saveAndRedirect(req.session, req.casa.journeyContext, redirectUrl, res, next);
+    }
+
+    // If the next URL is an "exit node", we need to flag that node as
+    // being validated so that subsequent traversals of this journey continue
+    // correctly to any waypoints leading on from this one.
+    // This effectively says that the other Plan linked to by the exit node is
+    // complete, but of course that may not be the case.
+    // It would be prudent for developers to add a conditions to the route to
+    // check is this is the case, eg
+    //   setRoute('a', 'b');
+    //   setRoute('b', 'url:///otherapp/')
+    //   setRoute('url:////otherapp/', 'c', (r, c) => checkIfOtherAppIsFinished())
+    if (Plan.isExitNode(nextWaypoint)) {
+      log.trace(`Next waypoint is an exit node; clearing validation state on ${nextWaypoint}`);
+      req.casa.journeyContext.clearValidationErrorsForPage(nextWaypoint);
+    }
+
+    // Construct the next url
+    const nextUrl = waypointUrl({
+      waypoint: nextWaypoint,
+      mountUrl: `${req.baseUrl}/`,
+      journeyContext: req.casa.journeyContext,
+      edit: req.casa.editMode,
+      editOrigin: req.casa.editOrigin,
+    });
+
+    // Save and move on
+    log.trace(`Redirecting to ${nextUrl}`);
+    return saveAndRedirect(req.session, req.casa.journeyContext, nextUrl, res, next);
+  },
+];

package/src/middleware/sanitise-fields.js

@@ -0,0 +1,58 @@
+// Sanitise the fields submitted from a form
+// - Coerce each field to its correct type
+// - Remove an extraneous fields that are not know to the application
+
+import _ from 'lodash';
+import fieldFactory from '../lib/field.js';
+import JourneyContext from '../lib/JourneyContext.js';
+
+export default ({
+  waypoint,
+  fields = [],
+}) => {
+  // Add some common, transient fields to ensure they survive beyond this sanitisation process
+  fields.push(fieldFactory('_csrf', { persist: false }).processor((value) => String(value)));
+  fields.push(fieldFactory('contextid', { persist: false }).processor((value) => String(value)));
+  fields.push(fieldFactory('edit', { persist: false }).processor((value) => String(value)));
+  fields.push(fieldFactory('editorigin', { persist: false }).processor((value) => String(value)));
+
+  // Middleware
+  return [
+    (req, res, next) => {
+      // First, prune all undefined, or unknown fields from `req.body` (i.e.
+      // those that do not have an entry in `fields`)
+      // EsLint disabled as `fields`, `i` & `name` are only controlled by dev
+      /* eslint-disable security/detect-object-injection */
+      const prunedBody = Object.create(null);
+      for (let i = 0, l = fields.length; i < l; i++) {
+        if (_.has(req.body, fields[i].name) && req.body[fields[i].name] !== undefined) {
+          prunedBody[fields[i].name] = req.body[fields[i].name];
+        }
+      }
+      /* eslint-enable security/detect-object-injection */
+
+      const journeyContext = JourneyContext.fromContext(req.casa.journeyContext);
+      journeyContext.setDataForPage(waypoint, prunedBody);
+
+      // Second, prune any fields that do not pass the validation conditional,
+      // and process those that do.
+      const sanitisedBody = Object.create(null);
+      for (let i = 0, l = fields.length; i < l; i++) {
+        const field = fields[i]; /* eslint-disable-line security/detect-object-injection */
+        const fieldValue = field.getValue(prunedBody);
+
+        if (fieldValue !== undefined && field.testConditions({
+          fieldValue,
+          waypoint,
+          journeyContext,
+        })) {
+          field.putValue(sanitisedBody, field.applyProcessors(fieldValue));
+        }
+      }
+
+      // Finally, write the sanitised body back to the request object
+      req.body = sanitisedBody;
+      next();
+    },
+  ];
+}

package/src/middleware/serve-first-waypoint.js

@@ -0,0 +1,28 @@
+import { validateUrlPath } from '../lib/utils.js';
+
+/**
+ * @access private
+ * @typedef {import('express').RequestHandler} ExpressRequestHandler
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').Plan} Plan
+ */
+
+/**
+ * Redirect the user to the first Plan waypoint when they request the root /
+ * path.
+ *
+ * @param {Plan} plan CASA Plan
+ * @returns {ExpressRequestHandler[]} Array of middleware
+ */
+export default ({
+  plan,
+}) => [(req, res) => {
+  const reqUrl = new URL(req.url, 'https://placeholder.test/');
+  const reqPath = validateUrlPath(`${req.baseUrl}${reqUrl.pathname}${plan.getWaypoints()[0]}`);
+  let reqParams = reqUrl.searchParams.toString();
+  reqParams = reqParams ? `?${reqParams}` : '';
+  res.redirect(302, `${reqPath}${reqParams}`);
+}];

package/src/middleware/session.js

@@ -0,0 +1,129 @@
+// A last-modified cookie is used to control whether the end user sees a
+// session-timeout page, or they are simply given a new session without
+// interrupting their journey.
+import expressSession, { MemoryStore } from 'express-session';
+import logger from '../lib/logger.js';
+import { validateUrlPath } from '../lib/utils.js';
+
+const log = logger('middleware:session');
+
+const sessionExpiryMiddleware = (
+  ttl,
+  getCookie,
+  touchCookie,
+  removeCookie,
+) => (req, res, next) => {
+  const lastModified = getCookie(req);
+  const age = Math.floor(Date.now() * 0.001) - lastModified;
+
+  if (lastModified === 0) {
+    // New session, or grace period cookie no longer available after
+    // expiring; generate a new session, and create grace-period cookie.
+    // This will invalidate any CSRF tokens, so by letting the request POST
+    // requests through the user may see a 500 error response.
+    log.info('Session is new, or grace period has expired. Regenerating session.');
+    req.session.regenerate((err) => {
+      if (err) {
+        next(err);
+      } else {
+        touchCookie(res);
+        if (req.method === 'POST') {
+          log.info('The CSRF token for this POST request will now be invalid for this regenerated session. Redirecting to app mount point.');
+          res.redirect(302, validateUrlPath(`${req.baseUrl}/`));
+        } else {
+          next();
+        }
+      }
+    });
+  } else if (age > ttl) {
+    // Cookie has become stale and server session will have been removed;
+    // redirect to session-timeout
+    log.info('Session has timed out within grace period. Destroying session and redirecting to timeout page.');
+    const language = req.session.language ?? 'en';
+    req.session.destroy((err) => {
+      if (err) {
+        next(err);
+      } else {
+        removeCookie(res);
+        const params = new URLSearchParams({
+          referrer: req.originalUrl,
+          lang: language,
+        });
+        /* eslint-disable-next-line prefer-template */
+        res.redirect(302, validateUrlPath(`${req.baseUrl}/session-timeout`) + `?${params.toString()}`);
+      }
+    });
+  } else {
+    // Touch cookie and continue
+    touchCookie(res);
+    next();
+  }
+};
+
+// 3 middleware:
+// - set the session cookie
+// - parse request cookies
+// - handle expiry of server-side session
+export default function sessionMiddleware({
+  cookieParserMiddleware,
+  secret,
+  name,
+  secure,
+  ttl,
+  cookieSameSite = true,
+  cookiePath = '/',
+  store = new MemoryStore(),
+}) {
+  const commonCookieOptions = {
+    httpOnly: true,
+    path: cookiePath,
+    secure,
+  };
+
+  if (cookieSameSite !== false) {
+    commonCookieOptions.sameSite = cookieSameSite === true ? 'Strict' : cookieSameSite;
+  }
+
+  const ttlGrace = 1800; // user will see session-timeout if session expires within 30mins
+  const touchCookieName = `${name}.t`;
+  const touchCookieOptions = {
+    ...commonCookieOptions,
+    maxAge: (ttl + ttlGrace) * 1000,
+    signed: true,
+  };
+
+  const getCookie = (req) => {
+    // Disabled eslint as `touchCookieName` is a constant, known value
+    /* eslint-disable-next-line security/detect-object-injection */
+    const lastModified = Date.parse(String(req.signedCookies[touchCookieName] ?? '1970-01-01T00:00:00+0000'));
+    return Number.isNaN(lastModified) ? 0 : Math.floor(lastModified * 0.001);
+  }
+
+  const touchCookie = (res) => {
+    // Touch cookie expiry is a short period after the session ttl. This gives
+    // a small period of time where a user will see the session-timeout message,
+    // which is important to avoid the confusion of simply being redirected back
+    // to the start of their journey.
+    res.cookie(touchCookieName, (new Date(Date.now())).toUTCString(), touchCookieOptions);
+  }
+
+  const removeCookie = (res) => {
+    res.clearCookie(touchCookieName, touchCookieOptions);
+  }
+
+  return [
+    expressSession({
+      secret,
+      name,
+      saveUninitialized: false,
+      resave: false,
+      cookie: {
+        ...commonCookieOptions,
+        maxAge: null,
+      },
+      store,
+    }),
+    cookieParserMiddleware,
+    sessionExpiryMiddleware(ttl, getCookie, touchCookie, removeCookie),
+  ];
+}

package/src/middleware/skip-waypoint.js

@@ -0,0 +1,46 @@
+// Mark a waypoint as skipped
+
+import lodash from 'lodash';
+import JourneyContext from '../lib/JourneyContext.js';
+import waypointUrl from '../lib/waypoint-url.js';
+import logger from '../lib/logger.js';
+
+const { has } = lodash;
+
+const log = logger('middleware:skip-waypoint');
+
+export default ({
+  waypoint,
+}) => [
+  (req, res, next) => {
+    if (!has(req.query, 'skipto')) {
+      return next();
+    }
+    const skipTo = String(req.query.skipto);
+
+    // Inject a special `__skipped__` attribute into this waypoint's data
+    log.info(`Marking waypoint "${waypoint}" as skipped`);
+    req.casa.journeyContext.clearValidationErrorsForPage(waypoint);
+    req.casa.journeyContext.setDataForPage(waypoint, {
+      __skipped__: true,
+    });
+    JourneyContext.putContext(req.session, req.casa.journeyContext);
+
+    const redirectUrl = waypointUrl({
+      mountUrl: `${req.baseUrl}/`,
+      waypoint: skipTo,
+      edit: req.casa.editMode,
+      editOrigin: req.casa.editOrigin,
+      journeyContext: req.casa.journeyContext,
+    });
+    log.debug(`Will redirect to "${redirectUrl}" after skipping "${waypoint}"`);
+
+    return req.session.save((err) => {
+      if (err) {
+        next(err);
+      } else {
+        res.redirect(302, redirectUrl);
+      }
+    });
+  },
+];

package/src/middleware/steer-journey.js

@@ -0,0 +1,79 @@
+// This sits in front of all other middleware and prevents the user from
+// "jumping ahead" in the Plan.
+
+import waypointUrl from '../lib/waypoint-url.js';
+import logger from '../lib/logger.js';
+
+const log = logger('middleware:steer-journey');
+
+/**
+ * @access private
+ * @typedef {import('../lib/Plan')} Plan
+ */
+
+/**
+ * This sits in front of all other journey middleware and prevents the user from
+ * "jumping ahead" in the Plan.
+ *
+ * @param {object} obj Options
+ * @param {string} obj.waypoint Current waypoint
+ * @param {Plan} obj.plan CASA Plan
+ * @returns {void}
+ */
+export default ({
+  waypoint,
+  plan,
+}) => [
+  (req, res, next) => {
+    const mountUrl = `${req.baseUrl}/`;
+
+    // If the requested waypoint doesn't exist in the traversed journey, send
+    // the user back to the last good waypoint.
+    const traversed = plan.traverse(req.casa.journeyContext);
+    if (traversed.indexOf(waypoint) === -1) {
+      const redirectTo = traversed[traversed.length - 1];
+      log.trace(`Attempted to access "${waypoint}" when not in the journey; redirecting to "${redirectTo}"`);
+
+      return res.redirect(302, waypointUrl({
+        waypoint: redirectTo,
+        mountUrl,
+        journeyContext: req.casa.journeyContext,
+        edit: req.casa.editMode,
+        editOrigin: req.casa.editOrigin,
+      }));
+    }
+
+    // Edit mode
+    // Cannot be in edit mode if we're already on the `editorigin` URL
+    if (req.casa.editMode) {
+      const { pathname: currentPathname } = new URL(req.originalUrl, 'https://placeholder.test/');
+
+      if (req.casa.editOrigin === currentPathname) {
+        log.debug(`Disabling edit mode as we are on the edit origin (${req.casa.editOrigin})`);
+        req.casa.editMode = false;
+        req.casa.editOrigin = undefined;
+      }
+    }
+
+    // difficult: first waypoint on a Plan - how do we determine if there are
+    // other plans pointing at this one? and how do we determine if those others
+    // are part of a future plan, or a past one? Think we'll have to leave it up
+    // to the dev to add the back link for the first page in a Plan.
+
+    // Calculate URL for the "back" link
+    const [prevRoute] = plan.traversePrevRoutes(req.casa.journeyContext, {
+      startWaypoint: waypoint,
+      stopCondition: () => (true), // stop at the first one
+    });
+    res.locals.casa.journeyPreviousUrl = prevRoute.target ? waypointUrl({
+      mountUrl,
+      journeyContext: req.casa.journeyContext,
+      waypoint: prevRoute.target,
+      routeName: 'prev',
+      edit: req.casa.editMode,
+      editOrigin: req.casa.editOrigin,
+    }) : undefined;
+
+    return next();
+  },
+];

package/src/middleware/strip-proxy-path.js

@@ -0,0 +1,56 @@
+// Strip any "proxy path" prefix present on the request URL
+//
+// The default "mountUrl" will be match whatever path that the CASA app
+// instance will be mounted onto. So if you mount on `/a/b/c` then all
+// URLs generated for the browser will be prefixed with `/a/b/c`.
+//
+// Defining a `mountUrl` will change that behaviour into a "proxy mode".
+// This mode assumes you have a forwarding proxy that will alter
+// the incoming request paths from `mountUrl` to the original path you
+// have mounted this CASA app instance onto.
+//
+// For example, if you mount the app on `/a/b/c/x`, but want the browser
+// URLs to just use the `/x` prefix, then pass a `mountUrl` of `/x`.
+//
+// See docs in `docs/guides/setup-behind-a-proxy.md`
+
+import logger from '../lib/logger.js';
+
+const log = logger('casa:middleware:strip-proxy-path');
+
+export default ({
+  mountUrl = '/',
+}) => [
+  (req, res, next) => {
+    // TODO:
+    // We _may_ have to start tracking the various prefix in order to differentiate
+    // between a proxy prefix, and a parent app's path.
+
+    // Assume everything before `mountUrl` is the proxy path prefix and remove it
+    req.originalBaseUrl = req.originalBaseUrl ?? req.baseUrl;
+    req.baseUrl = mountUrl.replace(/\/$/, '');
+
+    // If the app has been mounted directly on the specific `mountUrl`, then
+    // there's nothing we need to do and can let this request pass-through.
+    if (req.baseUrl === req.originalBaseUrl) {
+      next();
+    } else if (req.__CASA_BASE_URL_REWRITTEN__) {
+      delete req.__CASA_BASE_URL_REWRITTEN__;
+      next();
+    } else {
+      // Strip the proxy path prefix from the original URL so that
+      // subsequent middleware sees the URL path as though proxy wasn't there.
+      // req.url will already have the proxy prefix and mountUrl removed.
+      /* eslint-disable security/detect-non-literal-regexp */
+      log.trace(`req.originalUrl before proxy stripping: ${req.originalUrl}`);
+      req.originalUrl = req.originalUrl.replace(new RegExp(`^/.+?${mountUrl}`), mountUrl);
+      log.trace(`req.originalUrl after proxy stripping: ${req.originalUrl}`);
+      /* eslint-enable security/detect-non-literal-regexp */
+
+      // Issuing this call will re-run this same middleware, so we use this
+      // `__CASA_BASE_URL_REWRITTEN__` flag to prevent recursion.
+      req.__CASA_BASE_URL_REWRITTEN__ = true;
+      req.app.handle(req, res, next);
+    }
+  },
+];

package/src/middleware/validate-fields.js

@@ -0,0 +1,89 @@
+// Validate the data captured in the journey context
+import JourneyContext from '../lib/JourneyContext.js';
+import { REQUEST_PHASE_VALIDATE } from '../lib/constants.js';
+
+const updateContext = ({
+  waypoint,
+  errors = null,
+  journeyContext,
+  session,
+}) => {
+  // Set validation state
+  if (errors === null) {
+    journeyContext.clearValidationErrorsForPage(waypoint);
+  } else {
+    journeyContext.setValidationErrorsForPage(waypoint, errors);
+  }
+
+  // Save to session
+  JourneyContext.putContext(session, journeyContext, {
+    userInfo: {
+      casaRequestPhase: REQUEST_PHASE_VALIDATE,
+    },
+  });
+}
+
+export default ({
+  waypoint,
+  fields = [],
+  plan,
+}) => [
+  (req, res, next) => {
+    const mountUrl = `${req.baseUrl}/`;
+
+    // Run validators for every field to build up a complete list of errors
+    // currently associated with this waypoint.
+    let errors = [];
+    for (let i = 0, l = fields.length; i < l; i++) {
+      /* eslint-disable security/detect-object-injection */
+      // Dynamic object keys are only used on known entities (fields, waypoint)
+      const field = fields[i];
+      const fieldName = field.name;
+      const fieldValue = req.casa.journeyContext.data?.[waypoint]?.[fieldName];
+
+      // (type = ValidateContext)
+      const context = {
+        fieldName,
+        fieldValue,
+        waypoint,
+        journeyContext: req.casa.journeyContext,
+      };
+      /* eslint-enable security/detect-object-injection */
+
+      errors = [
+        ...errors,
+        ...field.runValidators(fieldValue, context),
+      ];
+    }
+
+    // Validation passed with no errors
+    if (!errors.length) {
+      updateContext({
+        waypoint,
+        session: req.session,
+        mountUrl,
+        plan,
+        journeyContext: req.casa.journeyContext,
+      });
+      return next();
+    }
+
+    // If there are any native errors in the list, we need to bail the request
+    const nativeError = errors.find((e) => e instanceof Error);
+    if (nativeError) {
+      return next(nativeError);
+    }
+
+    // Make the errors available to downstream middleware
+    updateContext({
+      errors,
+      waypoint,
+      session: req.session,
+      mountUrl,
+      plan,
+      journeyContext: req.casa.journeyContext,
+    });
+
+    return next();
+  },
+];

package/src/routes/ancillary.js

@@ -0,0 +1,29 @@
+import MutableRouter from '../lib/MutableRouter.js';
+
+/**
+ * @typedef {object} AncillaryRouterOptions Options to configure static router
+ * @property {number} sessionTtl Session timeout (seconds)
+ */
+
+/**
+ * Create an instance of the ancillary router.
+ *
+ * @access private
+ * @param {AncillaryRouterOptions} options Options
+ * @returns {MutableRouter} ExpressJS Router instance
+ */
+export default function ancillaryRouter({
+  sessionTtl,
+}) {
+  // Router
+  const router = new MutableRouter();
+
+  // Session timeout
+  router.all('/session-timeout', (req, res) => {
+    res.render('casa/session-timeout.njk', {
+      sessionTtl: Math.floor(sessionTtl / 60),
+    });
+  });
+
+  return router;
+}

package/src/routes/dirname.cjs

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