@dwp/govuk-casa 8.11.1 → 8.13.0

package/src/lib/JourneyContext.js

@@ -1,3 +1,4 @@
+/* eslint-disable import/no-cycle */
 /**
  * Represents the state of a user's journey through the Plan. It contains
  * information about:
@@ -6,11 +7,11 @@
  * - Validation errors on that data
  * - Navigation information about how the user got where they are.
  */
-import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
 import lodash from 'lodash';
 import ValidationError from './ValidationError.js';
 import logger from './logger.js';
 import { notProto } from './utils.js';
+import { uuid as uuidGenerator } from './context-id-generators.js';
 
 const {
   cloneDeep, isPlainObject, isObject, has, isEqual,
@@ -18,6 +19,8 @@ const {
 
 const log = logger('lib:journey-context');
 
+const uuid = uuidGenerator();
+
 /**
  * @access private
  * @typedef {import('../casa').ContextEventUserInfo} ContextEventUserInfo
@@ -75,6 +78,16 @@ export default class JourneyContext {
 
   static DEFAULT_CONTEXT_ID = 'default';
 
+  /**
+   * @type {symbol}
+   */
+  static ID_GENERATOR_REQ_LOG = Symbol('generatedContextIds');
+
+  /**
+   * @type {symbol}
+   */
+  static ID_GENERATOR_REQ_KEY = Symbol('generateContextId');
+
   /**
    * Constructor.
    *
@@ -476,12 +489,15 @@ export default class JourneyContext {
   /**
    * Construct a new ephemeral JourneyContext instance with a unique ID.
    *
+   * Note: In later versions of CASA, the `req` property will be mandatory.
+   *
+   * @param {ExpressRequest} [req] Request session
    * @returns {JourneyContext} Constructed JourneyContext instance
    */
-  static createEphemeralContext() {
+  static createEphemeralContext(req) {
     return JourneyContext.fromObject({
       identity: {
-        id: uuidv4(),
+        id: JourneyContext.generateContextId(req),
       },
     });
   }
@@ -489,17 +505,20 @@ export default class JourneyContext {
   /**
    * Construct a new JourneyContext instance from another instance.
    *
+   * Note: In later versions of CASA, the `req` property will be mandatory.
+   *
    * @param {JourneyContext} context Context to copy from
+   * @param {ExpressRequest} [req] Request
    * @returns {JourneyContext} Constructed JourneyContext instance
    * @throws {TypeError} When context is not a valid type
    */
-  static fromContext(context) {
+  static fromContext(context, req) {
     if (!(context instanceof JourneyContext)) {
       throw new TypeError('Source context must be a JourneyContext');
     }
 
     const newContextObj = context.toObject();
-    newContextObj.identity.id = uuidv4();
+    newContextObj.identity.id = JourneyContext.generateContextId(req);
 
     return JourneyContext.fromObject(newContextObj);
   }
@@ -542,14 +561,14 @@ export default class JourneyContext {
   }
 
   /**
-   * Validate the format of a context ID, i.e. "default" or a uuid
-   * eg 00000000-0000-0000-0000-000000000000
-   * eg 123e4567-e89b-12d3-a456-426614174000
+   * Validate the format of a context ID:
+   * - Between 1 and 64 characters
+   * - Contain only the characters a-z, 0-9, -
    *
    * @param {string} id Context ID
    * @returns {string} Original ID if it's valid
    * @throws {TypeError} When id is not a valid type
-   * @throws {SyntaxError} When id is not a valid uuid format
+   * @throws {SyntaxError} When id is not a valid format
    */
   static validateContextId(id) {
     if (id === JourneyContext.DEFAULT_CONTEXT_ID) {
@@ -558,9 +577,58 @@ export default class JourneyContext {
 
     if (typeof id !== 'string') {
       throw new TypeError('Context ID must be a string');
-    } else if (!uuidValidate(id)) {
-      throw new SyntaxError('Context ID is not in the correct uuid format');
+    } else if (!id.match(/^[a-z0-9-]{1,64}$/)) {
+      throw new SyntaxError('Context ID is not in the correct format');
+    }
+
+    return id;
+  }
+
+  /**
+   * Generate a new context ID, validate it, and throw if the ID has already been
+   * generated during this request lifecycle. This may happen if an ID was
+   * generated, but never used to store a new context in the session. Therefore
+   * it is important for user code to always call `putContext()` before
+   * generating another ID.
+   *
+   * @param {ExpressRequest} [req] Request
+   * @returns {string} New ID
+   * @throws {Error} When generated ID has already been used
+   */
+  static generateContextId(req) {
+    // Can't generate custom ID when no request object is provided, because the
+    // custom generator function itself exists on that object.
+    if (!req) {
+      log.warn('Generating a context ID without a given request object. Reverting to uuid().');
+      return uuid();
+    }
+
+    // Collate a list of context IDs already in use, either from existing
+    // contexts in the session, or generated during this request lifecycle.
+    // We don't identify the source of each ID because the generator must not
+    // differentiate its behaviour on whether the ID exists in session or not.
+    const inSessionIds = JourneyContext.getContexts(req.session)
+      .map((c) => c.identity.id)
+      .filter((id) => id !== JourneyContext.DEFAULT_CONTEXT_ID);
+    const inRequestIds = req[JourneyContext.ID_GENERATOR_REQ_LOG] ?? [];
+    const reservedIds = Array.from(new Set([...inSessionIds, ...inRequestIds]).values());
+
+    // Generate and log the ID
+    const id = JourneyContext.validateContextId(
+      req[JourneyContext.ID_GENERATOR_REQ_KEY].call(null, { req, reservedIds }),
+    );
+    if (reservedIds.includes(id)) {
+      throw new Error(`Regenerated a context ID, ${String(id)}. It has likely not yet been used to store a new context in session using JourneyContext.putContext().`);
+    }
+
+    if (!req[JourneyContext.ID_GENERATOR_REQ_LOG]) {
+      Object.defineProperty(req, JourneyContext.ID_GENERATOR_REQ_LOG, {
+        value: [],
+        enumerable: false,
+        writable: false,
+      });
     }
+    req[JourneyContext.ID_GENERATOR_REQ_LOG].push(id);
 
     return id;
   }

package/src/lib/configuration-ingestor.js

@@ -9,6 +9,8 @@ import {
   validateHookPath,
   validateView,
 } from './utils.js';
+import * as contextIdGenerators from './context-id-generators.js';
+import { CONFIG_ERROR_VISIBILITY_ALWAYS, CONFIG_ERROR_VISIBILITY_ONSUBMIT } from './constants.js';
 
 /**
  * @access private
@@ -255,6 +257,25 @@ export function validateSessionCookiePath(cookiePath, defaultPath = '/') {
  * @returns {boolean} cookie path
  * @throws {TypeError} When invalid arguments are provided
  */
+
+/**
+ * Validates errorVisibility.
+ *
+ * @access private
+ * @param {string} errorVisibility sets visibility flag for page validation error
+ * @throws {SyntaxError} For invalid errorVisibility flag.
+ * @returns {symbol | Function} flag for error visibility.
+ */
+export function validateErrorVisibility(errorVisibility = CONFIG_ERROR_VISIBILITY_ONSUBMIT) {
+  if (errorVisibility === undefined) {
+    return undefined;
+  }
+  if (errorVisibility === CONFIG_ERROR_VISIBILITY_ALWAYS || errorVisibility === CONFIG_ERROR_VISIBILITY_ONSUBMIT || typeof errorVisibility === 'function') {
+    return errorVisibility;
+  }
+  throw new TypeError('errorVisibility must be casa constant CONFIG_ERROR_VISIBILITY_ALWAYS | CONFIG_ERROR_VISIBILITY_ONSUBMIT or function');
+}
+
 export function validateSessionCookieSameSite(cookieSameSite, defaultFlag) {
   const validValues = [true, false, 'Strict', 'Lax', 'None'];
 
@@ -321,6 +342,9 @@ const validatePage = (page, index) => {
     if (page.hooks !== undefined) {
       validatePageHooks(page.hooks);
     }
+    if (page.errorVisibility !== undefined) {
+      validateErrorVisibility(page.errorVisibility)
+    }
   } catch (err) {
     err.message = `Page at index ${index} is invalid: ${err.message}`;
     throw err;
@@ -435,6 +459,18 @@ export function validateFormMaxBytes(value, defaultValue = 1024 * 50) {
   return parsedValue;
 }
 
+export function validateContextIdGenerator(generator) {
+  if (generator === undefined) {
+    return contextIdGenerators.uuid();
+  }
+
+  if (!(generator instanceof Function)) {
+    throw new TypeError('contextIdGenerator must be a function');
+  }
+
+  return generator;
+}
+
 /**
  * Ingest, validate, sanitise and manipulate configuration parameters.
  *
@@ -454,6 +490,9 @@ export default function ingest(config = {}) {
     // URL that will prefix all URLs in the browser address bar
     mountUrl: validateMountUrl(config.mountUrl),
 
+    // flag to make validation error visible on get requests
+    errorVisibility: validateErrorVisibility(config.errorVisibility),
+
     // Session
     session: validateSessionObject(config.session, (session) => ({
       name: validateSessionName(session.name),
@@ -489,6 +528,9 @@ export default function ingest(config = {}) {
     // Form parsing
     formMaxParams: validateFormMaxParams(config.formMaxParams, 25),
     formMaxBytes: validateFormMaxBytes(config.formMaxBytes, 1024 * 50),
+
+    // Context ID generator
+    contextIdGenerator: validateContextIdGenerator(config.contextIdGenerator),
   };
 
   // Freeze to modifications

package/src/lib/configure.js

@@ -22,6 +22,8 @@ import dataMiddlewareFactory from '../middleware/data.js';
 import bodyParserMiddlewareFactory from '../middleware/body-parser.js';
 import csrfMiddlewareFactory from '../middleware/csrf.js';
 
+import { CONFIG_ERROR_VISIBILITY_ONSUBMIT } from './constants.js';
+
 /**
  * @access private
  * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
@@ -55,6 +57,7 @@ export default function configure(config = {}) {
   const ingestedConfig = configurationIngestor(config);
   const {
     mountUrl,
+    errorVisibility = CONFIG_ERROR_VISIBILITY_ONSUBMIT,
     views = [],
     session = {
       secret: 'secret',
@@ -77,6 +80,7 @@ export default function configure(config = {}) {
     helmetConfigurator = undefined,
     formMaxParams,
     formMaxBytes,
+    contextIdGenerator,
   } = ingestedConfig;
 
   // Prepare all page hooks so they are prefixed with the `journey.` scope.
@@ -124,6 +128,7 @@ export default function configure(config = {}) {
   const dataMiddleware = dataMiddlewareFactory({
     plan,
     events,
+    contextIdGenerator,
   });
 
   // Prepare form middleware and its constituent parts
@@ -143,11 +148,13 @@ export default function configure(config = {}) {
   });
 
   // Setup waypoint router, which includes routes for every defined waypoint
+  const globalErrorVisibility = errorVisibility
   const journeyRouter = journeyRoutes({
     globalHooks: hooks,
     pages,
     plan,
     csrfMiddleware,
+    globalErrorVisibility,
   });
 
   // Create the mounting function

package/src/lib/constants.js

@@ -7,3 +7,5 @@ export const REQUEST_PHASE_GATHER = Symbol('gather');
 export const REQUEST_PHASE_VALIDATE = Symbol('validate');
 export const REQUEST_PHASE_REDIRECT = Symbol('redirect');
 export const REQUEST_PHASE_RENDER = Symbol('render');
+export const CONFIG_ERROR_VISIBILITY_ONSUBMIT = Symbol('onsubmit');
+export const CONFIG_ERROR_VISIBILITY_ALWAYS = Symbol('always');

package/src/lib/context-id-generators.js

@@ -0,0 +1,71 @@
+/* eslint-disable import/no-cycle */
+import { randomUUID } from 'node:crypto';
+
+/**
+ * @typedef {import('../casa.js').ContextIdGenerator} ContextIdGenerator
+ */
+
+/**
+ * Creates an instance of a UUID generator.
+ *
+ * @returns {ContextIdGenerator} Generator function
+ */
+const uuid = () => () => randomUUID();
+
+/**
+ * Returns a generator that returns the next incremental integer in a sequence.
+ *
+ * This generator does not take into account the removal of any contexts from
+ * session that were previously assigned a sequential ID. This means that IDs
+ * will be re-used when they are freed up.
+ *
+ * @returns {ContextIdGenerator} Generator function
+ */
+const sequentialInteger = () => ({ reservedIds }) => {
+  const contextIds = Array.from(reservedIds).sort();
+
+  if (!contextIds.length) {
+    return '1';
+  }
+
+  // Find the first numeric ID that we can increment
+  let lastInSequence;
+  do {
+    lastInSequence = Number.parseInt(contextIds.pop(), 10);
+  } while (contextIds.length && Number.isNaN(lastInSequence));
+
+  return String(!Number.isNaN(lastInSequence) ? lastInSequence + 1 : 1);
+};
+
+const shortGuid = ({
+  length = 5,
+  prefix = '',
+  pool = 'abcdefhkmnprtwxy346789',
+} = {}) => ({ reservedIds }) => {
+  // Ambiguous characters excluded
+  const poolSize = pool.length;
+
+  const maxAttempts = 10;
+  let attempts = maxAttempts;
+  let id;
+
+  do {
+    id = Array(length).fill(0).map(() => pool.charAt(Math.floor(Math.random() * poolSize))).join('');
+    attempts--;
+  } while (attempts > 0 && reservedIds.includes(id));
+
+  if (attempts === 0) {
+    throw new Error(`Failed to generate GUID after ${maxAttempts} iterations`);
+  }
+
+  return `${prefix}${id}`;
+}
+
+/**
+ * @namespace ContextIdGenerators
+ */
+export {
+  uuid,
+  sequentialInteger,
+  shortGuid,
+};

package/src/middleware/data.js

@@ -21,6 +21,7 @@ const editOrigin = (req) => {
 export default function dataMiddleware({
   plan,
   events,
+  contextIdGenerator,
 }) {
   return [
     (req, res, next) => {
@@ -45,6 +46,13 @@ export default function dataMiddleware({
       // Grab chosen language from session
       req.casa.journeyContext.nav.language = req.session.language;
 
+      // Context ID generator
+      Object.defineProperty(req, JourneyContext.ID_GENERATOR_REQ_KEY, {
+        value: contextIdGenerator,
+        enumerable: false,
+        writable: false,
+      });
+
       /* ------------------------------------------------- Template variables */
 
       // Capture mount URL that will be used in generating all browser URLs

package/src/middleware/gather-fields.js

@@ -29,7 +29,10 @@ export default ({
   (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);
+    req.casa.archivedJourneyContext = JourneyContext.fromContext(
+      req.casa.journeyContext,
+      req,
+    );
 
     // Ignore data for any non-persistent fields
     // ESLint disabled as `fields`, `i` and `name` are dev-controlled

package/src/middleware/sanitise-fields.js

@@ -31,7 +31,7 @@ export default ({
       }
       /* eslint-enable security/detect-object-injection */
 
-      const journeyContext = JourneyContext.fromContext(req.casa.journeyContext);
+      const journeyContext = JourneyContext.fromContext(req.casa.journeyContext, req);
       journeyContext.setDataForPage(waypoint, prunedBody);
 
       // Second, prune any fields that do not pass the validation conditional,

package/src/routes/journey.js

@@ -9,6 +9,7 @@ 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';
+import { CONFIG_ERROR_VISIBILITY_ALWAYS } from '../lib/constants.js';
 
 const log = logger('routes:journey');
 
@@ -53,6 +54,26 @@ const renderMiddlewareFactory = (view, contextFactory) => [
   },
 ];
 
+/**
+ * generate page validation error
+ *
+ * @param {object} errors object of page validation error
+ * @param {object} req casa request object
+ * @returns {object[]} array of error objects
+ */
+const generateGovukErrors = (errors, req) => Object.values(errors || {}).map(([error]) => ({
+  text: req.t(error.summary, error.variables),
+  href: error.fieldHref,
+}))
+/**
+ * handle errorVisibility flag and function and return boolean
+ *
+ * @param {symbol | Function} errorVisibility errorVisibility config option
+ * @param {object} req casa request object
+ * @returns {boolean} true if errorVisibility is "always" or function condition true
+ */
+const resolveErrorVisibility = (req, errorVisibility) => (typeof errorVisibility === 'function' ? errorVisibility({ req }) : errorVisibility === CONFIG_ERROR_VISIBILITY_ALWAYS)
+
 /**
  * Create an instance of the router for all waypoints visited during a Journey
  * through the Plan.
@@ -66,6 +87,7 @@ export default function journeyRouter({
   pages,
   plan,
   csrfMiddleware,
+  globalErrorVisibility,
 }) {
   // Router
   const router = new MutableRouter();
@@ -116,7 +138,7 @@ export default function journeyRouter({
   ];
 
   pages.forEach((page) => {
-    const { waypoint, view, hooks: pageHooks = [], fields } = page;
+    const { waypoint, view, hooks: pageHooks = [], fields, errorVisibility } = page;
     const waypointPath = `/${waypoint}`;
 
     let commonWaypointMiddleware = [
@@ -145,10 +167,18 @@ export default function journeyRouter({
       ...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),
-      })),
+      renderMiddlewareFactory(view, (req) => {
+        const displayErrors = resolveErrorVisibility(req, globalErrorVisibility) || resolveErrorVisibility(req, errorVisibility);
+        const errors = displayErrors && (req.casa.journeyContext.getValidationErrorsForPageByField(waypoint) ?? Object.create(null));
+        const govukErrors = displayErrors && generateGovukErrors(errors, req);
+
+        return ({
+          formUrl: waypointUrl({ mountUrl: `${req.baseUrl}/`, waypoint }),
+          formData: req.casa.journeyContext.getDataForPage(waypoint),
+          formErrors: (Object.keys(errors).length && displayErrors) ? errors : null,
+          formErrorsGovukArray: (govukErrors.length && displayErrors) ? govukErrors : null,
+        })
+      }),
     );
 
     router.post(
@@ -193,10 +223,7 @@ export default function journeyRouter({
         // 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 */
-        }));
+        const govukErrors = generateGovukErrors(errors, req)
 
         return {
           formUrl: waypointUrl({ mountUrl: `${req.baseUrl}/`, waypoint }),