@dwp/govuk-casa 8.7.9 → 8.8.0

package/src/lib/nunjucks-filters.js

@@ -0,0 +1,150 @@
+import merge from 'deepmerge';
+import { DateTime } from 'luxon';
+import nunjucks from 'nunjucks';
+
+const { all: deepmergeAll } = merge;
+
+// Arrays will be merged such that elements at the same index will be merged
+// into each other
+// ref: https://www.npmjs.com/package/deepmerge
+
+const combineMerge = (target, source, options) => {
+  const destination = target.slice()
+
+  source.forEach((item, index) => {
+    // ESLint disabled as `index` is only an integer
+    /* eslint-disable security/detect-object-injection */
+    if (typeof destination[index] === 'undefined') {
+      destination[index] = options.cloneUnlessOtherwiseSpecified(item, options)
+    } else if (options.isMergeableObject(item)) {
+      destination[index] = merge(target[index], item, options)
+    } else if (target.indexOf(item) === -1) {
+      destination.push(item)
+    }
+    /* eslint-enable security/detect-object-injection */
+  })
+  return destination
+}
+
+// Allows objects to be deepmerged and retain their type, without becoming [object Object]
+// ref: https://github.com/jonschlinkert/is-plain-object/blob/master/is-plain-object.js
+
+function isObject(o) {
+  return Object.prototype.toString.call(o) === '[object Object]';
+}
+
+function isPlainObjectOrArray(o) {
+  if (Array.isArray(o)) {
+    return true
+  }
+  if (isObject(o) === false) {
+    return false
+  }
+  const ctor = o.constructor;
+  if (ctor === undefined) {
+    return true
+  }
+  const prot = ctor.prototype;
+  if (isObject(prot) === false) {
+    return false
+  }
+  // eslint-disable-next-line no-prototype-builtins
+  if (prot.hasOwnProperty('isPrototypeOf') === false) {
+    return false;
+  }
+  return true;
+}
+
+function mergeObjects(...objects) {
+  return deepmergeAll([Object.create(null), ...objects], { arrayMerge: combineMerge, isMergeableObject: isPlainObjectOrArray });
+}
+/**
+ * Determine whether a value exists in a list.
+ *
+ * @memberof NunjucksFilters
+ * @param {any[]} source List of items to search
+ * @param {any} search Item to search within the `source`
+ * @returns {boolean} True if the search item was found
+ */
+function includes(source = [], search = '') {
+  return source.includes(search);
+}
+
+/**
+ * Format a given date.
+ *
+ * Requires NodeJS >= 14 to make use of bundled date locale data.
+ *
+ * `date` may be any of the following types:
+ *   object - {dd:'', mm:'', yyyy:''}
+ *
+ * @memberof NunjucksFilters
+ * @param  {object} date Date
+ * @param  {string} date.dd Day
+ * @param  {string} date.mm Month
+ * @param  {string} date.yyyy Year
+ * @param  {object} [config] Options
+ * @param  {string} [config.locale] Locale (default 'en')
+ * @param  {string} [config.format] Format (default 'd MMMM yyyy')
+ * @returns {string} Formatted date
+ */
+function formatDateObject(date, config = {}) {
+  const { locale = 'en', format = 'd MMMM yyyy' } = config;
+
+  if (
+    Object.prototype.toString.call(date) === '[object Object]'
+    && 'yyyy' in date
+    && 'mm' in date
+    && 'dd' in date
+  ) {
+    return DateTime.fromObject({
+      year: Math.max(0, parseInt(date.yyyy, 10)),
+      month: Math.max(0, parseInt(date.mm, 10)),
+      day: Math.max(1, parseInt(date.dd, 10)),
+    }).setLocale(locale).toFormat(format);
+  }
+  return 'INVALID DATE OBJECT';
+}
+
+/**
+ * Attribute values will be HTML/attribute escaped.
+ *
+ * Example:
+ *   Given: {class: 'basic', 'data-ga': 3}
+ *   Output: class="basic" data-ga="3"
+ *
+ * @memberof NunjucksFilters
+ * @param {object} attrsObject Attributes object (in name:value pairs)
+ * @returns {string} Formatted
+ */
+function renderAsAttributes(attrsObject) {
+  const attrsList = [];
+  if (typeof attrsObject === 'object') {
+    Object.keys(attrsObject).forEach((key) => {
+      // ESLint disable as `attrsObject` is dev-controlled, `Object.keys()` has
+      // been used (to get "own" properties) and `m` is one of the characters
+      // found by the regex.
+      /* eslint-disable security/detect-object-injection */
+      const value = String(attrsObject[key]).replace(/[<>"'&]/g, (m) => ({
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        '\'': '&#039;',
+        '&': '&amp;',
+      }[m]));
+      /* eslint-enable security/detect-object-injection */
+      attrsList.push(`${key}="${value}"`);
+    });
+  }
+  return new nunjucks.runtime.SafeString(attrsList.join(' '));
+}
+
+/**
+ * @namespace NunjucksFilters
+ */
+export {
+  mergeObjects,
+  includes,
+  formatDateObject,
+  renderAsAttributes,
+};

package/src/lib/nunjucks.js

@@ -0,0 +1,53 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { Environment } from 'nunjucks';
+import dirname from './dirname.cjs';
+import CasaTemplateLoader from './CasaTemplateLoader.js';
+import {
+  mergeObjects, includes, renderAsAttributes, formatDateObject,
+} from './nunjucks-filters.js';
+
+/**
+ * @typedef {object} NunjucksOptions
+ * @property {string[]} [views=[]] Template file directories (optional, default [])
+ */
+
+/**
+ * Create a Nunjucks environment.
+ *
+ * @access private
+ * @param {NunjucksOptions} options Nunjucks options
+ * @returns {Environment} Nunjucks Environment instance
+ */
+export default function nunjucksConfig({
+  views = [],
+}) {
+  // Prepare a single Nunjucks environment for all responses to use. Note that
+  // we cannot prepare response-specific global functions/filters if we use a
+  // single environment, but the performance gains of doing so are significant.
+  const loader = new CasaTemplateLoader(views, {
+    watch: false,
+    noCache: false,
+  });
+
+  const env = new Environment(loader, {
+    autoescape: true,
+    throwOnUndefined: false,
+    trimBlocks: false,
+    lstripBlocks: false,
+  });
+
+  // Enhancement to expose loader functions
+  env.modifyBlock = loader.modifyBlock.bind(loader);
+
+  // Globals
+  // These can't be modified once set. But they can be overridden by res.locals.
+  env.addGlobal('casaVersion', JSON.parse(readFileSync(resolve(dirname, '../../package.json'))).version);
+
+  env.addGlobal('mergeObjects', mergeObjects);
+  env.addGlobal('includes', includes);
+  env.addGlobal('formatDateObject', formatDateObject);
+  env.addGlobal('renderAsAttributes', renderAsAttributes);
+
+  return env;
+}

package/src/lib/utils.js

@@ -0,0 +1,232 @@
+/**
+ * @access private
+ * @typedef {import('../casa').GlobalHook | import('../casa').PageHook} Hook
+ */
+
+/**
+ * Determine if value is empty. Recurse over objects.
+ *
+ * @access private
+ * @param  {any} val Value to check
+ * @returns {boolean} True if the object is empty
+ */
+export function isEmpty(val) {
+  if (
+    val === null
+    || typeof val === 'undefined'
+    || (typeof val === 'string' && val === '')
+  ) {
+    return true;
+  }
+  if (Array.isArray(val) || typeof val === 'object') {
+    // ESLint disabled as `k` is an "own property" (thanks to `Object.keys()`)
+    /* eslint-disable-next-line security/detect-object-injection */
+    return Object.keys(val).filter((k) => !isEmpty(val[k])).length === 0;
+  }
+  return false;
+}
+
+/**
+ * Test is a value can be stringified (numbers or strings)
+ *
+ * @access private
+ * @param {any} value Item to test
+ * @returns {boolean} Whether the value is stringable or not
+ */
+export function isStringable(value) {
+  return typeof value === 'string' || typeof value === 'number';
+}
+
+/**
+ * Extract the middleware functions that are relevant for the given hook and
+ * path.
+ *
+ * @access private
+ * @param {string} hookName Hook name (including scope prefix)
+ * @param {string} path URL path to match (relative to mountUrl)
+ * @param {Hook[]} hooks Hooks to be applied at the page level
+ * @returns {Function[]} An array of middleware that should be applied
+ */
+export function resolveMiddlewareHooks(hookName, path, hooks = []) {
+  /* eslint-disable-next-line max-len */
+  const pathMatch = (h) => h.path === undefined || (h.path instanceof RegExp && h.path.test(path)) || h.path === path;
+  return hooks.filter((h) => h.hook === hookName).filter(pathMatch).map((h) => h.middleware);
+}
+
+/**
+ * Coerce an input to a string.
+ *
+ * @access private
+ * @param {any} input Input to be stringified
+ * @param {string} fallback Fallback to use if input can't be stringified
+ * @returns {string} The stringified input
+ */
+export function stringifyInput(input, fallback) {
+  // Not using param defaults here as the fallback may be explicitly "undefined"
+  const fb = arguments.length === 2 && (isStringable(fallback) || fallback === undefined) ? fallback : '';
+  return isStringable(input) ? String(input) : fb;
+}
+
+/**
+ * Strip whitespace from a string.
+ *
+ * @access private
+ * @param {string} value value to be stripped of whitespace
+ * @param {object} options overrides for the default whitespace replacements
+ * @returns {string} value stripped of white space
+ * @throws {TypeError}
+ */
+export function stripWhitespace(value, options) {
+  const opts = {
+    leading: '',
+    trailing: '',
+    nested: ' ',
+    ...options,
+  };
+
+  if (typeof value !== 'string') {
+    throw new TypeError('value must be a string');
+  }
+
+  if (typeof opts.leading !== 'string') {
+    throw new TypeError('leading must be a string');
+  }
+
+  if (typeof opts.trailing !== 'string') {
+    throw new TypeError('trailing must be a string');
+  }
+
+  if (typeof opts.nested !== 'string') {
+    throw new TypeError('nested must be a string');
+  }
+
+  return value
+    .replace(/^\s+/, opts.leading)
+    .replace(/\s+$/, opts.trailing)
+    .replace(/\s+/g, opts.nested);
+}
+
+/* ------------------------------------------------ validation / sanitisation */
+
+/**
+ * Checks if the given string can be used as an object key.
+ *
+ * @access private
+ * @param {string} key Proposed Object key
+ * @returns {string} Same key if it's valid
+ * @throws {Error} if proposed key is an invalid keyword
+ */
+export function notProto(key) {
+  if (['__proto__', 'constructor', 'prototype'].includes(String(key).toLowerCase())) {
+    throw new Error('Attempt to use prototype key disallowed');
+  }
+  return key;
+}
+
+/**
+ * Validate a hook name.
+ *
+ * @access private
+ * @param {string} hookName Hook name
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateHookName(hookName) {
+  if (typeof hookName !== 'string') {
+    throw new TypeError('Hook name must be a string');
+  }
+
+  if (!hookName.length) {
+    throw new SyntaxError('Hook name must not be empty');
+  }
+
+  if (!hookName.match(/^([a-z_]+\.|)[a-z_]+$/i)) {
+    throw new SyntaxError('Hook name must match either <scope>.<hookname> or <hookname> formats');
+  }
+}
+
+/**
+ * Validate a hook path.
+ *
+ * @access private
+ * @param {string} path URL path
+ * @returns {void}
+ * @throws {TypeError}
+ */
+export function validateHookPath(path) {
+  if (typeof path !== 'string' && !(path instanceof RegExp)) {
+    throw new TypeError('Hook path must be a string or RegExp');
+  }
+}
+
+/**
+ * Validate a URL path.
+ *
+ * @access private
+ * @param {string} path URL path
+ * @returns {string} Same string, if valid
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateUrlPath(path) {
+  if (typeof path !== 'string') {
+    throw new TypeError('URL path must be a string');
+  }
+
+  if (path.match(/[^/a-z0-9_-]/)) {
+    throw new SyntaxError('URL path must contain only a-z, 0-9, -, _ and / characters');
+  }
+
+  if (path.match(/\/{2,}/)) {
+    throw new SyntaxError('URL path must not contain consecutive /');
+  }
+
+  return path;
+}
+
+/**
+ * Validate a template name.
+ *
+ * @access private
+ * @param {string} view Template name
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateView(view) {
+  if (typeof view !== 'string') {
+    throw new TypeError('View must be a string');
+  }
+
+  if (!view.length) {
+    throw new SyntaxError('View must not be empty');
+  }
+
+  if (!view.match(/^[a-z0-9/_-]+\.njk$/i)) {
+    throw new SyntaxError('View must contain only a-z, 0-9, -, _ and / characters, and end in .njk');
+  }
+}
+
+/**
+ * Validate a waypoint.
+ *
+ * @access private
+ * @param {string} waypoint Waypoint
+ * @returns {void}
+ * @throws {TypeError}
+ * @throws {SyntaxError}
+ */
+export function validateWaypoint(waypoint) {
+  if (typeof waypoint !== 'string') {
+    throw new TypeError('Waypoint must be a string');
+  }
+
+  if (!waypoint.length) {
+    throw new SyntaxError('Waypoint must not be empty');
+  }
+
+  if (waypoint.match(/[^/a-z0-9_-]/)) {
+    throw new SyntaxError('Waypoint must contain only a-z, 0-9, -, _ and / characters');
+  }
+}

package/src/lib/validators/dateObject.js

@@ -0,0 +1,169 @@
+/* eslint-disable class-methods-use-this */
+import { DateTime } from 'luxon';
+import lodash from 'lodash';
+import ValidationError from '../ValidationError.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import { stringifyInput, stripWhitespace } from '../utils.js';
+
+const { isPlainObject } = lodash;
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} DateObjectConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ * @property {object} [afterOffsetFromNow] Offset from now
+ * @property {ErrorMessageConfig} [errorMsgAfterOffset] Error if date is after this offset
+ * @property {object} [beforeOffsetFromNow] Offset from now
+ * @property {ErrorMessageConfig} [errorMsgBeforeOffset] Error if date is before this offset
+ * @property {boolean} [allowMonthNames=false] Allow "Jan", "January", etc
+ * @property {boolean} [allowSingleDigitDay=false] Allow "1" rather than "01"
+ * @property {boolean} [allowSingleDigitMonth=false] Allow "1" rather than "01"
+ * @property {DateTime} [now=false] Override the notion of "now" (useful for testing)
+ */
+
+/**
+ * Date object format:
+ *  {
+ *    dd: <string>,
+ *    mm: <string>,
+ *    yyyy: <string>
+ *  }.
+ *
+ * Note that the time part will be zero'ed, as we are only interested in the
+ * date component (minimum day resolution).
+ *
+ * See {@link DateObjectConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class DateObject extends ValidatorFactory {
+  /** @property {string} name Validator name ("dateObject") */
+  name = 'dateObject';
+
+  validate(value, dataContext = {}) {
+    const config = {
+      errorMsg: {
+        inline: 'validation:rule.dateObject.inline',
+        summary: 'validation:rule.dateObject.summary',
+      },
+      errorMsgAfterOffset: {
+        inline: 'validation:rule.dateObject.afterOffset.inline',
+        summary: 'validation:rule.dateObject.afterOffset.summary',
+      },
+      errorMsgBeforeOffset: {
+        inline: 'validation:rule.dateObject.beforeOffset.inline',
+        summary: 'validation:rule.dateObject.beforeOffset.summary',
+      },
+      now: DateTime.local(),
+      allowSingleDigitDay: false,
+      allowSingleDigitMonth: false,
+      allowMonthNames: false,
+      afterOffsetFromNow: undefined,
+      beforeOffsetFromNow: undefined,
+      ...this.config,
+    };
+
+    let valid = false;
+    let { errorMsg } = config;
+    let luxonDate;
+    const NOW = config.now.startOf('day');
+
+    // Accepted formats
+    let formats = ['dd-MM-yyyy'];
+    const formatTests = [{
+      flags: [config.allowSingleDigitDay],
+      formats: ['d-MM-yyyy'],
+    }, {
+      flags: [config.allowSingleDigitDay, config.allowSingleDigitMonth],
+      formats: ['d-M-yyyy'],
+    }, {
+      flags: [config.allowSingleDigitDay, config.allowMonthNames],
+      formats: ['d-MMM-yyyy', 'd-MMMM-yyyy'],
+    }, {
+      flags: [config.allowSingleDigitMonth],
+      formats: ['dd-M-yyyy'],
+    }, {
+      flags: [config.allowMonthNames],
+      formats: ['dd-MMM-yyyy', 'dd-MMMM-yyyy'],
+    }];
+    formatTests.forEach((test) => {
+      if (test.flags.every((v) => v === true)) {
+        formats = [...formats, ...test.formats];
+      }
+    });
+
+    if (typeof value === 'object') {
+      formats.find((format) => {
+        luxonDate = DateTime.fromFormat(
+          [value.dd, value.mm, value.yyyy].join('-'),
+          format,
+        ).startOf('day');
+
+        valid = luxonDate.isValid;
+
+        return valid;
+      });
+
+      if (luxonDate) {
+        // Check date is after the specified duration from now.
+        // Need to use UTC() otherwise DST shifts can affect the calculated offset
+        if (config.afterOffsetFromNow) {
+          const offsetDate = NOW.plus(config.afterOffsetFromNow).startOf('day');
+
+          if (luxonDate <= offsetDate) {
+            valid = false;
+            errorMsg = config.errorMsgAfterOffset;
+          }
+        }
+
+        // Check date is before the specified duration from now
+        // Need to use UTC() otherwise DST shifts can affect the calculated offset
+        if (config.beforeOffsetFromNow) {
+          const offsetDate = NOW.plus(config.beforeOffsetFromNow).startOf('day');
+
+          if (luxonDate >= offsetDate) {
+            valid = false;
+            errorMsg = config.errorMsgBeforeOffset;
+          }
+        }
+      }
+
+      // Check presence of each object component (dd, mm, yyyy) in order to log
+      // which specific parts are in error
+      errorMsg.focusSuffix = [];
+      if (!Object.prototype.hasOwnProperty.call(value, 'dd') || !value.dd) {
+        errorMsg.focusSuffix.push('[dd]');
+      }
+      if (!Object.prototype.hasOwnProperty.call(value, 'mm') || !value.mm) {
+        errorMsg.focusSuffix.push('[mm]');
+      }
+      if (!Object.prototype.hasOwnProperty.call(value, 'yyyy') || !value.yyyy) {
+        errorMsg.focusSuffix.push('[yyyy]');
+      }
+
+      // If the date is invalid, but not specific parts have been highlighted in
+      // error, then highlight all inputs, focusing on the [dd] first
+      if (!valid && !errorMsg.focusSuffix.length) {
+        errorMsg.focusSuffix = ['[dd]', '[mm]', '[yyyy]'];
+      }
+    }
+
+    return valid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return isPlainObject(value) ? {
+        dd: stripWhitespace(stringifyInput(value.dd)),
+        mm: stripWhitespace(stringifyInput(value.mm)),
+        yyyy: stripWhitespace(stringifyInput(value.yyyy)),
+      } : Object.create(null);
+    }
+    return undefined;
+  }
+}

package/src/lib/validators/email.js

@@ -0,0 +1,55 @@
+/* eslint-disable class-methods-use-this */
+import validatorPkg from 'validator';
+import ValidationError from '../ValidationError.js';
+import ValidatorFactory from '../ValidatorFactory.js';
+import { stringifyInput } from '../utils.js';
+
+const { isEmail } = validatorPkg; // CommonJS
+
+/**
+ * @access private
+ * @typedef {import('../../casa').ErrorMessageConfig} ErrorMessageConfig
+ */
+
+/**
+ * @typedef {object} EmailConfigOptions
+ * @property {ErrorMessageConfig} errorMsg Error message config
+ */
+
+/**
+ * Email address.
+ *
+ * This is not an exhaustive validation, and is permissive.
+ *
+ * See {@link EmailConfigOptions} for `make()` options.
+ *
+ * @memberof Validators
+ * @augments ValidatorFactory
+ */
+export default class Email extends ValidatorFactory {
+  /** @property {string} name Validator name ("email") */
+  name = 'email';
+
+  validate(value, dataContext = {}) {
+    let isValid;
+    try {
+      isValid = isEmail(value);
+    } catch (e) {
+      isValid = false;
+    }
+
+    const errorMsg = this.config.errorMsg || {
+      summary: 'validation:rule.email.summary',
+      inline: 'validation:rule.email.inline',
+    };
+
+    return isValid ? [] : [ValidationError.make({ errorMsg, dataContext })];
+  }
+
+  sanitise(value) {
+    if (value !== undefined) {
+      return stringifyInput(value);
+    }
+    return undefined;
+  }
+}