hof 23.0.0-frontend-v4-beta.13 → 23.0.0-frontend-v4-beta.15

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 2025-10-25, Version 23.0.0 (Stable), @Rhodine-orleans-lindsay
+## 2025-12-09, Version 23.0.0 (Stable), @Rhodine-orleans-lindsay
 ### Changed
 - Updated cookie banner view to follow GOV.UK design system. Updated cookieSettings.js to allow for different confirmation text based on whether cookies were accepted or rejected
 - Added inputmode='numeric' to date component
@@ -10,7 +10,39 @@
 - Added a modifier for phone text input styles that accept sequences of digits
 - Added govuk-template--rebranded class to govuk template html to enable govuk rebrand styles:
   - Updated header and footer to follow GOV.UK design system as part of rebrand
-  * ⛓️‍💥 **BREAKING CHANGE** : files and folders in a project's `assets` folder will need to be moved to a `assets/rebrand` folder. Add a `rebrand` folder to the `assets` folder. e.g. `assets/images` will need to be moved to `assets/rebrand/images`. 
+
+## 2025-11-20, Version 22.12.0 (Stable), @dk4g @jamiecarterHO
+
+### Infrastructure  
+- Updated CI/CD pipeline to test against Node.js 20.x, 22.x, and 24.x
+- Updated Redis testing versions to 7 and 8
+- Added `NODE_VERSION` environment variable for consistent Node.js version across jobs
+- Updated release process to use Node.js 24 for tagging and publishing operations
+
+### Security
+  - Replaced deprecated `crypto.createCipher`/`crypto.createDecipher` with `crypto.createCipheriv`/`crypto.createDecipheriv`
+  - Added proper initialisation vector (IV) handling for enhanced security
+  - Enforced 32-byte session secret requirement for AES-256 encryption compatibility
+  - Removed insecure default session secret ('changethis') - now requires explicit configuration
+
+### Migration Notes
+- **Session Reset Required**: Due to enhanced encryption security, existing user sessions will be invalidated and users will need to re-authenticate after this update
+- **Session Secret**: You must now set a unique `SESSION_SECRET` environment variable of exactly 32 bytes for encryption compatibility. 
+For testing purposes, you can use the following command to generate a random value. For production environments, consult a security expert or refer to official cryptographic guidelines to generate a secure secret
+`node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`
+
+## 2025-11-15, Version 22.11.0 (Stable), @Rhodine-orleans-lindsay
+
+### Changed
+- Updated custom session-timeout handling so that custom behaviours are not blocked by a `404` middleware error.
+
+### Added
+- Added a `CUSTOM_SESSION_EXPIRY` environment variable so that a time other than the redis session ttl can be used for the session timeout. **IMPORTANT**: The `CUSTOM_SESSION_EXPIRY` variable must always be a time before the redis session ttl would expire so that behaviours can run before the `SESSION_TIMEOUT` middleware is triggered.
+- Added a `USE_CUSTOM_SESSION_TIMEOUT` that is `false` by default. When set to `true` the '/session-timeout' page can run before the session expires without triggering a `404` middleware error.
+
+   - 🎬 Action:
+      - For custom session timeout handling that is not linked to the redis session ttl, The following variables must be set: `CUSTOM_SESSION_EXPIRY` to the relevant expiry time e.g.600 and `USE_CUSTOM_SESSION_TIMEOUT` to true.
+      - If a behaviour is required on the '/session-timeout` step, the '/session-timeout' step must be set in the project's index.js, along with any relevant behaviours.
 
 ## 2025-10-10, Version 22.10.4 (Stable), @dk4g
 ### Security

package/README.md

@@ -867,7 +867,7 @@ Kubernetes healthcheck URLs are provided as defaults if no overrides are supplie
 |----------|-------------|---------|---------|
 | `SHOW_COOKIES_BANNER` | Controls whether the cookies banner is displayed | Auto-detected based on GA tags | `true`, `false` |
 
-**Behavior:**
+**Behaviour:**
 - If `SHOW_COOKIES_BANNER` is explicitly set, that value is used
 - If not set, banner is automatically shown when `GA_TAG` or `GA_4_TAG` is present
 - If no GA tags are configured, banner is hidden by default
@@ -1328,7 +1328,11 @@ This feature allows you to customise the content related to the session timeout
 
 ### Usage
 
-To enable and customise the session timeout behavior, you need to set the component and translations in your project's `hof.settings.json` file:
+By default, the session timeout is set to the redis session ttl. To bypass this and display the session timeout message before the redis session ttl the following evironment variables must be set:
+`CUSTOM_SESSION_EXPIRY` - e.g. `600`. Configure to expire before thte project's redis session ttl.
+`USE_CUSTOM_SESSION_TIMEOUT` -  `false` by default. When set to `true` the '/session-timeout' page can run before the session expires without triggering a `404` middleware error.
+
+To enable and customise the session timeout behaviour, you need to set the component and translations in your project's `hof.settings.json` file:
 ```json
  "behaviours": [
     "hof/components/session-timeout-warning"
@@ -1348,6 +1352,20 @@ By default, the framework uses the standard content provided by HOF. If you wish
   "saveExitFormContent": true // allows you to customise the content on the save-and-exit page
 ```
 
+To override the default session-timeout page completely, the path to the session-timeout.html should be set in the views property in the hof.settings.json file e.g. 
+```json
+ "behaviours": [
+    "hof/components/session-timeout-warning"
+  ],
+  "translations": "./apps/common/translations",
+   "views": ["./apps/common/views"], // allows you to overide the HOF default session-timeout page and use a custom one from the specified views
+   ...
+```
+or in the project's `server.js` e.g.
+```js
+settings.views = path.resolve(__dirname, './apps/common/views');
+```
+
 ### Customising content in `pages.json`
 Once the variables are set, you can customise the session timeout warning and exit messages in your project's pages.json:
 

package/build/tasks/watch/index.js

@@ -125,6 +125,7 @@ module.exports = config => {
         const rootDir = require('path').resolve(__dirname, '../../../');
         ignored.push(`${rootDir}/frontend/govuk-template/govuk_template_generated.html`);
         watchLocation = [rootDir, '.'];
+        process.env.SESSION_SECRET = require('crypto').randomBytes(16).toString('hex');
       }
 
       const watcher = chokidar.watch(watchLocation, { ignored });

package/components/emailer/emailer.js

@@ -34,17 +34,17 @@ module.exports = class Emailer {
         html: body,
         attachments: [{
           filename: 'govuk_logotype_email.png',
-          path: path.resolve(__dirname, './assets/rebrand/images/govuk_logotype_email.png'),
+          path: path.resolve(__dirname, './assets/images/govuk_logotype_email.png'),
           cid: 'govuk_logotype_email'
         },
         {
           filename: 'ho_crest_27px.png',
-          path: path.resolve(__dirname, './assets/rebrand/images/ho_crest_27px.png'),
+          path: path.resolve(__dirname, './assets/images/ho_crest_27px.png'),
           cid: 'ho_crest_27px'
         },
         {
           filename: 'spacer.gif',
-          path: path.resolve(__dirname, './assets/rebrand/images/spacer.gif'),
+          path: path.resolve(__dirname, './assets/images/spacer.gif'),
           cid: 'spacer_image'
         }]
       }, (err, result) => err ? reject(err) : resolve(result));

package/config/builder-defaults.js

@@ -6,17 +6,17 @@ const toolkitImages =
 
 module.exports = {
   browserify: {
-    src: 'assets/rebrand/js/index.js',
+    src: 'assets/js/index.js',
     out: 'public/js/bundle.js',
-    match: 'assets/rebrand/js/**/*.js',
+    match: 'assets/js/**/*.js',
     restart: false,
     compress: false,
     debug: false
   },
   sass: {
-    src: 'assets/rebrand/scss/app.scss',
+    src: 'assets/scss/app.scss',
     out: 'public/css/app.css',
-    match: 'assets/rebrand/scss/**/*.scss',
+    match: 'assets/scss/**/*.scss',
     restart: false,
     quietDeps: false,
     outputStyle: 'expanded',
@@ -28,9 +28,9 @@ module.exports = {
     shared: 'apps/common/translations/src'
   },
   images: {
-    src: ['assets/rebrand/images', toolkitImages],
+    src: ['assets/rebrand/images', 'assets/images', toolkitImages],
     out: 'public/images',
-    match: ['assets/rebrand/images/**/*', `${toolkitImages}/**/*`],
+    match: 'assets/images/**/*',
     restart: false
   },
   server: {

package/config/hof-defaults.js

@@ -51,7 +51,7 @@ const defaults = {
   },
   session: {
     ttl: process.env.SESSION_TTL || 1800,
-    secret: process.env.SESSION_SECRET || 'changethis',
+    secret: process.env.SESSION_SECRET,
     name: process.env.SESSION_NAME || 'hod.sid',
     sanitiseInputs: false
   },
@@ -59,6 +59,7 @@ const defaults = {
     pdfConverter: process.env.PDF_CONVERTER_URL
   },
   serveStatic: process.env.SERVE_STATIC_FILES !== 'false',
+  useCustomSessionTimeout: parseBoolean(process.env.USE_CUSTOM_SESSION_TIMEOUT, false, 'USE_CUSTOM_SESSION_TIMEOUT'),
   sessionTimeOutWarning: process.env.SESSION_TIMEOUT_WARNING || 300,
   serviceUnavailable: parseBoolean(process.env.SERVICE_UNAVAILABLE, false, 'SERVICE_UNAVAILABLE')
 };

package/frontend/toolkit/index.js

@@ -1,10 +1,10 @@
 module.exports = {
-  helpers: require('./assets/rebrand/javascript/helpers'),
-  formFocus: require('./assets/rebrand/javascript/form-focus'),
-  progressiveReveal: require('./assets/rebrand/javascript/progressive-reveal'),
-  validation: require('./assets/rebrand/javascript/validation'),
+  helpers: require('./assets/javascript/helpers'),
+  formFocus: require('./assets/javascript/form-focus'),
+  progressiveReveal: require('./assets/javascript/progressive-reveal'),
+  validation: require('./assets/javascript/validation'),
   detailsSummary: function () {
-    require('./assets/rebrand/javascript/vendor/details.polyfill');
+    require('./assets/javascript/vendor/details.polyfill');
   },
-  characterCount: require('./assets/rebrand/javascript/character-count')
+  characterCount: require('./assets/javascript/character-count')
 };

package/index.js

@@ -158,7 +158,7 @@ function bootstrap(options) {
     res.locals.htmlLang = config.htmlLang;
     res.locals.cookieName = config.session.name;
     // session timeout warning configs
-    res.locals.sessionTimeOut = config.session.ttl;
+    res.locals.sessionTimeOut = process.env.CUSTOM_SESSION_EXPIRY || config.session.ttl;
     res.locals.sessionTimeOutWarning = config.sessionTimeOutWarning;
     res.locals.sessionTimeoutWarningContent = config.sessionTimeoutWarningContent;
     res.locals.exitFormContent = config.exitFormContent;
@@ -238,8 +238,8 @@ function bootstrap(options) {
     app.use(hofMiddleware.rateLimiter(config, 'requests'));
   }
 
-  // Set up routing so <YOUR-SITE-URL>/assets are served from /node_modules/govuk-frontend/govuk/assets/rebrand
-  app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/govuk/assets/rebrand')));
+  // Set up routing so <YOUR-SITE-URL>/assets are served from /node_modules/govuk-frontend/govuk/assets
+  app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/govuk/assets')));
   // Check if service has been paused and redirect accordingly
   const bypassPaths = ['/assets', '/healthcheck', '/service-unavailable'];
 
@@ -254,26 +254,32 @@ function bootstrap(options) {
 
   /**
    * Handles requests to the session timeout page.
+   * For custom session timeout handling that is not linked to the redis session ttl,
+   * set `CUSTOM_SESSION_EXPIRY` variables to the relevant time and `USE_CUSTOM_SESSION_TIMEOUT`variables to true.
+   * If `CUSTOM_SESSION_EXPIRY` and `USE_CUSTOM_SESSION_TIMEOUT` envs are set,
+   * include '/session-timeout' step in the project's index.js.
    * - If the user has a session cookie but their session is missing or inactive,
    *   this triggers a session timeout error handled by error middleware.
    * - Otherwise, responds with a 404 "Page Not Found" error.
    * This route ensures the timeout page only appears after an actual session expiry.
   */
-  app.get('/session-timeout', (req, res, next) => {
-    if ((req.cookies['hof-wizard-sc']) && (!req.session || req.session.exists !== true)) {
-      const err = new Error('Session expired');
-      err.code = 'SESSION_TIMEOUT';
-      return next(err);
-    }
-    const err = new Error('Not Found');
-    err.status = 404;
-    const locals = Object.assign({}, req.translate('errors'));
-    if (locals && locals['404']) {
-      return res.status(404).render('404', locals['404']);
-    }
-    // Fallback: render a basic 404 page if translation is missing
-    return res.status(404).send('Page Not Found');
-  });
+  if (!config.useCustomSessionTimeout) {
+    app.get('/session-timeout', (req, res, next) => {
+      if ((req.cookies['hof-wizard-sc']) && (!req.session || req.session.exists !== true)) {
+        const err = new Error('Session expired');
+        err.code = 'SESSION_TIMEOUT';
+        return next(err);
+      }
+      const err = new Error('Not Found');
+      err.status = 404;
+      const locals = Object.assign({}, req.translate('errors'));
+      if (locals && locals['404']) {
+        return res.status(404).render('404', locals['404']);
+      }
+      // Fallback: render a basic 404 page if translation is missing
+      return res.status(404).send('Page Not Found');
+    });
+  }
 
   if (config.getAccessibility === true) {
     deprecate(

package/lib/encryption.js

@@ -1,23 +1,49 @@
-/* eslint-disable */ 
 'use strict';
 
-const crypto = require('crypto');
+const crypto = require('node:crypto');
 const algorithm = 'aes-256-cbc';
+const ivLength = 16;
 
-module.exports = password => ({
-
-  encrypt: text => {
-    const cipher = crypto.createCipher(algorithm, password);
-    let crypted = cipher.update(text, 'utf8', 'hex');
-    crypted += cipher.final('hex');
-    return crypted;
-  },
-
-  decrypt: text => {
-    const decipher = crypto.createDecipher(algorithm, password);
-    let dec = decipher.update(text, 'hex', 'utf8');
-    dec += decipher.final('utf8');
-    return dec;
+/**
+ * Creates an encryption utility with AES-256-CBC algorithm.
+ * Provides encrypt and decrypt methods that use a random IV for each encryption operation.
+ *
+ * @module encryption
+ * @param {string|Buffer} secret - Must be exactly 32 bytes
+ * @returns {Object} Encryption utility object
+ * @throws {Error} If secret is not exactly 32 bytes
+ */
+module.exports = secret => {
+  const encryptionKey = Buffer.from(secret, 'utf8');
+  if (encryptionKey.byteLength !== 32) {
+    throw new Error(`Encryption secret must be exactly 32 bytes. Provided: ${encryptionKey.byteLength} bytes.`);
   }
 
-});
+  return {
+    encrypt: text => {
+      try {
+        const iv = crypto.randomBytes(ivLength);
+        const cipher = crypto.createCipheriv(algorithm, encryptionKey, iv);
+        let encrypted = cipher.update(text, 'utf8');
+        encrypted = Buffer.concat([encrypted, cipher.final()]);
+        return iv.toString('hex') + ':' + encrypted.toString('hex');
+      } catch (error) {
+        throw new Error(`Encryption failed: ${error.message}`);
+      }
+    },
+
+    decrypt: text => {
+      try {
+        const textParts = text.split(':');
+        const iv = Buffer.from(textParts.shift(), 'hex');
+        const encryptedText = Buffer.from(textParts.join(':'), 'hex');
+        const decipher = crypto.createDecipheriv(algorithm, encryptionKey, iv);
+        let decrypted = decipher.update(encryptedText);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        return decrypted.toString('utf8');
+      } catch (error) {
+        throw new Error(`Decryption failed: ${error.message}`);
+      }
+    }
+  };
+};

package/lib/sessions.js

@@ -10,8 +10,11 @@ const secureHttps = config => config.protocol === 'https' || config.env === 'pro
 module.exports = (app, config) => {
   const logger = config.logger || console;
 
-  if (config.env === 'production' && config.session.secret === 'changethis') {
-    throw new Error('Session secret must be set to a unique random string for production environments');
+  const secretBuffer = Buffer.from(config.session.secret, 'utf8');
+  if (secretBuffer.byteLength !== 32) {
+    throw new Error(
+      `Session secret must be exactly 32 bytes. Current: ${secretBuffer.byteLength} bytes.`
+    );
   }
 
   app.use(cookieParser(config.session.secret, {

package/lib/settings.js

@@ -42,7 +42,7 @@ module.exports = async (app, config) => {
     viewsArray.slice().reverse().forEach(view => {
       const customViewPath = path.resolve(config.root, view);
       try {
-        fs.accessSync(customViewPath, fs.F_OK);
+        fs.accessSync(customViewPath, fs.constants.F_OK);
       } catch (err) {
         throw new Error(`Cannot find views at ${customViewPath}`);
       }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "hof",
   "description": "A bootstrap for HOF projects",
-  "version": "23.0.0-frontend-v4-beta.13",
+  "version": "23.0.0-frontend-v4-beta.15",
   "license": "MIT",
   "main": "index.js",
   "author": "HomeOffice",
   "engines": {
-    "node": ">=10.22.1",
-    "npm": ">=6.14.0"
+    "node": ">=14.0.0"
   },
   "bin": {
     "hof-build": "./bin/hof-build",

package/sandbox/assets/{rebrand/js → js}/index.js

@@ -1,7 +1,7 @@
 /* eslint-disable */
 'use strict'
 
-require('../../../../frontend/themes/gov-uk/client-js');
+require('../../../frontend/themes/gov-uk/client-js');
 
 var $ = require('jquery');
 var typeahead = require('typeahead-aria');

package/sandbox/assets/{rebrand/scss → scss}/app.scss

@@ -1,5 +1,5 @@
 
-@import "../../../../frontend/themes/gov-uk/styles/govuk";
+@import "../../../frontend/themes/gov-uk/styles/govuk";
 
 //autocomplete styling
 .tt-menu {

package/sandbox/package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "start:dev": "HOF_SANDBOX=true ../bin/hof-build watch --env",
+    "start:dev": "HOF_SANDBOX=true ../bin/hof-build watch",
     "dev": "yarn && GA_TAG=test nodemon server",
     "build": "HOF_SANDBOX=true ../bin/hof-build",
     "postinstall": "yarn run build"

package/sandbox/public/js/bundle.js

@@ -1403,17 +1403,17 @@ module.exports = validation;
 
 },{}],12:[function(require,module,exports){
 module.exports = {
-  helpers: require('./assets/rebrand/javascript/helpers'),
-  formFocus: require('./assets/rebrand/javascript/form-focus'),
-  progressiveReveal: require('./assets/rebrand/javascript/progressive-reveal'),
-  validation: require('./assets/rebrand/javascript/validation'),
+  helpers: require('./assets/javascript/helpers'),
+  formFocus: require('./assets/javascript/form-focus'),
+  progressiveReveal: require('./assets/javascript/progressive-reveal'),
+  validation: require('./assets/javascript/validation'),
   detailsSummary: function () {
-    require('./assets/rebrand/javascript/vendor/details.polyfill');
+    require('./assets/javascript/vendor/details.polyfill');
   },
-  characterCount: require('./assets/rebrand/javascript/character-count')
+  characterCount: require('./assets/javascript/character-count')
 };
 
-},{"./assets/rebrand/javascript/character-count":6,"./assets/rebrand/javascript/form-focus":7,"./assets/rebrand/javascript/helpers":8,"./assets/rebrand/javascript/progressive-reveal":9,"./assets/rebrand/javascript/validation":10,"./assets/rebrand/javascript/vendor/details.polyfill":11}],13:[function(require,module,exports){
+},{"./assets/javascript/character-count":6,"./assets/javascript/form-focus":7,"./assets/javascript/helpers":8,"./assets/javascript/progressive-reveal":9,"./assets/javascript/validation":10,"./assets/javascript/vendor/details.polyfill":11}],13:[function(require,module,exports){
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
   typeof define === 'function' && define.amd ? define(factory) :
@@ -35627,7 +35627,7 @@ exports.clearImmediate = typeof clearImmediate === "function" ? clearImmediate :
 /* eslint-disable */
 'use strict'
 
-require('../../../../frontend/themes/gov-uk/client-js');
+require('../../../frontend/themes/gov-uk/client-js');
 
 var $ = require('jquery');
 var typeahead = require('typeahead-aria');
@@ -35695,7 +35695,7 @@ $('.typeahead').each(function applyTypeahead() {
   });
 });
 
-},{"../../../../frontend/themes/gov-uk/client-js":3,"jquery":20,"typeahead-aria":23}],20:[function(require,module,exports){
+},{"../../../frontend/themes/gov-uk/client-js":3,"jquery":20,"typeahead-aria":23}],20:[function(require,module,exports){
 arguments[4][15][0].apply(exports,arguments)
 },{"dup":15}],21:[function(require,module,exports){
 /*!