@dwp/govuk-casa 8.7.12 → 8.8.0

package/src/lib/configuration-ingestor.js

@@ -0,0 +1,457 @@
+/* eslint-disable sonarjs/no-duplicate-string */
+import { PageField } from './field.js';
+import Plan from './Plan.js';
+import logger from './logger.js';
+import {
+  validateWaypoint,
+  validateHookName,
+  validateHookPath,
+  validateView,
+} from './utils.js';
+
+/**
+ * @access private
+ * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').HelmetConfigurator} HelmetConfigurator
+ */
+
+const log = logger('lib:configuration-ingestor');
+
+const echo = (a) => (a);
+
+/**
+ * Validates and sanitises i18n object.
+ *
+ * @access private
+ * @param {object} i18n Object to validate.
+ * @param {Function} cb Callback function that receives the validated value.
+ * @throws {TypeError} For invalid object.
+ * @returns {object} Sanitised i18n object.
+ */
+export function validateI18nObject(i18n = Object.create(null), cb = echo) {
+  if (Object.prototype.toString.call(i18n) !== '[object Object]') {
+    throw new TypeError('I18n must be an object');
+  }
+  return cb(i18n);
+}
+
+/**
+ * Validates and sanitises i18n directory.
+ *
+ * @access private
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+export function validateI18nDirs(dirs = []) {
+  if (!Array.isArray(dirs)) {
+    throw new TypeError('I18n directories must be an array (i18n.dirs)');
+  }
+  dirs.forEach((dir, i) => {
+    if (typeof dir !== 'string') {
+      throw new TypeError(`I18n directory must be a string, got ${typeof dir} (i18n.dirs[${i}])`);
+    }
+  });
+  return dirs;
+}
+
+/**
+ * Validates and sanitises i18n locales.
+ *
+ * @access private
+ * @param {Array} locales Array of locales.
+ * @throws {SyntaxError} For invalid locales.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of locales.
+ */
+export function validateI18nLocales(locales = ['en', 'cy']) {
+  if (!Array.isArray(locales)) {
+    throw new TypeError('I18n locales must be an array (i18n.locales)');
+  }
+  locales.forEach((locale, i) => {
+    if (typeof locale !== 'string') {
+      throw new TypeError(`I18n locale must be a string, got ${typeof locale} (i18n.locales[${i}])`);
+    }
+  });
+  return locales;
+}
+
+/**
+ * Validates and sanitises mount url.
+ *
+ * @access private
+ * @param {string} mountUrl Prefix for all URLs in the browser address bar
+ * @throws {SyntaxError} For invalid URL.
+ * @returns {string|undefined} Sanitised URL.
+ */
+export function validateMountUrl(mountUrl) {
+  if (typeof mountUrl === 'undefined') {
+    return undefined;
+  }
+  if (!mountUrl.match(/\/$/)) {
+    throw new SyntaxError('mountUrl must include a trailing slash (/)');
+  }
+  return mountUrl;
+}
+
+/**
+ * Validates and sanitises sessions object.
+ *
+ * @access private
+ * @param {object} session Object to validate.
+ * @param {Function} cb Callback function that receives the validated value.
+ * @throws {TypeError} For invalid object.
+ * @returns {object} Sanitised sessions object.
+ */
+export function validateSessionObject(session = Object.create(null), cb = echo) {
+  if (session === undefined) {
+    return cb(session);
+  }
+
+  if (typeof session !== 'object') {
+    throw new TypeError('Session config has not been specified');
+  }
+
+  return cb(session);
+}
+
+/**
+ * Validates and sanitises view directory.
+ *
+ * @access private
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+export function validateViews(dirs = []) {
+  if (!Array.isArray(dirs)) {
+    throw new TypeError('View directories must be an array (views)');
+  }
+  dirs.forEach((dir, i) => {
+    if (typeof dir !== 'string') {
+      throw new TypeError(`View directory must be a string, got ${typeof dir} (views[${i}])`);
+    }
+  });
+  return dirs;
+}
+
+/**
+ * Validates and sanitises sessions secret.
+ *
+ * @access private
+ * @param {string} secret Session secret.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Secret.
+ */
+export function validateSessionSecret(secret) {
+  if (typeof secret === 'undefined') {
+    throw ReferenceError('Session secret is missing (session.secret)')
+  } else if (typeof secret !== 'string') {
+    throw new TypeError('Session secret must be a string (session.secret)');
+  }
+  return secret;
+}
+
+/**
+ * Validates and sanitises sessions ttl.
+ *
+ * @access private
+ * @param {number} ttl Session ttl (seconds).
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {number} Ttl.
+ */
+export function validateSessionTtl(ttl = 3600) {
+  if (typeof ttl !== 'number') {
+    throw new TypeError('Session ttl must be an integer (session.ttl)');
+  }
+  return ttl;
+}
+
+/**
+ * Validates and sanitises sessions name.
+ *
+ * @access private
+ * @param {string} [name=casa-session] Session name.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Name.
+ */
+export function validateSessionName(name = 'casa-session') {
+  if (typeof name !== 'string') {
+    throw new TypeError('Session name must be a string (session.name)');
+  }
+  return name;
+}
+
+/**
+ * Validates and sanitises sessions secure flag.
+ *
+ * @access private
+ * @param {boolean} [secure] Session secure flag.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid or missing value.
+ * @returns {string} Name.
+ */
+export function validateSessionSecure(secure) {
+  if (secure === undefined) {
+    throw new Error('Session secure flag must be explicitly defined (session.secure)');
+  }
+  if (typeof secure !== 'boolean') {
+    throw new TypeError('Session secure flag must be boolean (session.secure)');
+  }
+  return secure;
+}
+
+/**
+ * Validates and sanitises sessions store.
+ *
+ * @access private
+ * @param {Function} store Session store.
+ * @returns {Function} Store.
+ */
+export function validateSessionStore(store) {
+  if (typeof store === 'undefined') {
+    log.warn('Using MemoryStore session storage, which is not suitable for production');
+    return null;
+  }
+  return store;
+}
+
+/**
+ * Validates and sanitises sessions cookie url path.
+ *
+ * @access private
+ * @param {string} cookiePath Session cookie url path.
+ * @param {string} defaultPath Default path if none specified.
+ * @returns {string} Cookie path.
+ */
+export function validateSessionCookiePath(cookiePath, defaultPath = '/') {
+  if (typeof cookiePath === 'undefined') {
+    return defaultPath;
+  }
+  return cookiePath;
+}
+
+/**
+ * Validates and sanitises sessions cookie "sameSite" flag. One of:
+ * true (Strict)
+ * false (will not set the flag at all)
+ * Strict
+ * Lax
+ * None
+ *
+ * @access private
+ * @param {any} cookieSameSite Session cookie "sameSite" flag
+ * @param {any} defaultFlag Default path if none specified
+ * @returns {boolean} cookie path
+ * @throws {TypeError} When invalid arguments are provided
+ */
+export function validateSessionCookieSameSite(cookieSameSite, defaultFlag) {
+  const validValues = [true, false, 'Strict', 'Lax', 'None'];
+
+  if (defaultFlag === undefined) {
+    throw new TypeError('validateSessionCookieSameSite() requires an explicit default flag');
+  } else if (!validValues.includes(defaultFlag)) {
+    throw new TypeError('validateSessionCookieSameSite() default flag must be set to one of true, false, Strict, Lax or None (session.cookieSameSite)');
+  }
+
+  const value = cookieSameSite !== undefined ? cookieSameSite : defaultFlag;
+  if (!validValues.includes(value)) {
+    throw new TypeError('SameSite flag must be set to one of true, false, Strict, Lax or None (session.cookieSameSite)');
+  }
+
+  return value;
+}
+
+const validatePageHook = (hook, index) => {
+  try {
+    validateHookName(hook.hook);
+    if (typeof hook.middleware !== 'function') {
+      throw new TypeError('Hook middleware must be a function');
+    }
+  } catch (err) {
+    err.message = `Page hook at index ${index} is invalid: ${err.message}`;
+    throw err;
+  }
+}
+
+export function validatePageHooks(hooks) {
+  if (!Array.isArray(hooks)) {
+    throw new TypeError('Hooks must be an array');
+  }
+  hooks.forEach((hook, index) => validatePageHook(hook, index));
+  return hooks;
+}
+
+const validateField = (field, index) => {
+  try {
+    if (!(field instanceof PageField)) {
+      throw new TypeError('Page field must be an instance of PageField (created via the "field()" function)');
+    }
+  } catch (err) {
+    err.message = `Page field at index ${index} is invalid: ${err.message}`;
+    throw err;
+  }
+};
+
+export function validateFields(fields) {
+  if (!Array.isArray(fields)) {
+    throw new TypeError('Page fields must be an array (page[].fields)');
+  }
+  fields.forEach((hook, index) => validateField(hook, index));
+  return fields;
+}
+
+const validatePage = (page, index) => {
+  try {
+    validateWaypoint(page.waypoint);
+    validateView(page.view);
+    if (page.fields !== undefined) {
+      validateFields(page.fields);
+    }
+    if (page.hooks !== undefined) {
+      validatePageHooks(page.hooks);
+    }
+  } catch (err) {
+    err.message = `Page at index ${index} is invalid: ${err.message}`;
+    throw err;
+  }
+}
+
+export function validatePages(pages = []) {
+  if (!Array.isArray(pages)) {
+    throw new TypeError('Pages must be an array (pages)');
+  }
+  pages.forEach((page, index) => validatePage(page, index));
+  return pages;
+}
+
+export function validatePlan(plan) {
+  if (plan === undefined) {
+    return plan;
+  }
+
+  if (!(plan instanceof Plan)) {
+    throw new TypeError('Plan must be an instance the Plan class (plan)');
+  }
+
+  return plan;
+}
+
+const validateGlobalHook = (hook, index) => {
+  try {
+    validateHookName(hook.hook);
+    if (typeof hook.middleware !== 'function') {
+      throw new TypeError('Hook middleware must be a function');
+    }
+    if (hook.path !== undefined) {
+      validateHookPath(hook.path);
+    }
+  } catch (err) {
+    err.message = `Global hook at index ${index} is invalid: ${err.message}`;
+    throw err;
+  }
+};
+
+export function validateGlobalHooks(hooks) {
+  if (hooks === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(hooks)) {
+    throw new TypeError('Hooks must be an array');
+  }
+
+  hooks.forEach((hook, index) => validateGlobalHook(hook, index));
+  return hooks;
+}
+
+export function validatePlugins(plugins) {
+  return plugins;
+}
+
+export function validateEvents(events) {
+  return events;
+}
+
+/**
+ * Validates helmet configuration function.
+ *
+ * @access private
+ * @param {HelmetConfigurator} helmetConfigurator Configuration function
+ * @returns {HelmetConfigurator} Validated configuration function
+ * @throws {TypeError} when passed a non-function
+ */
+export function validateHelmetConfigurator(helmetConfigurator) {
+  if (helmetConfigurator !== undefined && !(helmetConfigurator instanceof Function)) {
+    throw new TypeError('Helmet configurator must be a function');
+  }
+
+  return helmetConfigurator;
+}
+
+/**
+ * Ingest, validate, sanitise and manipulate configuration parameters.
+ *
+ * @access private
+ * @param {ConfigurationOptions} config Config to ingest.
+ * @throws {Error|SyntaxError|TypeError} For invalid config values.
+ * @returns {object} Immutable config object.
+ */
+export default function ingest(config = {}) {
+  const parsed = {
+    // I18n configuration
+    i18n: validateI18nObject(config.i18n, (i18n) => ({
+      dirs: validateI18nDirs(i18n.dirs),
+      locales: validateI18nLocales(i18n.locales),
+    })),
+
+    // URL that will prefix all URLs in the browser address bar
+    mountUrl: validateMountUrl(config.mountUrl),
+
+    // Session
+    session: validateSessionObject(config.session, (session) => ({
+      name: validateSessionName(session.name),
+      secret: validateSessionSecret(session.secret),
+      secure: validateSessionSecure(session.secure),
+      ttl: validateSessionTtl(session.ttl),
+      store: validateSessionStore(session.store),
+      cookiePath: validateSessionCookiePath(session.cookiePath, '/'),
+      cookieSameSite: validateSessionCookieSameSite(session.cookieSameSite, 'Strict'),
+    })),
+
+    // Views configuration
+    views: validateViews(config.views),
+
+    // Pages
+    pages: validatePages(config.pages),
+
+    // Plan
+    plan: validatePlan(config.plan),
+
+    // Hooks
+    hooks: validateGlobalHooks(config.hooks),
+
+    // Plugins
+    plugins: validatePlugins(config.plugins),
+
+    // Events
+    events: validateEvents(config.events),
+
+    // Helmet configuration
+    helmetConfigurator: validateHelmetConfigurator(config.helmetConfigurator),
+
+  };
+
+  // Freeze to modifications
+  Object.freeze(parsed);
+  return parsed;
+}

package/src/lib/configure.js

@@ -0,0 +1,202 @@
+import { MemoryStore } from 'express-session';
+import { resolve } from 'path';
+import { createRequire } from 'module';
+import cookieParserFactory from 'cookie-parser';
+import dirname from './dirname.cjs';
+
+import configurationIngestor from './configuration-ingestor.js';
+import nunjucks from './nunjucks.js';
+import mountFactory from './mount.js';
+
+import staticRoutes from '../routes/static.js';
+import ancillaryRoutes from '../routes/ancillary.js';
+import journeyRoutes from '../routes/journey.js';
+
+import preMiddlewareFactory from '../middleware/pre.js';
+import postMiddlewareFactory from '../middleware/post.js';
+
+import sessionMiddlewareFactory from '../middleware/session.js';
+import i18nMiddlewareFactory from '../middleware/i18n.js';
+import dataMiddlewareFactory from '../middleware/data.js';
+
+import bodyParserMiddlewareFactory from '../middleware/body-parser.js';
+import csrfMiddlewareFactory from '../middleware/csrf.js';
+
+/**
+ * @access private
+ * @typedef {import('../casa').ConfigurationOptions} ConfigurationOptions
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').ConfigureResult} ConfigureResult
+ */
+
+/**
+ * @access private
+ * @typedef {import('../casa').Mounter} Mounter
+ */
+
+/**
+ * Configure some middleware for use in creating a new CASA app.
+ *
+ * @memberof module:@dwp/govuk-casa
+ * @param {ConfigurationOptions} config Configuration options
+ * @returns {ConfigureResult} Result
+ */
+export default function configure(config = {}) {
+  // Pass the raw config through each plugin's configure phase so they can
+  // optionally modify it
+  (config.plugins ?? []).forEach((plugin) => {
+    plugin.configure(config);
+  });
+
+  // Extract config
+  const ingestedConfig = configurationIngestor(config);
+  const {
+    mountUrl,
+    views = [],
+    session = {
+      secret: 'secret',
+      name: 'casasession',
+      secure: false,
+      ttl: 3600,
+      cookieSameSite: true,
+      cookiePath: '/',
+      store: undefined,
+    },
+    pages = [],
+    plan = null,
+    hooks = [],
+    plugins = [],
+    events = [],
+    i18n = {
+      dirs: [],
+      locales: ['en', 'cy'],
+    },
+    helmetConfigurator = undefined,
+  } = ingestedConfig;
+
+  // Prepare all page hooks so they are prefixed with the `journey.` scope.
+  pages.forEach((page) => {
+    /* eslint-disable-next-line no-param-reassign,no-return-assign */
+    (page?.hooks ?? []).forEach((h) => h.hook = `journey.${h.hook}`);
+  });
+
+  // Prepare a Nunjucks environment for rendering all templates.
+  // Resolve priority: userland templates > CASA templates > GOVUK templates > Plugin templates
+  const nunjucksEnv = nunjucks({
+    views: [
+      ...views,
+      resolve(dirname, '../../views'),
+      resolve(createRequire(dirname).resolve('govuk-frontend'), '../../'),
+    ],
+  });
+
+  // Prepare mandatory middleware
+  // These _must_ be added to the ExpressJS application at the start and end
+  // of all other middleware respectively.
+  const preMiddleware = preMiddlewareFactory({ helmetConfigurator });
+  const postMiddleware = postMiddlewareFactory();
+
+  // Prepare common middleware mounted prior to the ancillaryRouter
+  const cookieParserMiddleware = cookieParserFactory(session.secret);
+  const sessionMiddleware = sessionMiddlewareFactory({
+    cookieParserMiddleware,
+    secure: session.secure,
+    secret: session.secret,
+    name: session.name,
+    ttl: session.ttl,
+    cookieSameSite: session.cookieSameSite,
+    cookiePath: session.cookiePath,
+    store: session.store ?? new MemoryStore(),
+  });
+  const i18nMiddleware = i18nMiddlewareFactory({
+    directories: [
+      // Order is important; latter directories take precedence
+      resolve(dirname, '../../locales/'),
+      ...i18n.dirs,
+    ],
+    languages: i18n.locales,
+  });
+  const dataMiddleware = dataMiddlewareFactory({
+    plan,
+    events,
+  });
+
+  // Prepare form middleware and its constituent parts
+  // These are used for any forms, including waypoint page forms.
+  const bodyParserMiddleware = bodyParserMiddlewareFactory();
+  const csrfMiddleware = csrfMiddlewareFactory();
+
+  // Setup router to serve up bundled static assets
+  const staticRouter = staticRoutes();
+
+  // Setup ancillary router default stand-alone pages.
+  const ancillaryRouter = ancillaryRoutes({
+    sessionTtl: session.ttl,
+  });
+
+  // Setup waypoint router, which includes routes for every defined waypoint
+  const journeyRouter = journeyRoutes({
+    globalHooks: hooks,
+    pages,
+    plan,
+    csrfMiddleware,
+  });
+
+  // Create the mounting function
+  const mount = mountFactory({
+    nunjucksEnv,
+    mountUrl,
+    plan,
+    staticRouter,
+    ancillaryRouter,
+    journeyRouter,
+    preMiddleware,
+    sessionMiddleware,
+    i18nMiddleware,
+    bodyParserMiddleware,
+    dataMiddleware,
+    postMiddleware,
+  });
+
+  // Prepare configuration result
+  const configOutput = {
+    // Nunjucks environment, so it can be attached to other ExpressJS instances
+    // using `nunjucksEnv.express(myApp); myApp.set('view engine', 'njk');`.
+    nunjucksEnv,
+
+    // Mandatory middleware. User must add these to their ExpressJS app.
+    preMiddleware,
+    postMiddleware,
+
+    // Mandatory routers that consumer must mount onto their own ExpressJS parent app
+    staticRouter,
+    ancillaryRouter,
+    journeyRouter,
+
+    // CSRF middleware. Should be used wherever form pages are built.
+    csrfMiddleware,
+
+    // Other middleware
+    // These may be used by the application author to build other custom routes
+    cookieParserMiddleware,
+    sessionMiddleware,
+    bodyParserMiddleware,
+    i18nMiddleware,
+    dataMiddleware,
+
+    // Mount function
+    mount,
+
+    // Ingested config
+    config: ingestedConfig,
+  };
+
+  // Bootstrap all plugins
+  plugins.filter((p) => p.bootstrap).forEach((plugin) => plugin?.bootstrap(configOutput));
+
+  // Finished configuration
+  return configOutput;
+}

package/src/lib/dirname.cjs

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

package/src/lib/end-session.js

@@ -0,0 +1,45 @@
+import logger from './logger.js';
+
+const log = logger('lib:end-session');
+
+/**
+ * A convenience for ending the current session, but retaining some data in it,
+ * like the current language. It persists an empty session before regenerating
+ * a new ID.
+ *
+ * Note: this will not remove the session from server-side storage, which will
+ * instead be left up to the storage mechanism to clean up.
+ *
+ * @memberof module:@dwp/govuk-casa
+ * @param {import('express').Request} req HTTP request
+ * @param {Function} next Chain
+ * @returns {void}
+ */
+export default function endSession(req, next) {
+  const { language } = req.session;
+
+  Object.entries(req.session).forEach(([k]) => {
+    if (!['cookie'].includes(k)) {
+      // ESLint disabled as `Object.entries()` returns "own" properties, and
+      // all values are being null'd, so not assigned any user-controlled values
+      /* eslint-disable-next-line security/detect-object-injection */
+      req.session[k] = null;
+    }
+  });
+
+  req.session.save((saveErr) => {
+    if (saveErr) {
+      log.error(saveErr);
+    }
+
+    req.session.regenerate((err) => {
+      if (err) {
+        log.error(err);
+        next(err);
+      } else {
+        req.session.language = language;
+        req.session.save(next);
+      }
+    });
+  });
+}