@dwp/govuk-casa 7.0.7 → 7.0.8

package/dist/lib/configuration-ingestor.js

@@ -0,0 +1,490 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEvents = exports.validatePlugins = exports.validateGlobalHooks = exports.validatePlan = exports.validatePages = exports.validateFields = exports.validatePageHooks = exports.validateSessionCookieSameSite = exports.validateSessionCookiePath = exports.validateSessionStore = exports.validateSessionSecure = exports.validateSessionName = exports.validateSessionTtl = exports.validateSessionSecret = exports.validateViews = exports.validateSessionObject = exports.validateMountUrl = exports.validateI18nLocales = exports.validateI18nDirs = exports.validateI18nObject = void 0;
+/* eslint-disable sonarjs/no-duplicate-string */
+const field_js_1 = require("./field.js");
+const Plan_js_1 = __importDefault(require("./Plan.js"));
+const logger_js_1 = __importDefault(require("./logger.js"));
+const utils_js_1 = require("./utils.js");
+/**
+ * @typedef {import('./index').ContextEvent} ContextEvent
+ */
+/**
+ * @typedef {object} SessionOptions
+ * @property {string} [name=casasession] Session name
+ * @property {string} [secret=secret] Encryption secret
+ * @property {number} [ttl=3600] Session ttl (seconds)
+ * @property {boolean} [secure=false] Whether to use secure session cookies
+ * @property {boolean|string} [cookieSameSite=true] SameSite (true = Strict)
+ * @property {object} [store] Session store (default MemoryStore)
+ */
+/**
+ * @typedef {object} I18nOptions
+ * @property {string[]} dirs Directories to search for locale dictionaries
+ * @property {string[]} [locales=['en', 'cy']] Supported locales
+ */
+/**
+ * @typedef {object} GlobalHook Hook configuration
+ * @property {string} hook Hook name in format `<router>.<hook>`
+ * @property {Function} middleware Middleware function to insert at the hook point
+ * @property {string|RegExp} [path=undefined] Only run if route path matches this string/regexp
+ */
+/**
+ * @typedef {object} PageHook (extends GlobalHook)
+ * @property {string} hook Hook name (without a scope prefix)
+ * @property {Function} middleware Middleware function to insert at the hook point
+ */
+/**
+ * @typedef {object} Page Page configuration. A Page is the interactive representation of a waypoint
+ * @property {string} waypoint The waypoint with which this page is associated
+ * @property {string} view Template path
+ * @property {PageHook[]} [hooks=[]] Page-specific hooks (optional, default [])
+ * @property {PageField[]} [fields=[]] Fields to be managed on this page (optional, default [])
+ */
+/**
+ * Configure some middleware for use in creating a new CASA app.
+ *
+ * `mountUrl` is used to ensure the CSS content uses the correct reference to
+ * static assets in the `govuk-frontend` module.
+ *
+ * @typedef {object} ConfigurationOptions Configuration options
+ * @property {string} [mountUrl=/] URL path to root of CASA app
+ * @property {string[]} [views=[]] Template directories
+ * @property {SessionOptions} [session] Session configuration
+ * @property {Page[]} [pages=[]] Pages the represent waypoints
+ * @property {GlobalHook[]} [hooks=[]] Hooks to apply
+ * @property {object[]} [plugins=[]] Plugins
+ * @property {I18nOptions[]} [i18n] I18n configuration
+ * @property {Plan} plan CASA Plan
+ * @property {ContextEvent[]} [events=[]] Handlers for JourneyContext events
+ */
+const log = (0, logger_js_1.default)('lib:configuration-ingestor');
+const echo = (a) => (a);
+/**
+ * Validates and sanitises i18n obejct.
+ *
+ * @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.
+ */
+function validateI18nObject(i18n, cb = echo) {
+    if (Object.prototype.toString.call(i18n) !== '[object Object]') {
+        throw new TypeError('I18n must be an object');
+    }
+    return cb(i18n);
+}
+exports.validateI18nObject = validateI18nObject;
+/**
+ * Validates and sanitises i18n directory.
+ *
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+function validateI18nDirs(dirs) {
+    if (typeof dirs === 'undefined') {
+        throw ReferenceError('I18n directories are missing (i18n.dirs)');
+    }
+    else 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;
+}
+exports.validateI18nDirs = validateI18nDirs;
+/**
+ * Validates and sanitises i18n locales.
+ *
+ * @param {Array} locales Array of locales.
+ * @throws {SyntaxError} For invalid locales.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of locales.
+ */
+function validateI18nLocales(locales) {
+    if (typeof locales === 'undefined') {
+        throw ReferenceError('I18n locales are missing (i18n.locales)');
+    }
+    else 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;
+}
+exports.validateI18nLocales = validateI18nLocales;
+/**
+ * Validates and sanitises mount url.
+ *
+ * @param {string} mountUrl URL from which Express app will be served.
+ * @param {string} name Name of the URL type (Mount URL, or Proxy Mount URL).
+ * @throws {SyntaxError} For invalid URL.
+ * @returns {string} Sanitised URL.
+ */
+function validateMountUrl(mountUrl, name = 'Mount URL') {
+    if (typeof mountUrl === 'undefined') {
+        return '/';
+    }
+    if (!mountUrl.match(/\/$/)) {
+        throw new SyntaxError(`${name} must include a trailing slash (/)`);
+    }
+    return mountUrl;
+}
+exports.validateMountUrl = validateMountUrl;
+/**
+ * Validates and sanitises sessions object.
+ *
+ * @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.
+ */
+function validateSessionObject(session, cb = echo) {
+    if (session === undefined) {
+        return cb(session);
+    }
+    if (typeof session !== 'object') {
+        throw new TypeError('Session config has not been specified');
+    }
+    return cb(session);
+}
+exports.validateSessionObject = validateSessionObject;
+/**
+ * Validates and sanitises view directory.
+ *
+ * @param {Array} dirs Array of directories.
+ * @throws {SyntaxError} For invalid directories.
+ * @throws {TypeError} For invalid type.
+ * @returns {Array} Array of directories.
+ */
+function validateViews(dirs) {
+    if (typeof dirs === 'undefined') {
+        throw ReferenceError('View directories are missing (views)');
+    }
+    else 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;
+}
+exports.validateViews = validateViews;
+/**
+ * Validates and sanitises sessions secret.
+ *
+ * @param {string} secret Session secret.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Secret.
+ */
+function validateSessionSecret(secret) {
+    if (typeof secret === 'undefined') {
+        throw ReferenceError('Session secret is missing (sessions.secret)');
+    }
+    else if (typeof secret !== 'string') {
+        throw new TypeError('Session secret must be a string (sessions.secret)');
+    }
+    return secret;
+}
+exports.validateSessionSecret = validateSessionSecret;
+/**
+ * Validates and sanitises sessions ttl.
+ *
+ * @param {number} ttl Session ttl (seconds).
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {number} Ttl.
+ */
+function validateSessionTtl(ttl) {
+    if (typeof ttl === 'undefined') {
+        throw ReferenceError('Session ttl is missing (sessions.ttl)');
+    }
+    else if (typeof ttl !== 'number') {
+        throw new TypeError('Session ttl must be an integer (sessions.ttl)');
+    }
+    return ttl;
+}
+exports.validateSessionTtl = validateSessionTtl;
+/**
+ * Validates and sanitises sessions name.
+ *
+ * @param {string} name Session name.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Name.
+ */
+function validateSessionName(name) {
+    if (typeof name === 'undefined') {
+        throw ReferenceError('Session name is missing (sessions.name)');
+    }
+    else if (typeof name !== 'string') {
+        throw new TypeError('Session name must be a string (sessions.name)');
+    }
+    return name;
+}
+exports.validateSessionName = validateSessionName;
+/**
+ * Validates and sanitises sessions secure flag.
+ *
+ * @param {boolean} secure Session secure flag.
+ * @throws {ReferenceError} For missing value type.
+ * @throws {TypeError} For invalid value.
+ * @returns {string} Name.
+ */
+function validateSessionSecure(secure) {
+    if (typeof secure === 'undefined') {
+        throw ReferenceError('Session secure flag is missing (sessions.secure)');
+    }
+    else if (typeof secure !== 'boolean') {
+        throw new TypeError('Session secure flag must be boolean (sessions.secure)');
+    }
+    return secure;
+}
+exports.validateSessionSecure = validateSessionSecure;
+/**
+ * Validates and sanitises sessions store.
+ *
+ * @param {Function} store Session store.
+ * @returns {Function} Store.
+ */
+function validateSessionStore(store) {
+    if (typeof store === 'undefined') {
+        log.warn('Using MemoryStore session storage, which is not suitable for production');
+        return null;
+    }
+    return store;
+}
+exports.validateSessionStore = validateSessionStore;
+/**
+ * Validates and sanitises sessions cookie url path.
+ *
+ * @param {string} cookiePath Session cookie url path.
+ * @param {string} defaultPath Default path if none specified.
+ * @returns {string} Cookie path.
+ */
+function validateSessionCookiePath(cookiePath, defaultPath = '/') {
+    if (typeof cookiePath === 'undefined') {
+        return defaultPath;
+    }
+    return cookiePath;
+}
+exports.validateSessionCookiePath = validateSessionCookiePath;
+/**
+ * Validates and sanitises sessions cookie "sameSite" flag. One of:
+ * true (Strict)
+ * false (will not set the flag at all)
+ * Strict
+ * Lax
+ * None
+ *
+ * @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
+ */
+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 (sessions.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 (sessions.cookieSameSite)');
+    }
+    return value;
+}
+exports.validateSessionCookieSameSite = validateSessionCookieSameSite;
+const validatePageHook = (hook, index) => {
+    try {
+        (0, utils_js_1.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;
+    }
+};
+function validatePageHooks(hooks) {
+    if (!Array.isArray(hooks)) {
+        throw new TypeError('Hooks must be an array');
+    }
+    hooks.forEach((hook, index) => validatePageHook(hook, index));
+    return hooks;
+}
+exports.validatePageHooks = validatePageHooks;
+const validateField = (field, index) => {
+    try {
+        if (!(field instanceof field_js_1.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;
+    }
+};
+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;
+}
+exports.validateFields = validateFields;
+const validatePage = (page, index) => {
+    try {
+        (0, utils_js_1.validateWaypoint)(page.waypoint);
+        (0, utils_js_1.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;
+    }
+};
+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;
+}
+exports.validatePages = validatePages;
+function validatePlan(plan) {
+    if (plan === undefined) {
+        return plan;
+    }
+    if (!(plan instanceof Plan_js_1.default)) {
+        throw new TypeError('Plan must be an instance the Plan class (plan)');
+    }
+    return plan;
+}
+exports.validatePlan = validatePlan;
+const validateGlobalHook = (hook, index) => {
+    try {
+        (0, utils_js_1.validateHookName)(hook.hook);
+        if (typeof hook.middleware !== 'function') {
+            throw new TypeError('Hook middleware must be a function');
+        }
+        if (hook.path !== undefined) {
+            (0, utils_js_1.validateHookPath)(hook.path);
+        }
+    }
+    catch (err) {
+        err.message = `Global hook at index ${index} is invalid: ${err.message}`;
+        throw err;
+    }
+};
+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;
+}
+exports.validateGlobalHooks = validateGlobalHooks;
+function validatePlugins(plugins) {
+    return plugins;
+}
+exports.validatePlugins = validatePlugins;
+function validateEvents(events) {
+    return events;
+}
+exports.validateEvents = validateEvents;
+/**
+ * Ingest, validate, sanitise and manipulate configuration parameters.
+ *
+ * @param {ConfigurationOptions} config Config to ingest.
+ * @throws {Error|SyntaxError|TypeError} For invalid config values.
+ * @returns {object} Immutable config object.
+ */
+function ingest(config = {}) {
+    const parsed = {
+        // I18n configuration
+        i18n: validateI18nObject(config.i18n, (i18n) => ({
+            dirs: validateI18nDirs(i18n.dirs),
+            locales: validateI18nLocales(i18n.locales),
+        })),
+        // Public URL from which the app will be served
+        mountUrl: validateMountUrl(config.mountUrl),
+        // Session
+        sessions: 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),
+    };
+    // Freeze to modifications
+    Object.freeze(parsed);
+    return parsed;
+}
+exports.default = ingest;
+// module.exports = {
+//   ingest,
+//   validateAllowPageEdit,
+//   validateUseStickyEdit,
+//   validateContentSecurityPolicies,
+//   validateHeadersObject,
+//   validateHeadersDisabled,
+//   validateI18nObject,
+//   validateI18nDirs,
+//   validateI18nLocales,
+//   validateMountController,
+//   validateMountUrl,
+//   validatePhase,
+//   validateServiceName,
+//   validateSessionExpiryController,
+//   validateSessionObject,
+//   validateSessionCookiePath,
+//   validateSessionCookieSameSite,
+//   validateSessionName,
+//   validateSessionSecret,
+//   validateSessionSecure,
+//   validateSessionStore,
+//   validateSessionTtl,
+//   validateViewsObject,
+//   validateViews,
+// };

package/dist/lib/configure.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @typedef {import('express').RequestHandler} ExpressRequestHandler
+ */
+/**
+ * @typedef {import('./index').MutableRouter} MutableRouter
+ */
+/**
+ * @typedef {import('./configuration-ingestor').ConfigurationOptions} ConfigurationOptions
+ */
+/**
+ * @typedef {object} ConfigureResult Result of a call to configure() function
+ * @property {nunjucks.Environment} nunjucksEnv Nunjucks environment
+ * @property {MutableRouter} staticRouter Router handling all static assets
+ * @property {MutableRouter} ancillaryRouter Router handling ancillary routes
+ * @property {MutableRouter} journeyRouter Router handling all waypoint requests
+ * @property {ExpressRequestHandler[]} preMiddleware Middleware mounted before anything else
+ * @property {ExpressRequestHandler[]} postMiddleware Middleware mounted after everything else
+ * @property {ExpressRequestHandler[]} csrfMiddleware CSRF get/set middleware (useful for forms)
+ * @property {ExpressRequestHandler} sessionMiddleware Session middleware
+ * @property {ExpressRequestHandler[]} cookieParserMiddleware Cookie-parsing middleware
+ * @property {ExpressRequestHandler[]} i18nMiddleware I18n preparation middleware
+ * @property {ExpressRequestHandler} bodyParserMiddleware Body parsing middleware
+ * @property {Function} mount Function used to mount all CASA artifacts onto an ExpressJS app
+ */
+/**
+ * Configure some middleware for use in creating a new CASA app.
+ *
+ * `mountUrl` is used to ensure the CSS content uses the correct reference to
+ * static assets in the `govuk-frontend` module.
+ *
+ * @param {ConfigurationOptions} config Configuration options
+ * @returns {ConfigureResult} Result
+ */
+export default function configure(config?: ConfigurationOptions): ConfigureResult;
+export type ExpressRequestHandler = import('express').RequestHandler;
+export type MutableRouter = import('./index').MutableRouter;
+export type ConfigurationOptions = import('./configuration-ingestor').ConfigurationOptions;
+/**
+ * Result of a call to configure() function
+ */
+export type ConfigureResult = {
+    /**
+     * Nunjucks environment
+     */
+    nunjucksEnv: nunjucks.Environment;
+    /**
+     * Router handling all static assets
+     */
+    staticRouter: MutableRouter;
+    /**
+     * Router handling ancillary routes
+     */
+    ancillaryRouter: MutableRouter;
+    /**
+     * Router handling all waypoint requests
+     */
+    journeyRouter: MutableRouter;
+    /**
+     * Middleware mounted before anything else
+     */
+    preMiddleware: ExpressRequestHandler[];
+    /**
+     * Middleware mounted after everything else
+     */
+    postMiddleware: ExpressRequestHandler[];
+    /**
+     * CSRF get/set middleware (useful for forms)
+     */
+    csrfMiddleware: ExpressRequestHandler[];
+    /**
+     * Session middleware
+     */
+    sessionMiddleware: ExpressRequestHandler;
+    /**
+     * Cookie-parsing middleware
+     */
+    cookieParserMiddleware: ExpressRequestHandler[];
+    /**
+     * I18n preparation middleware
+     */
+    i18nMiddleware: ExpressRequestHandler[];
+    /**
+     * Body parsing middleware
+     */
+    bodyParserMiddleware: ExpressRequestHandler;
+    /**
+     * Function used to mount all CASA artifacts onto an ExpressJS app
+     */
+    mount: Function;
+};