@dwp/govuk-casa 9.3.5 → 9.4.1

package/src/core-plugins/edit-snapshot/src/configure.js

@@ -0,0 +1,30 @@
+import logger from "../../../lib/logger.js";
+import preSteerHook from "./pre-steer-hook.js";
+import postSteerHook from "./post-steer-hook.js";
+
+/**
+ * @typedef {import("../../../casa.js").ConfigurationOptions} ConfigurationOptions
+ * @access private
+ */
+
+const log = logger("lib:internal-plugin:edit-snapshot");
+
+/**
+ * @param {ConfigurationOptions} config Configuration object
+ * @returns {void}
+ */
+export default function (config) {
+  log.info("Configuring 'edit-snapshot' plugin");
+
+  config.hooks ??= [];
+  config.hooks.push(
+    {
+      hook: "journey.presteer",
+      middleware: preSteerHook,
+    },
+    {
+      hook: "journey.poststeer",
+      middleware: postSteerHook,
+    },
+  );
+}

package/src/core-plugins/edit-snapshot/src/index.js

@@ -0,0 +1,7 @@
+import configure from "./configure.js";
+
+export default () => {
+  return {
+    configure,
+  };
+};

package/src/core-plugins/edit-snapshot/src/post-steer-hook.js

@@ -0,0 +1,22 @@
+import logger from "../../../lib/logger.js";
+import { FLAG_FOR_PURGING, deleteSnapshot } from "./utils.js";
+
+const log = logger("lib:internal-plugin:edit-snapshot:post-steer-hook");
+
+export default (req, res, next) => {
+  // Snapshot purging is carried out here rather than in the presteer hook,
+  // because the `middleware/steer-journey.js` middleware first needs the opportunity
+  // to redirect if the journey cannot be traversed to the edit origin.
+  // eslint-disable-next-line security/detect-object-injection
+  if (req.casa[FLAG_FOR_PURGING] === true) {
+    log.debug(
+      `Snapshot purging flag has been set for context '${req.casa.journeyContext.identity.id}'. Snapshot will be deleted.`,
+    );
+    deleteSnapshot(log, req);
+    // eslint-disable-next-line security/detect-object-injection
+    req.casa[FLAG_FOR_PURGING] = false;
+    return req.session.save(next);
+  }
+
+  next();
+};

package/src/core-plugins/edit-snapshot/src/pre-steer-hook.js

@@ -0,0 +1,43 @@
+import logger from "../../../lib/logger.js";
+import {
+  FLAG_FOR_PURGING,
+  snapshotExists,
+  recoverSnapshot,
+  createSnapshot,
+  reachedEditOrigin,
+} from "./utils.js";
+
+const log = logger("lib:internal-plugin:edit-snapshot:pre-steer-hook");
+
+export default (req, res, next) => {
+  if (req.query.editcancel && snapshotExists(req)) {
+    log.debug(
+      "Edit workflow was actively canceled. Snapshot will be recovered.",
+    );
+    recoverSnapshot(log, req);
+    return req.session.save(next);
+  }
+
+  if (!req.casa.editMode && snapshotExists(req)) {
+    log.debug("Edit workflow passively canceled. Snapshot will be recovered.");
+    recoverSnapshot(log, req);
+    return req.session.save(next);
+  }
+
+  if (req.casa.editMode && reachedEditOrigin(log, req)) {
+    log.trace(
+      `Editing workflow has reached editorigin. Purge MAY be carried out in poststeer hook on context '${req.casa.journeyContext.identity.id}'.`,
+    );
+    // eslint-disable-next-line security/detect-object-injection
+    req.casa[FLAG_FOR_PURGING] = true;
+    return next();
+  }
+
+  if (req.casa.editMode && !snapshotExists(req)) {
+    log.debug("Editing workflow has just started. Will create snapshot.");
+    createSnapshot(log, req);
+    return req.session.save(next);
+  }
+
+  next();
+};

package/src/core-plugins/edit-snapshot/src/utils.js

@@ -0,0 +1,53 @@
+/* eslint-disable security/detect-object-injection */
+import { JourneyContext } from "../../../casa.js";
+
+const SESSION_KEY = "casa_edit_snapshots";
+
+export const FLAG_FOR_PURGING = Symbol("flag_to_purge_edit_snapshot");
+
+export const snapshotExists = (req) => {
+  return (
+    req?.session[SESSION_KEY] &&
+    Object.hasOwn(req.session[SESSION_KEY], req.casa.journeyContext.identity.id)
+  );
+};
+
+export const reachedEditOrigin = (log, req) => {
+  const { pathname: currentPathname } = new URL(
+    req.originalUrl,
+    "https://placeholder.test/",
+  );
+  const { pathname: editOriginPathname } = new URL(
+    req.casa.editOrigin,
+    "https://placeholder.test/",
+  );
+
+  return editOriginPathname === currentPathname;
+};
+
+export const createSnapshot = (log, req) => {
+  log.debug(
+    `Creating a new edit snapshot for context '${req.casa.journeyContext.identity.id}'`,
+  );
+  req.session[SESSION_KEY] ??= Object.create(null);
+  req.session[SESSION_KEY][req.casa.journeyContext.identity.id] =
+    req.casa.journeyContext.toObject();
+};
+
+export const recoverSnapshot = (log, req) => {
+  log.debug(
+    `Recovering snapshot for context '${req.casa.journeyContext.identity.id}'`,
+  );
+  req.casa.journeyContext.configureFromObject(
+    req.session[SESSION_KEY][req.casa.journeyContext.identity.id],
+  );
+  JourneyContext.putContext(req.session, req.casa.journeyContext);
+  deleteSnapshot(log, req);
+};
+
+export const deleteSnapshot = (log, req) => {
+  log.debug(
+    `Purging edit snapshot for context '${req.casa.journeyContext.identity.id}'`,
+  );
+  req.session[SESSION_KEY][req.casa.journeyContext.identity.id] = undefined;
+};

package/src/core-plugins/index.js

@@ -0,0 +1,2 @@
+// Convenience for exporting all plugins as "corePlugins" from main casa module
+export { default as editSnapshot } from "./edit-snapshot/src/index.js";

package/src/lib/CasaTemplateLoader.js

@@ -97,7 +97,6 @@ export default class CasaTemplateLoader extends FileSystemLoader {
       /* eslint-disable-next-line security/detect-object-injection */
       const { block, modifier } = this.#blockModifiers[i];
       if (source.src.indexOf(`block ${block}`) > -1) {
-        /* eslint-disable-next-line no-param-reassign */
         source.src = source.src.replace(
           `block ${block} %}`,
           `block ${block} %}${modifier(name)}`,

package/src/lib/JourneyContext.js

@@ -51,6 +51,10 @@ const clone = rfdc({ proto: false });
  * @access private
  */
 
+/**
+ * @param {any} key Object key to validate
+ * @returns {string} Validated key
+ */
 export function validateObjectKey(key = "") {
   const keyLower = String.prototype.toLowerCase.call(key);
   if (
@@ -163,6 +167,13 @@ export default class JourneyContext {
     return new JourneyContext(data, deserialisedValidation, nav, identity);
   }
 
+  configureFromObject(object) {
+    const source = JourneyContext.fromObject(object);
+    this.#data = source.data;
+    this.#validation = source.validation;
+    this.#nav = source.nav;
+  }
+
   get data() {
     return this.#data;
   }
@@ -262,7 +273,7 @@ export default class JourneyContext {
    * @returns {JourneyContext} Chain.
    */
   removeValidationStateForPage(pageId) {
-    /* eslint-disable-next-line no-unused-vars */
+    /* eslint-disable-next-line sonarjs/no-unused-vars,no-unused-vars */
     const { [pageId]: dummy, ...remaining } = this.#validation;
     this.#validation = { ...remaining };
     return this;
@@ -560,14 +571,14 @@ export default class JourneyContext {
       log.trace(
         "Session context list already initialised as an object (legacy structure). Will convert from object to array.",
       );
-      /* eslint-disable-next-line no-param-reassign */
+
       session.journeyContextList = Object.entries(session.journeyContextList);
     }
 
     // Initialise new context list in the session
     if (!Object.hasOwn(session, "journeyContextList")) {
       log.trace("Initialising session with a default journey context list");
-      /* eslint-disable-next-line no-param-reassign */
+
       session.journeyContextList = [];
 
       const defaultContext = new JourneyContext();
@@ -690,7 +701,7 @@ export default class JourneyContext {
     const list = new Map(session?.journeyContextList);
     if (list.has(id)) {
       // ESLint disabled as `id` has been verified as an "own" property
-      /* eslint-disable-next-line security/detect-object-injection */
+
       return JourneyContext.fromObject(list.get(id));
     }
 
@@ -792,7 +803,7 @@ export default class JourneyContext {
 
     const list = new Map(session.journeyContextList);
     list.set(context.identity.id, context.toObject());
-    /* eslint-disable-next-line no-param-reassign */
+
     session.journeyContextList = [...list.entries()];
   }
 
@@ -919,6 +930,7 @@ export default class JourneyContext {
    * @param {string} opts.to Waypoint to skip to.
    */
   setSkipped(waypoint, opts) {
+    /* eslint-disable security/detect-object-injection */
     // Unset, with setSkipped(a, false)
     if (opts === false) {
       this.data[waypoint] ??= Object.create(null);
@@ -941,25 +953,25 @@ export default class JourneyContext {
         `setSkipped opts must be a boolean or object with a "to" prop of waypoint to skip to, got: ${typeof opts}`,
       );
     }
+    /* eslint-enable security/detect-object-injection */
   }
 
   /**
    * Tests if a page has been skipped.
    *
-   * @param {string} page Page ID (waypoint).
+   * @param {string} waypoint Page ID (waypoint).
    * @param {object} opts Skip ptions.
    * @param {string} opts.to Waypoint that should be skipped to.
    * @returns {boolean} True if the page has been skipped, or if it has been
    *   skipped to a specific page.
    */
   isSkipped(waypoint, opts) {
+    const wpData = this.data[String(waypoint)];
+
     if (opts === undefined) {
-      return (
-        this.data[waypoint]?.__skipped__ === true ||
-        this.data[waypoint]?.__skip__ !== undefined
-      );
+      return wpData?.__skipped__ === true || wpData?.__skip__ !== undefined;
     } else if (typeof opts.to === "string") {
-      return this.data[waypoint]?.__skip__?.to === opts.to;
+      return wpData?.__skip__?.to === opts.to;
     }
   }
 }

package/src/lib/MutableRouter.js

@@ -1,4 +1,3 @@
-/* eslint-disable sonarjs/no-duplicate-string,class-methods-use-this */
 import { Router } from "express";
 
 /** @memberof module:@dwp/govuk-casa */

package/src/lib/ValidationError.js

@@ -41,7 +41,7 @@ export default class ValidationError {
    * @param {object} args Arguments
    * @param {ErrorMessageConfig} args.errorMsg Error message config to seed
    *   ValidationError
-   * @param {ValidateContext} [args.dataContext={}] Data for error msg function.
+   * @param {ValidateContext} [args.dataContext] Data for error msg function.
    *   Default is `{}`
    * @returns {ValidationError} Error instance
    * @throws {TypeError} If errorMsg is not in a valid type

package/src/lib/ValidatorFactory.js

@@ -1,4 +1,3 @@
-/* eslint-disable class-methods-use-this */
 import lodash from "lodash";
 
 const { isPlainObject } = lodash; // CommonJS
@@ -54,7 +53,6 @@ export default class ValidatorFactory {
 
     const validator = Reflect.construct(this, [config]);
 
-    /* eslint-disable-next-line sonarjs/prefer-object-literal */
     const instance = {};
     instance.name = validator.name || "unknown";
     instance.config = config;
@@ -96,7 +94,6 @@ export default class ValidatorFactory {
     throw new Error("validate() method has not been implemented");
   }
 
-  /* eslint-disable-next-line jsdoc/require-returns-check */
   /**
    * Sanitise the given value.
    *

package/src/lib/configuration-ingestor.js

@@ -1,4 +1,3 @@
-/* eslint-disable sonarjs/no-duplicate-string */
 import bytes from "bytes";
 import { PageField } from "./field.js";
 import Plan from "./Plan.js";
@@ -25,6 +24,41 @@ import {
  * @access private
  */
 
+/**
+ * @typedef {import("../casa").Page} Page
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").PageField} PageField
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").PageHook} PageHook
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").GlobalHook} GlobalHook
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").IPlugin} IPlugin
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").ContextEventHandler} ContextEventHandler
+ * @access private
+ */
+
+/**
+ * @typedef {import("../casa").ContextIdGenerator} ContextIdGenerator
+ * @access private
+ */
+
 const log = logger("lib:configuration-ingestor");
 
 const echo = (a) => a;
@@ -58,11 +92,12 @@ export function validateI18nDirs(dirs = []) {
   if (!Array.isArray(dirs)) {
     throw new TypeError("I18n directories must be an array (i18n.dirs)");
   }
-  for (let i = 0; i < dirs.length; i++) {
-    const dir = dirs[i];
+
+  let i = 0;
+  for (const dir of dirs) {
     if (typeof dir !== "string") {
       throw new TypeError(
-        `I18n directory must be a string, got ${typeof dir} (i18n.dirs[${i}])`,
+        `I18n directory must be a string, got ${typeof dir} (i18n.dirs[${i++}])`,
       );
     }
   }
@@ -82,11 +117,12 @@ export function validateI18nLocales(locales = ["en", "cy"]) {
   if (!Array.isArray(locales)) {
     throw new TypeError("I18n locales must be an array (i18n.locales)");
   }
-  for (let i = 0; i < locales.length; i++) {
-    const locale = locales[i];
+
+  let i = 0;
+  for (const locale of locales) {
     if (typeof locale !== "string") {
       throw new TypeError(
-        `I18n locale must be a string, got ${typeof locale} (i18n.locales[${i}])`,
+        `I18n locale must be a string, got ${typeof locale} (i18n.locales[${i++}])`,
       );
     }
   }
@@ -148,11 +184,12 @@ export function validateViews(dirs = []) {
   if (!Array.isArray(dirs)) {
     throw new TypeError("View directories must be an array (views)");
   }
-  for (let i = 0; i < dirs.length; i++) {
-    const dir = dirs[i];
+
+  let i = 0;
+  for (const dir of dirs) {
     if (typeof dir !== "string") {
       throw new TypeError(
-        `View directory must be a string, got ${typeof dir} (views[${i}])`,
+        `View directory must be a string, got ${typeof dir} (views[${i++}])`,
       );
     }
   }
@@ -196,7 +233,7 @@ export function validateSessionTtl(ttl = 3600) {
 /**
  * Validates and sanitises sessions name.
  *
- * @param {string} [name=casa-session] Session name. Default is `casa-session`
+ * @param {string} [name] Session name. Default is `casa-session`
  * @returns {string} Name.
  * @throws {ReferenceError} For missing value type.
  * @throws {TypeError} For invalid value.
@@ -300,6 +337,11 @@ export function validateErrorVisibility(
   );
 }
 
+/**
+ * @param {boolean | string} cookieSameSite Cookie SameSite value
+ * @param {boolean | string} defaultFlag Default value
+ * @returns {boolean | string} Validated value
+ */
 export function validateSessionCookieSameSite(cookieSameSite, defaultFlag) {
   const validValues = [true, false, "Strict", "Lax", "None"];
 
@@ -335,12 +377,18 @@ const validatePageHook = (hook, index) => {
   }
 };
 
+/**
+ * @param {PageHook[]} hooks Page hook functions
+ * @returns {PageHook[]} Validated page hooks
+ */
 export function validatePageHooks(hooks) {
   if (!Array.isArray(hooks)) {
     throw new TypeError("Hooks must be an array");
   }
-  for (let i = 0; i < hooks.length; i++) {
-    validatePageHook(hooks[i], i);
+
+  let i = 0;
+  for (const hook of hooks) {
+    validatePageHook(hook, i++);
   }
   return hooks;
 }
@@ -358,12 +406,18 @@ const validateField = (field, index) => {
   }
 };
 
+/**
+ * @param {PageField[]} fields Page fields
+ * @returns {PageField[]} Validated fields
+ */
 export function validateFields(fields) {
   if (!Array.isArray(fields)) {
     throw new TypeError("Page fields must be an array (page[].fields)");
   }
-  for (let i = 0; i < fields.length; i++) {
-    validateField(fields[i], i);
+
+  let i = 0;
+  for (const field of fields) {
+    validateField(field, i++);
   }
   return fields;
 }
@@ -387,16 +441,26 @@ const validatePage = (page, index) => {
   }
 };
 
+/**
+ * @param {Page[]} [pages] Pages
+ * @returns {Page[]} Validated pages
+ */
 export function validatePages(pages = []) {
   if (!Array.isArray(pages)) {
     throw new TypeError("Pages must be an array (pages)");
   }
-  for (let i = 0; i < pages.length; i++) {
-    validatePage(pages[i], i);
+
+  let i = 0;
+  for (const page of pages) {
+    validatePage(page, i++);
   }
   return pages;
 }
 
+/**
+ * @param {Plan} plan Plan
+ * @returns {Plan} Validated plan
+ */
 export function validatePlan(plan) {
   if (plan === undefined) {
     return plan;
@@ -424,6 +488,10 @@ const validateGlobalHook = (hook, index) => {
   }
 };
 
+/**
+ * @param {GlobalHook[]} hooks Global hook functions
+ * @returns {GlobalHook[]} Validated global hooks
+ */
 export function validateGlobalHooks(hooks) {
   if (hooks === undefined) {
     return [];
@@ -431,16 +499,26 @@ export function validateGlobalHooks(hooks) {
   if (!Array.isArray(hooks)) {
     throw new TypeError("Hooks must be an array");
   }
-  for (let i = 0; i < hooks.length; i++) {
-    validateGlobalHook(hooks[i], i);
+
+  let i = 0;
+  for (const hook of hooks) {
+    validateGlobalHook(hook, i++);
   }
   return hooks;
 }
 
+/**
+ * @param {IPlugin[]} plugins Plugins
+ * @returns {IPlugin[]} Validated plugins
+ */
 export function validatePlugins(plugins) {
   return plugins;
 }
 
+/**
+ * @param {ContextEventHandler[]} events Event handlers
+ * @returns {ContextEventHandler[]} Validated event handlers
+ */
 export function validateEvents(events) {
   return events;
 }
@@ -464,6 +542,13 @@ export function validateHelmetConfigurator(helmetConfigurator) {
   return helmetConfigurator;
 }
 
+/**
+ * @param {number} value Max params value
+ * @param {number} [defaultValue] Default value
+ * @returns {number} Valid value
+ * @throws {TypeError} If not an integer
+ * @throws {RangeError} If out of bounds
+ */
 export function validateFormMaxParams(value, defaultValue = 25) {
   // CASA needs to send certain hidden form fields (see `sanitise-fields`
   // middleware), plus some padding here.
@@ -482,6 +567,13 @@ export function validateFormMaxParams(value, defaultValue = 25) {
   return value;
 }
 
+/**
+ * @param {number} value Max bytes value
+ * @param {number} [defaultValue] Default value
+ * @returns {number} Valid value
+ * @throws {TypeError} If not an integer
+ * @throws {RangeError} If out of bounds
+ */
 export function validateFormMaxBytes(value, defaultValue = 1024 * 50) {
   const MIN_BYTES = 1024;
 
@@ -502,6 +594,11 @@ export function validateFormMaxBytes(value, defaultValue = 1024 * 50) {
   return parsedValue;
 }
 
+/**
+ * @param {ContextIdGenerator} generator ID generator function
+ * @returns {ContextIdGenerator} Validated generator
+ * @throws {TypeError} If not a function
+ */
 export function validateContextIdGenerator(generator) {
   if (generator === undefined) {
     return contextIdGenerators.uuid();

package/src/lib/configure.js

@@ -87,7 +87,7 @@ export default function configure(config = {}) {
   for (const page of pages) {
     if (page?.hooks) {
       for (const h of page.hooks) {
-        h.hook = `journey.${h.hook}`
+        h.hook = `journey.${h.hook}`;
       }
     }
   }
@@ -211,7 +211,7 @@ export default function configure(config = {}) {
 
   // Bootstrap all plugins
   for (const plugin of plugins.filter((p) => p.bootstrap)) {
-    plugin?.bootstrap(configOutput)
+    plugin?.bootstrap(configOutput);
   }
 
   // Finished configuration

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

@@ -1,4 +1,3 @@
-/* eslint-disable import/no-cycle */
 import { randomUUID } from "node:crypto";
 
 /** @typedef {import("../casa.js").ContextIdGenerator} ContextIdGenerator */
@@ -50,6 +49,7 @@ const shortGuid =
     do {
       id = Array(length)
         .fill(0)
+        /* eslint-disable-next-line sonarjs/pseudo-random */
         .map(() => pool.charAt(Math.floor(Math.random() * poolSize)))
         .join("");
       attempts--;

package/src/lib/field.js

@@ -66,9 +66,9 @@ export class PageField {
    *
    * @param {string} name Field name
    * @param {object} [opts] Options
-   * @param {boolean} [opts.optional=false] Whether this field is optional.
-   *   Default is `false`
-   * @param {boolean} [opts.persist=true] Whether this field will persist in
+   * @param {boolean} [opts.optional] Whether this field is optional. Default is
+   *   `false`
+   * @param {boolean} [opts.persist] Whether this field will persist in
    *   `req.body`. Default is `true`
    */
   constructor(
@@ -95,7 +95,7 @@ export class PageField {
     };
 
     // Apply name
-    /* eslint-disable-next-line security/detect-non-literal-fs-filename */
+
     this.rename(name);
   }
 
@@ -153,13 +153,11 @@ export class PageField {
    */
   putValue(obj = Object.create(null), value = undefined) {
     if (this.#meta.complex) {
-      /* eslint-disable-next-line no-param-reassign */
       obj[this.#meta.complexFieldName] = {
         ...(obj[this.#meta.complexFieldName] ?? {}),
         [this.#meta.complexFieldProperty]: value,
       };
     } else {
-      /* eslint-disable-next-line no-param-reassign */
       obj[this.#name] = value;
     }
 
@@ -315,7 +313,6 @@ export class PageField {
     for (let i = 0, l = this.#validators.length; i < l; i++) {
       // ESLint disabled as `i` is an integer
       /* eslint-disable security/detect-object-injection */
-      // TODO: Replace `value` with `context.fieldValue` here
       let fieldErrors = this.#validators[i].validate(
         context.fieldValue,
         context,
@@ -441,9 +438,9 @@ export class PageField {
  * @memberof module:@dwp/govuk-casa
  * @param {string} name Field name
  * @param {object} [opts] Options
- * @param {boolean} [opts.optional=false] Whether this field is optional.
- *   Default is `false`
- * @param {boolean} [opts.persist=true] Whether this field will persist in
+ * @param {boolean} [opts.optional] Whether this field is optional. Default is
+ *   `false`
+ * @param {boolean} [opts.persist] Whether this field will persist in
  *   `req.body`. Default is `true`
  * @returns {PageField} A PageField
  */