hof 22.10.5-fix-error-page-journey-header-bug-beta.1 → 22.11.0-custom-session-timeout-beta.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 2025-11-11, Version 22.11.0 , @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 a time before the redis session ttl would expire so that behaviours can run before the `SESSION_TIMEOUT` middleware is triggered.
+- Added a `CUSTOM_SESSION_TIMEOUT` that is `false` by default. When set to `true` the 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 `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
 - Upgraded axios version to address a security vulnerability

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`. Configured to expire before thte project's redis session ttl.
+`CUSTOM_SESSION_TIMEOUT` -  `False` by default. When set to `true` the 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/config/hof-defaults.js

@@ -59,6 +59,7 @@ const defaults = {
     pdfConverter: process.env.PDF_CONVERTER_URL
   },
   serveStatic: process.env.SERVE_STATIC_FILES !== 'false',
+  customSessionTimeout: parseBoolean(process.env.CUSTOM_SESSION_TIMEOUT, false, 'CUSTOM_SESSION_TIMEOUT'),
   sessionTimeOutWarning: process.env.SESSION_TIMEOUT_WARNING || 300,
   serviceUnavailable: parseBoolean(process.env.SERVICE_UNAVAILABLE, false, 'SERVICE_UNAVAILABLE')
 };

package/frontend/template-partials/views/error.html

@@ -1,6 +1,6 @@
 {{<layout}}
   {{$journeyHeader}}
-    {{#serviceName}}{{serviceName}}{{/serviceName}}
+    {{#t}}journey.header{{/t}}
   {{/journeyHeader}}
   {{$propositionHeader}}
     {{> partials-navigation}}

package/index.js

@@ -156,7 +156,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;
@@ -252,26 +252,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 `CUSTOM_SESSION_TIMEOUT`variables to true.
+   * If `CUSTOM_SESSION_EXPIRY` and `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.customSessionTimeout) {
+    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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hof",
   "description": "A bootstrap for HOF projects",
-  "version": "22.10.5-fix-error-page-journey-header-bug-beta.1",
+  "version": "22.11.0-custom-session-timeout-beta.1",
   "license": "MIT",
   "main": "index.js",
   "author": "HomeOffice",

package/sandbox/apps/sandbox/behaviours/test-console-log.js

@@ -0,0 +1,9 @@
+'use strict';
+
+module.exports = SuperClass => class extends SuperClass {
+  configure(req, res, next) {
+    // Simple behaviour to log to console when run
+    console.log('***************** console log behaviour executed************************');
+    return super.configure(req, res, next);
+  }
+};

package/sandbox/apps/sandbox/index.js

@@ -4,6 +4,7 @@
 const CountrySelect = require('./behaviours/country-select')
 const SummaryPageBehaviour = require('../../../').components.summary;
 const InternationalPhoneNumber = require('./behaviours/international-number');
+const TestConsoleLog = require('./behaviours/test-console-log');
 
 module.exports = {
   name: 'sandbox',
@@ -92,6 +93,9 @@ module.exports = {
       ],
       next: '/confirm'
     },
+    '/session-timeout': {
+      behaviours: TestConsoleLog
+    },
     '/exit': {},
     '/save-and-exit': {}
   }

package/sandbox/apps/sandbox/translations/en/default.json

@@ -2,6 +2,10 @@
   "errors": {
     "service-unavailable": {
       "contact": "You can email for more information"
+    },
+    "session": {
+      "title": "Custom title translation - Your session has timed out",
+      "message": "Custom message translation -  For your security, we have timed you out due to inactivity."
     }
   },
   "exit": {

package/sandbox/apps/sandbox/translations/src/en/errors.json

@@ -1,5 +1,9 @@
 {
   "service-unavailable": {
     "contact": "You can email for more information"
+  },
+  "session": {
+    "title": "Custom title translation - Your session has timed out",
+    "message": "Custom message translation -  For your security, we have timed you out due to inactivity."
   }
 }

package/sandbox/apps/sandbox/views/session-timeout.html

@@ -0,0 +1,7 @@
+{{<error}}
+  {{$content}}
+    <h1 class="govuk-heading-l">{{#t}}errors.session.title{{/t}}</h1>
+    <h2 class="govuk-heading-m">{{#t}}errors.session.message{{/t}}</h2>
+    <a href="/" class="govuk-button" role="button">{{#t}}buttons.start-again{{/t}}</a>
+  {{/content}}
+{{/error}}

package/sandbox/package.json

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