@dwp/govuk-casa 8.7.12 → 8.8.0

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,78 @@
+// 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,
+      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,84 @@
+// Validate the data captured in the journey context
+import JourneyContext from '../lib/JourneyContext.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);
+}
+
+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;

package/src/routes/journey.js

@@ -0,0 +1,212 @@
+/* eslint-disable object-curly-newline,max-len */
+import MutableRouter from '../lib/MutableRouter.js';
+import skipWaypointMiddlewareFactory from '../middleware/skip-waypoint.js';
+import steerJourneyMiddlewareFactory from '../middleware/steer-journey.js';
+import sanitiseFieldsMiddlewareFactory from '../middleware/sanitise-fields.js';
+import gatherFieldsMiddlewareFactory from '../middleware/gather-fields.js';
+import validateFieldsMiddlewareFactory from '../middleware/validate-fields.js';
+import progressJourneyMiddlewareFactory from '../middleware/progress-journey.js';
+import waypointUrl from '../lib/waypoint-url.js';
+import logger from '../lib/logger.js';
+import { resolveMiddlewareHooks } from '../lib/utils.js';
+
+const log = logger('routes:journey');
+
+/**
+ * @access private
+ * @param {import('../casa.js').GlobalHook} GlobalHook
+ */
+
+/**
+ * @access private
+ * @param {import('../casa.js').Page} Page
+ */
+
+/**
+ * @access private
+ * @param {import('../casa.js').Plan} Plan
+ */
+
+/**
+ * @typedef {object} JourneyRouterOptions Options to configure static router
+ * @property {GlobalHook[]} globalHooks Global hooks
+ * @property {Page[]} pages Page definitions
+ * @property {Plan} plan Plan
+ * @property {Function[]} csrfMiddleware Middleware for providing CSRF controls
+ */
+
+const renderMiddlewareFactory = (view, contextFactory) => [
+  (req, res, next) => {
+    res.render(view, {
+      // Common template variables for both GET and POST requests
+      inEditMode: req.casa.editMode,
+      editOriginUrl: req.casa.editOrigin,
+      activeContextId: req.casa.journeyContext.identity.id,
+      ...contextFactory(req),
+    }, (err, templateString) => {
+      if (err) {
+        next(err);
+      } else {
+        res.send(templateString);
+      }
+    });
+  },
+];
+
+/**
+ * Create an instance of the router for all waypoints visited during a Journey
+ * through the Plan.
+ *
+ * @access private
+ * @param {JourneyRouterOptions} opts Options
+ * @returns {MutableRouter} Router
+ */
+export default function journeyRouter({
+  globalHooks,
+  pages,
+  plan,
+  csrfMiddleware,
+}) {
+  // Router
+  const router = new MutableRouter();
+
+  // Special "_" route which handles redirecting the user between sub-apps
+  // /app1/_/?refmount=app2&route=prev
+  router.all('/_', (req, res) => {
+    const mountUrl = `${req.baseUrl}/`;
+    const refmount = req.query?.refmount;
+    const route = req.query?.route;
+    log.trace(`App root ${mountUrl}: refmount = ${refmount}, route = ${route}`);
+
+    let redirectTo;
+    const fallback = waypointUrl({
+      mountUrl,
+      waypoint: plan.traverse(req.casa.journeyContext, {
+        stopCondition: () => (true), // we only need one; stop at the first
+      })[0],
+    });
+
+    if (route === 'prev') {
+      const routes = plan.traversePrevRoutes(req.casa.journeyContext, { startWaypoint: refmount });
+      redirectTo = routes.length ? waypointUrl({ mountUrl, waypoint: routes[0].target }) : fallback;
+    } else {
+      const routes = plan.traverseNextRoutes(req.casa.journeyContext, { startWaypoint: refmount });
+      if (routes[0].target !== null) {
+        redirectTo = routes.length ? waypointUrl({ mountUrl, waypoint: routes[0].target }) : fallback;
+      } else {
+        redirectTo = fallback;
+      }
+    }
+
+    // Carry over any params
+    const url = new URL(redirectTo, 'https://placeholder.test/');
+    const searchParams = new URLSearchParams(req.query);
+    searchParams.delete('refmount');
+    searchParams.delete('route');
+    url.search = searchParams.toString();
+    redirectTo = `${url.pathname.replace(/\/+/g, '/')}${url.search}`;
+
+    log.trace(`Redirect to ${redirectTo}`);
+    return res.redirect(redirectTo);
+  });
+
+  // Create GET / POST routes for each page
+  const commonMiddleware = [
+    ...csrfMiddleware,
+  ];
+
+  pages.forEach((page) => {
+    const { waypoint, view, hooks: pageHooks = [], fields } = page;
+    const waypointPath = `/${waypoint}`;
+
+    let commonWaypointMiddleware = [
+      (req, res, next) => {
+        req.casa.waypoint = waypoint;
+        res.locals.casa.waypoint = waypoint;
+        next();
+      },
+    ];
+
+    if (plan.isSkippable(waypoint)) {
+      log.info(`Configuring "${waypoint}" as a skippable waypoint`);
+      commonWaypointMiddleware = [
+        ...commonWaypointMiddleware,
+        ...skipWaypointMiddlewareFactory({ waypoint }),
+      ];
+    }
+
+    router.get(
+      waypointPath,
+      ...commonMiddleware,
+      ...commonWaypointMiddleware,
+
+      ...resolveMiddlewareHooks('journey.presteer', waypointPath, [...globalHooks, ...pageHooks]),
+      ...steerJourneyMiddlewareFactory({ waypoint, plan }),
+      ...resolveMiddlewareHooks('journey.poststeer', waypointPath, [...globalHooks, ...pageHooks]),
+
+      ...resolveMiddlewareHooks('journey.prerender', waypointPath, [...globalHooks, ...pageHooks]),
+      renderMiddlewareFactory(view, (req) => ({
+        formUrl: waypointUrl({ mountUrl: `${req.baseUrl}/`, waypoint }),
+        formData: req.casa.journeyContext.getDataForPage(waypoint),
+      })),
+    );
+
+    router.post(
+      waypointPath,
+      ...commonMiddleware,
+      ...commonWaypointMiddleware,
+
+      ...resolveMiddlewareHooks('journey.presteer', waypointPath, [...globalHooks, ...pageHooks]),
+      ...steerJourneyMiddlewareFactory({ waypoint, plan }),
+      ...resolveMiddlewareHooks('journey.poststeer', waypointPath, [...globalHooks, ...pageHooks]),
+
+      ...resolveMiddlewareHooks('journey.presanitise', waypointPath, [...globalHooks, ...pageHooks]),
+      ...sanitiseFieldsMiddlewareFactory({ waypoint, fields }),
+      ...resolveMiddlewareHooks('journey.postsanitise', waypointPath, [...globalHooks, ...pageHooks]),
+
+      ...resolveMiddlewareHooks('journey.pregather', waypointPath, [...globalHooks, ...pageHooks]),
+      ...gatherFieldsMiddlewareFactory({ waypoint, fields }),
+      ...resolveMiddlewareHooks('journey.postgather', waypointPath, [...globalHooks, ...pageHooks]),
+
+      ...resolveMiddlewareHooks('journey.prevalidate', waypointPath, [...globalHooks, ...pageHooks]),
+      ...validateFieldsMiddlewareFactory({ waypoint, fields, plan }),
+      ...resolveMiddlewareHooks('journey.postvalidate', waypointPath, [...globalHooks, ...pageHooks]),
+
+      // If there were validation errors, jump out of this route and into the
+      // next, where the errors will be rendered
+      (req, res, next) => (req.casa.journeyContext.hasValidationErrorsForPage(waypoint) ? next('route') : next()),
+
+      ...resolveMiddlewareHooks('journey.preredirect', waypointPath, [...globalHooks, ...pageHooks]),
+      ...progressJourneyMiddlewareFactory({ waypoint, plan }),
+    );
+
+    router.post(
+      waypointPath,
+      ...resolveMiddlewareHooks('journey.prerender', waypointPath, [...globalHooks, ...pageHooks]),
+      renderMiddlewareFactory(view, (req) => {
+        const errors = req.casa.journeyContext.getValidationErrorsForPageByField(waypoint) ?? Object.create(null);
+
+        // This is a convenience for the template. The `govukErrorSummary` macro
+        // requires the errors be in a particular format, so here we provide our
+        // errors in that format.
+        // Where there are multiple errors against a particular field, only the
+        // first one is shown.
+        // Disabling security/detect-object-injection rule because both `errors`
+        // and the `k` property are known entities
+        const govukErrors = Object.keys(errors).map((k) => ({
+          text: req.t(errors[k][0].summary, errors[k][0].variables), /* eslint-disable-line security/detect-object-injection */
+          href: errors[k][0].fieldHref, /* eslint-disable-line security/detect-object-injection */
+        }));
+
+        return {
+          formUrl: waypointUrl({ mountUrl: `${req.baseUrl}/`, waypoint }),
+          formData: req.body,
+          formErrors: Object.keys(errors).length ? errors : null,
+          formErrorsGovukArray: govukErrors.length ? govukErrors : null,
+        };
+      }),
+    );
+  });
+
+  return router;
+}