@defra/lis-infra-ui-services 0.21.0 → 0.22.0

package/README.md

@@ -3,3 +3,59 @@
 This package contains the shared topology metadata and route helpers used across the hub, spokes, and services.
 
 Install dependencies for this package locally with `npm install` from this directory.
+
+## Error pages
+
+`catchAll` from `@defra/lis-infra-ui-services/errors`, registered as an `onPreResponse` extension, renders one of four shared pages from `src/nunjucks/routes/error/` by status code:
+
+| Status        | Page                   |
+| ------------- | ---------------------- |
+| 404           | `page-not-found`       |
+| 401, 403      | `not-authorised`       |
+| 503           | `service-unavailable`  |
+| anything else | `problem-with-service` |
+
+The links on these pages come from the `errorPages` option of `createNunjucksConfig` (or `createNunjucksContextBuilder`), exposed to templates as `errorPages`. Every key is optional:
+
+```js
+createNunjucksConfig({
+  config,
+  logger,
+  getRequestBasePath,
+  errorPages: {
+    contactHref:
+      'https://www.gov.uk/government/organisations/british-cattle-movement-service', // default
+    homeHref: '/', // default, "Home page" on page not found
+    getStartedHref: '/' // default, "Get started" on page not found
+  }
+})
+```
+
+## Scheduled maintenance
+
+Each hub switches maintenance on with its own config value, `maintenance.availableFrom`: the UK local date-time the service is back, in ISO 8601 form without an offset, e.g. `2026-11-19T09:00` or `2026-11-19T09:00:00`. Values with a `Z` or `+hh:mm` offset, and dates without a time, throw at start-up. An empty value leaves the service running as normal.
+
+```js
+// config.js
+maintenance: {
+  availableFrom: {
+    doc: 'UK local date-time the service is back from, without an offset; empty when not in maintenance',
+    format: String,
+    default: '',
+    env: 'MAINTENANCE_AVAILABLE_FROM'
+  }
+}
+
+// server.js, after @hapi/vision is registered
+import { createMaintenancePlugin } from '@defra/lis-infra-ui-services/maintenance'
+
+await server.register(
+  createMaintenancePlugin({
+    availableFrom: config.get('maintenance.availableFrom'),
+    healthPath: '/health', // default
+    assetPath: config.get('assetPath') // default '/public'
+  })
+)
+```
+
+While `availableFrom` is set, every request except the health check and assets under `assetPath` gets the service unavailable page with a 503, showing the time as "9am on Thursday 19 November 2026" and carrying it in a `Retry-After` header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {
@@ -18,6 +18,7 @@
     "./components/sub-navigation.scss": "./src/components/sub-navigation.scss",
     "./duration": "./src/duration.js",
     "./errors": "./src/errors/index.js",
+    "./maintenance": "./src/maintenance.js",
     "./navigation": "./src/navigation.js",
     "./nunjucks/build-navigation": "./src/nunjucks/build-navigation.js",
     "./nunjucks/context": "./src/nunjucks/context.js",
@@ -77,6 +78,7 @@
     "@defra/lis-hubs-infra-access": "^0.29.0",
     "@defra/lis-hubs-infra-core": "^0.12.0",
     "@defra/lis-infra-eslint-config": "^0.6.0",
+    "@hapi/hapi": "^21.4.10",
     "@vitest/coverage-istanbul": "^4.1.10",
     "audit-ci": "^7.1.0",
     "eslint": "^9.0.0",

package/src/errors/error-pages.js

@@ -0,0 +1,19 @@
+export const pageNotFound = {
+  view: 'error/page-not-found',
+  pageTitle: 'Page not found'
+}
+
+export const notAuthorised = {
+  view: 'error/not-authorised',
+  pageTitle: 'Sorry, you are not authorised to view this page'
+}
+
+export const serviceUnavailable = {
+  view: 'error/service-unavailable',
+  pageTitle: 'Sorry, the service is unavailable'
+}
+
+export const problemWithService = {
+  view: 'error/problem-with-service',
+  pageTitle: 'Sorry, there is a problem with the service'
+}

package/src/errors/index.js

@@ -1,20 +1,26 @@
 /** @import { Request, ResponseToolkit, Lifecycle } from '@hapi/hapi' */
 import { logger } from '@defra/lis-hubs-infra-core'
 
+import { isAnsweredByMaintenance } from '../maintenance.js'
+import {
+  notAuthorised,
+  pageNotFound,
+  problemWithService,
+  serviceUnavailable
+} from './error-pages.js'
 import { statusCodes } from '../status-codes.js'
 
-function statusCodeMessage(statusCode) {
+function errorPageFor(statusCode) {
   switch (statusCode) {
     case statusCodes.notFound:
-      return 'Page not found'
-    case statusCodes.forbidden:
-      return 'Forbidden'
+      return pageNotFound
     case statusCodes.unauthorized:
-      return 'Unauthorized'
-    case statusCodes.badRequest:
-      return 'Bad Request'
+    case statusCodes.forbidden:
+      return notAuthorised
+    case statusCodes.serviceUnavailable:
+      return serviceUnavailable
     default:
-      return 'Something went wrong'
+      return problemWithService
   }
 }
 
@@ -41,25 +47,21 @@ export function catchAll(request, h) {
   const { response } = request
   const statusCode = getStatusCode(response)
 
-  if (statusCode >= statusCodes.internalServerError) {
+  if (
+    statusCode >= statusCodes.internalServerError &&
+    !isAnsweredByMaintenance(request)
+  ) {
     logger.error(getLogMessage(response, statusCode))
   }
 
   if (!('isBoom' in response)) {
     return h.continue
   }
-  const genericMessage = statusCodeMessage(statusCode)
-  const detailedMessage =
-    response?.message ?? response?.source?.message ?? genericMessage
-
-  const message =
-    process.env.NODE_ENV === 'development' ? detailedMessage : genericMessage
+  const { view, pageTitle } = errorPageFor(statusCode)
+  const developmentMessage =
+    process.env.NODE_ENV === 'development'
+      ? (response?.message ?? response?.source?.message)
+      : undefined
 
-  return h
-    .view('error/index', {
-      pageTitle: genericMessage,
-      heading: statusCode,
-      message
-    })
-    .code(statusCode)
+  return h.view(view, { pageTitle, developmentMessage }).code(statusCode)
 }

package/src/errors/index.test.js

@@ -35,46 +35,76 @@ function createBoomRequest(statusCode) {
 
 afterEach(() => {
   vi.clearAllMocks()
+  vi.unstubAllEnvs()
 })
 
 test('catchAll continues when the response is not Boom', () => {
+  // Arrange
   const toolkit = createToolkit()
+
+  // Act
   const result = catchAll({ response: {} }, toolkit)
 
+  // Assert
   assert.equal(result, toolkit.continue)
   assert.equal(toolkit.view.mock.calls.length, 0)
 })
 
-test('catchAll renders the expected not found page', () => {
-  const request = createBoomRequest(statusCodes.notFound)
-  const toolkit = createToolkit()
-
-  catchAll(request, toolkit)
-
-  assert.deepEqual(toolkit.view.mock.calls[0], [
-    'error/index',
-    {
-      pageTitle: 'Page not found',
-      heading: statusCodes.notFound,
-      message: 'Page not found'
-    }
-  ])
-  assert.deepEqual(toolkit.code.mock.calls[0], [statusCodes.notFound])
-  assert.equal(logger.error.mock.calls.length, 0)
-})
+test.each([
+  [statusCodes.notFound, 'error/page-not-found', 'Page not found'],
+  [
+    statusCodes.unauthorized,
+    'error/not-authorised',
+    'Sorry, you are not authorised to view this page'
+  ],
+  [
+    statusCodes.forbidden,
+    'error/not-authorised',
+    'Sorry, you are not authorised to view this page'
+  ],
+  [
+    statusCodes.badRequest,
+    'error/problem-with-service',
+    'Sorry, there is a problem with the service'
+  ],
+  [
+    statusCodes.serviceUnavailable,
+    'error/service-unavailable',
+    'Sorry, the service is unavailable'
+  ]
+])(
+  'catchAll renders a %i as the %s page titled "%s"',
+  (statusCode, view, pageTitle) => {
+    // Arrange
+    const request = createBoomRequest(statusCode)
+    const toolkit = createToolkit()
+
+    // Act
+    catchAll(request, toolkit)
+
+    // Assert
+    assert.deepEqual(toolkit.view.mock.calls[0], [
+      view,
+      { pageTitle, developmentMessage: undefined }
+    ])
+    assert.deepEqual(toolkit.code.mock.calls[0], [statusCode])
+  }
+)
 
-test('catchAll logs and renders generic content for server errors', () => {
+test('catchAll logs server errors and renders the problem with the service page', () => {
+  // Arrange
   const request = createBoomRequest(statusCodes.internalServerError)
   const toolkit = createToolkit()
 
+  // Act
   catchAll(request, toolkit)
 
+  // Assert
   assert.deepEqual(toolkit.view.mock.calls[0], [
-    'error/index',
+    'error/problem-with-service',
     {
-      pageTitle: 'Something went wrong',
-      heading: statusCodes.internalServerError,
-      message: 'Something went wrong'
+      pageTitle: 'Sorry, there is a problem with the service',
+      developmentMessage: undefined
     }
   ])
   assert.deepEqual(toolkit.code.mock.calls[0], [
@@ -83,7 +113,20 @@ test('catchAll logs and renders generic content for server errors', () => {
   assert.deepEqual(logger.error.mock.calls[0], ['Mock error stack'])
 })
 
+test('catchAll does not log client errors', () => {
+  // Arrange
+  const request = createBoomRequest(statusCodes.notFound)
+  const toolkit = createToolkit()
+
+  // Act
+  catchAll(request, toolkit)
+
+  // Assert
+  assert.equal(logger.error.mock.calls.length, 0)
+})
+
 test('catchAll prefers a client-attached statusCode over a boomified 500', () => {
+  // Arrange
   const request = {
     response: {
       isBoom: true,
@@ -94,21 +137,67 @@ test('catchAll prefers a client-attached statusCode over a boomified 500', () =>
   }
   const toolkit = createToolkit()
 
+  // Act
   catchAll(request, toolkit)
 
+  // Assert
   assert.deepEqual(toolkit.view.mock.calls[0], [
-    'error/index',
-    {
-      pageTitle: 'Page not found',
-      heading: statusCodes.notFound,
-      message: 'Page not found'
-    }
+    'error/page-not-found',
+    { pageTitle: 'Page not found', developmentMessage: undefined }
   ])
   assert.deepEqual(toolkit.code.mock.calls[0], [statusCodes.notFound])
   assert.equal(logger.error.mock.calls.length, 0)
 })
 
+test("catchAll passes the error's own message to the page in development", () => {
+  // Arrange
+  vi.stubEnv('NODE_ENV', 'development')
+  const request = createBoomRequest(statusCodes.internalServerError)
+  request.response.message = 'Upstream timed out'
+  const toolkit = createToolkit()
+
+  // Act
+  catchAll(request, toolkit)
+
+  // Assert
+  assert.equal(
+    toolkit.view.mock.calls[0][1].developmentMessage,
+    'Upstream timed out'
+  )
+})
+
+test("catchAll leaves out the error's own message outside development", () => {
+  // Arrange
+  vi.stubEnv('NODE_ENV', 'production')
+  const request = createBoomRequest(statusCodes.internalServerError)
+  request.response.message = 'Upstream timed out'
+  const toolkit = createToolkit()
+
+  // Act
+  catchAll(request, toolkit)
+
+  // Assert
+  assert.equal(toolkit.view.mock.calls[0][1].developmentMessage, undefined)
+})
+
+test('catchAll does not log the 503 the maintenance plugin answered with', () => {
+  // Arrange
+  const toolkit = createToolkit()
+  const request = {
+    plugins: { 'lis-maintenance': { answered: true } },
+    response: { statusCode: statusCodes.serviceUnavailable, source: {} }
+  }
+
+  // Act
+  const result = catchAll(request, toolkit)
+
+  // Assert
+  assert.equal(result, toolkit.continue)
+  assert.equal(logger.error.mock.calls.length, 0)
+})
+
 test('catchAll logs plain 500 responses before continuing', () => {
+  // Arrange
   const toolkit = createToolkit()
   const request = {
     response: {
@@ -119,8 +208,10 @@ test('catchAll logs plain 500 responses before continuing', () => {
     }
   }
 
+  // Act
   const result = catchAll(request, toolkit)
 
+  // Assert
   assert.equal(result, toolkit.continue)
   assert.deepEqual(logger.error.mock.calls[0], ['Plain 500 response'])
   assert.equal(toolkit.view.mock.calls.length, 0)

package/src/maintenance.js

@@ -0,0 +1,131 @@
+/** @import { Plugin, Request } from '@hapi/hapi' */
+import { format, isValid, parseISO } from 'date-fns'
+
+import { serviceUnavailable } from './errors/error-pages.js'
+import { statusCodes } from './status-codes.js'
+
+const PLUGIN_NAME = 'lis-maintenance'
+const MIDDAY_HOUR = 12
+const LOCAL_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/
+
+function formatTime(date) {
+  if (date.getMinutes() === 0) {
+    if (date.getHours() === 0) {
+      return 'midnight'
+    }
+    if (date.getHours() === MIDDAY_HOUR) {
+      return 'midday'
+    }
+    return format(date, 'haaa')
+  }
+
+  return format(date, 'h:mmaaa')
+}
+
+/**
+ * Only a local date-time is accepted: it is read as wall-clock time, so the
+ * page shows what was configured whatever the server's time zone, whereas an
+ * offset would be converted to the server's zone.
+ * @param {string} isoString
+ * @returns {Date}
+ */
+function parseAvailableFrom(isoString) {
+  const date = LOCAL_DATE_TIME.test(isoString) ? parseISO(isoString) : null
+
+  if (!date || !isValid(date)) {
+    throw new Error(
+      `maintenance.availableFrom must be the UK local date-time without an offset, e.g. 2026-11-19T09:00, got "${isoString}"`
+    )
+  }
+
+  return date
+}
+
+/**
+ * Formats a return time in the GOV.UK style, e.g. "9am on Monday 19 November
+ * 2026".
+ * @param {string} isoString - a local date-time without an offset
+ * @returns {string}
+ */
+export function formatAvailableFrom(isoString) {
+  const date = parseAvailableFrom(isoString)
+
+  return `${formatTime(date)} on ${format(date, 'EEEE d MMMM yyyy')}`
+}
+
+/**
+ * Whether the maintenance plugin answered this request, so the error handler
+ * does not log every refused request as a server error.
+ * @param {Request} request
+ * @returns {boolean}
+ */
+export function isAnsweredByMaintenance(request) {
+  return request?.plugins?.[PLUGIN_NAME]?.answered === true
+}
+
+function withoutTrailingSlashes(path) {
+  let trimmed = path
+
+  while (trimmed.endsWith('/')) {
+    trimmed = trimmed.slice(0, -1)
+  }
+
+  return trimmed
+}
+
+function isExempt(path, { healthPath, assetPrefix }) {
+  return path === healthPath || path.startsWith(assetPrefix)
+}
+
+function answerUnavailable(request, h, { availableFrom, retryAfter }) {
+  request.plugins[PLUGIN_NAME] = { answered: true }
+
+  return h
+    .view(serviceUnavailable.view, {
+      pageTitle: serviceUnavailable.pageTitle,
+      availableFrom
+    })
+    .code(statusCodes.serviceUnavailable)
+    .header('Retry-After', retryAfter)
+    .takeover()
+}
+
+/**
+ * Answers every request with the service unavailable page while
+ * `availableFrom` is set. The health check stays up so the platform does not
+ * restart the service, and assets stay up so the page is styled.
+ * @param {{ availableFrom?: string, healthPath?: string, assetPath?: string }} options
+ * @returns {Plugin<void>}
+ */
+export function createMaintenancePlugin({
+  availableFrom,
+  healthPath = '/health',
+  assetPath = '/public'
+} = {}) {
+  const isActive = typeof availableFrom === 'string' && availableFrom !== ''
+  const formattedAvailableFrom = isActive
+    ? formatAvailableFrom(availableFrom)
+    : undefined
+  const retryAfter = isActive
+    ? parseAvailableFrom(availableFrom).toUTCString()
+    : undefined
+  const assetPrefix = `${withoutTrailingSlashes(assetPath)}/`
+
+  return {
+    name: PLUGIN_NAME,
+    register(server) {
+      if (!isActive) {
+        return
+      }
+
+      server.ext('onRequest', (request, h) =>
+        isExempt(request.path, { healthPath, assetPrefix })
+          ? h.continue
+          : answerUnavailable(request, h, {
+              availableFrom: formattedAvailableFrom,
+              retryAfter
+            })
+      )
+    }
+  }
+}

package/src/maintenance.test.js

@@ -0,0 +1,260 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import hapi from '@hapi/hapi'
+import hapiVision from '@hapi/vision'
+import nunjucks from 'nunjucks'
+import { afterEach, describe, expect, test } from 'vitest'
+
+import {
+  createMaintenancePlugin,
+  formatAvailableFrom,
+  isAnsweredByMaintenance
+} from './maintenance.js'
+import { statusCodes } from './status-codes.js'
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..'
+)
+const environment = new nunjucks.Environment(
+  new nunjucks.FileSystemLoader([
+    path.join(packageRoot, 'src/nunjucks/routes'),
+    path.join(packageRoot, 'test/fixtures/nunjucks')
+  ]),
+  { autoescape: true }
+)
+
+let server
+
+async function createServer(maintenanceOptions) {
+  server = hapi.server()
+  await server.register({
+    plugin: hapiVision,
+    options: {
+      engines: {
+        njk: {
+          compile(src) {
+            const template = nunjucks.compile(src, environment)
+            return (context) => template.render(context)
+          }
+        }
+      },
+      path: path.join(packageRoot, 'src/nunjucks/routes'),
+      context: {
+        errorPages: { contactHref: 'https://example.com/contact' }
+      }
+    }
+  })
+  await server.register(createMaintenancePlugin(maintenanceOptions))
+  server.route([
+    { method: 'GET', path: '/health', handler: () => ({ message: 'success' }) },
+    { method: 'GET', path: '/holdings', handler: () => 'Holdings' },
+    { method: 'GET', path: '/public/app.css', handler: () => 'body {}' }
+  ])
+  await server.initialize()
+
+  return server
+}
+
+afterEach(async () => {
+  await server?.stop()
+  server = undefined
+})
+
+describe('formatAvailableFrom()', () => {
+  test.each([
+    ['2026-11-19T09:00', '9am on Thursday 19 November 2026'],
+    ['2026-11-16T09:30', '9:30am on Monday 16 November 2026'],
+    ['2026-11-16T17:05:00', '5:05pm on Monday 16 November 2026'],
+    ['2026-11-16T12:00', 'midday on Monday 16 November 2026'],
+    ['2026-11-16T00:00', 'midnight on Monday 16 November 2026']
+  ])('formats %s as "%s"', (isoString, expected) => {
+    // Arrange
+    // Act
+    const formatted = formatAvailableFrom(isoString)
+
+    // Assert
+    expect(formatted).toBe(expected)
+  })
+
+  test('throws on a value that is not an ISO 8601 date-time', () => {
+    // Arrange
+    const isoString = 'next Tuesday'
+
+    // Act
+    const act = () => formatAvailableFrom(isoString)
+
+    // Assert
+    expect(act).toThrow(
+      'maintenance.availableFrom must be the UK local date-time without an offset, e.g. 2026-11-19T09:00, got "next Tuesday"'
+    )
+  })
+
+  test.each([['2026-11-19T09:00Z'], ['2026-11-19T09:00:00+01:00']])(
+    'throws on %s because it carries an offset',
+    (isoString) => {
+      // Arrange
+      // Act
+      const act = () => formatAvailableFrom(isoString)
+
+      // Assert
+      expect(act).toThrow('without an offset')
+    }
+  )
+
+  test('throws on a date without a time', () => {
+    // Arrange
+    const isoString = '2026-11-19'
+
+    // Act
+    const act = () => formatAvailableFrom(isoString)
+
+    // Assert
+    expect(act).toThrow('without an offset')
+  })
+
+  test('throws on a date-time that does not exist', () => {
+    // Arrange
+    const isoString = '2026-13-40T09:00'
+
+    // Act
+    const act = () => formatAvailableFrom(isoString)
+
+    // Assert
+    expect(act).toThrow('without an offset')
+  })
+})
+
+describe('createMaintenancePlugin()', () => {
+  test('answers a page request with the service unavailable page and a 503', async () => {
+    // Arrange
+    await createServer({ availableFrom: '2026-11-16T09:00' })
+
+    // Act
+    const response = await server.inject({ method: 'GET', url: '/holdings' })
+
+    // Assert
+    expect(response.statusCode).toBe(statusCodes.serviceUnavailable)
+    expect(response.payload).toContain(
+      '<title>Sorry, the service is unavailable - Livestock Information</title>'
+    )
+    expect(response.payload).toContain(
+      'You will be able to use the service from 9am on Monday 16 November 2026.'
+    )
+    expect(isAnsweredByMaintenance(response.request)).toBe(true)
+  })
+
+  test('tells clients when to retry with a Retry-After HTTP-date', async () => {
+    // Arrange
+    await createServer({ availableFrom: '2026-11-16T09:00' })
+
+    // Act
+    const response = await server.inject({ method: 'GET', url: '/holdings' })
+
+    // Assert
+    expect(response.headers['retry-after']).toBe(
+      new Date(2026, 10, 16, 9, 0).toUTCString()
+    )
+  })
+
+  test('leaves the health check untouched', async () => {
+    // Arrange
+    await createServer({ availableFrom: '2026-11-16T09:00' })
+
+    // Act
+    const response = await server.inject({ method: 'GET', url: '/health' })
+
+    // Assert
+    expect(response.statusCode).toBe(statusCodes.ok)
+    expect(response.result).toEqual({ message: 'success' })
+    expect(isAnsweredByMaintenance(response.request)).toBe(false)
+  })
+
+  test('honours a custom health path', async () => {
+    // Arrange
+    await createServer({
+      availableFrom: '2026-11-16T09:00',
+      healthPath: '/holdings'
+    })
+
+    // Act
+    const response = await server.inject({ method: 'GET', url: '/holdings' })
+
+    // Assert
+    expect(response.statusCode).toBe(statusCodes.ok)
+  })
+
+  test('leaves static assets untouched so the page is styled', async () => {
+    // Arrange
+    await createServer({ availableFrom: '2026-11-16T09:00' })
+
+    // Act
+    const response = await server.inject({
+      method: 'GET',
+      url: '/public/app.css'
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(statusCodes.ok)
+  })
+
+  test('treats an asset path with a trailing slash the same as one without', async () => {
+    // Arrange
+    await createServer({
+      availableFrom: '2026-11-16T09:00',
+      assetPath: '/public/'
+    })
+
+    // Act
+    const assetResponse = await server.inject({
+      method: 'GET',
+      url: '/public/app.css'
+    })
+    const pageResponse = await server.inject({
+      method: 'GET',
+      url: '/holdings'
+    })
+
+    // Assert
+    expect(assetResponse.statusCode).toBe(statusCodes.ok)
+    expect(pageResponse.statusCode).toBe(statusCodes.serviceUnavailable)
+  })
+
+  test.each([[''], [undefined]])(
+    'does nothing when availableFrom is %j',
+    async (availableFrom) => {
+      // Arrange
+      await createServer({ availableFrom })
+
+      // Act
+      const response = await server.inject({ method: 'GET', url: '/holdings' })
+
+      // Assert
+      expect(response.statusCode).toBe(statusCodes.ok)
+      expect(response.payload).toBe('Holdings')
+    }
+  )
+
+  test('fails at start-up when availableFrom has an offset', () => {
+    // Arrange
+    const options = { availableFrom: '2026-11-16T09:00Z' }
+
+    // Act
+    const act = () => createMaintenancePlugin(options)
+
+    // Assert
+    expect(act).toThrow('without an offset')
+  })
+
+  test('fails at start-up when availableFrom is not a date-time', () => {
+    // Arrange
+    const options = { availableFrom: 'soon' }
+
+    // Act
+    const act = () => createMaintenancePlugin(options)
+
+    // Assert
+    expect(act).toThrow('maintenance.availableFrom must be the UK local')
+  })
+})

package/src/nunjucks/context.js

@@ -5,6 +5,9 @@ import { HUBS, getModuleById } from '@defra/lis-hubs-infra-registry'
 
 const HUB_SERVICE_NAME_PREFIX = 'lis-hubs-'
 
+export const BCMS_CONTACT_HREF =
+  'https://www.gov.uk/government/organisations/british-cattle-movement-service'
+
 /**
  * Both auth schemes put the hub's service name on credentials.caller - a
  * spoke gets the hub that called it, a hub gets itself - so it is only
@@ -47,7 +50,14 @@ function createPermissionCheck(request) {
 }
 
 /**
- * @param {{ config: object, buildNavigation: Function, getRequestBasePath: Function, logger: object, readFileSync: Function, moduleId?: string }} options
+ * @typedef {object} ErrorPageLinks
+ * @property {string} [contactHref] - every error page's contact link; defaults to the BCMS GOV.UK page
+ * @property {string} [homeHref] - the page not found "Home page" link; defaults to '/'
+ * @property {string} [getStartedHref] - the page not found "Get started" link; defaults to '/'
+ */
+
+/**
+ * @param {{ config: object, buildNavigation: Function, getRequestBasePath: Function, logger: object, readFileSync: Function, moduleId?: string, errorPages?: ErrorPageLinks }} options
  * @returns {Function}
  */
 export function createNunjucksContextBuilder({
@@ -56,8 +66,14 @@ export function createNunjucksContextBuilder({
   getRequestBasePath,
   logger,
   readFileSync,
-  moduleId
+  moduleId,
+  errorPages = {}
 }) {
+  const errorPageLinks = {
+    contactHref: errorPages.contactHref ?? BCMS_CONTACT_HREF,
+    homeHref: errorPages.homeHref ?? '/',
+    getStartedHref: errorPages.getStartedHref ?? '/'
+  }
   const sectionName = moduleId ? (getModuleById(moduleId)?.label ?? null) : null
   const manifestPath = path.join(
     config.get('root'),
@@ -96,6 +112,7 @@ export function createNunjucksContextBuilder({
       isBackOffice: requestHubId === 'back-office',
       hasPermission: createPermissionCheck(request),
       logoutUrl: '/signout',
+      errorPages: errorPageLinks,
       getAssetPath(asset) {
         const viteAssetPath = viteManifest?.[asset]?.file
         return `${assetRoot}/${viteAssetPath ?? asset}`

package/src/nunjucks/context.test.js

@@ -302,6 +302,82 @@ describe('createNunjucksContextBuilder() hub flags', () => {
   })
 })
 
+describe('createNunjucksContextBuilder() errorPages', () => {
+  test('defaults the contact link to the BCMS GOV.UK page and the other links to the root', () => {
+    // Arrange
+    const contextBuilder = createNunjucksContextBuilder({
+      config: createConfig(),
+      buildNavigation: () => [],
+      getRequestBasePath: () => '',
+      logger: {},
+      readFileSync: () => '{}'
+    })
+    const request = { headers: {}, path: '/', auth: { credentials: null } }
+
+    // Act
+    const context = contextBuilder(request)
+
+    // Assert
+    expect(context.errorPages).toEqual({
+      contactHref:
+        'https://www.gov.uk/government/organisations/british-cattle-movement-service',
+      homeHref: '/',
+      getStartedHref: '/'
+    })
+  })
+
+  test('uses the links given in the errorPages option', () => {
+    // Arrange
+    const contextBuilder = createNunjucksContextBuilder({
+      config: createConfig(),
+      buildNavigation: () => [],
+      getRequestBasePath: () => '',
+      logger: {},
+      readFileSync: () => '{}',
+      errorPages: {
+        contactHref: 'https://example.com/contact',
+        homeHref: '/home',
+        getStartedHref: '/start'
+      }
+    })
+    const request = { headers: {}, path: '/', auth: { credentials: null } }
+
+    // Act
+    const context = contextBuilder(request)
+
+    // Assert
+    expect(context.errorPages).toEqual({
+      contactHref: 'https://example.com/contact',
+      homeHref: '/home',
+      getStartedHref: '/start'
+    })
+  })
+
+  test('keeps the default for any link the errorPages option leaves out', () => {
+    // Arrange
+    const contextBuilder = createNunjucksContextBuilder({
+      config: createConfig(),
+      buildNavigation: () => [],
+      getRequestBasePath: () => '',
+      logger: {},
+      readFileSync: () => '{}',
+      errorPages: { getStartedHref: '/start', homeHref: undefined }
+    })
+    const request = { headers: {}, path: '/', auth: { credentials: null } }
+
+    // Act
+    const context = contextBuilder(request)
+
+    // Assert
+    expect(context.errorPages).toEqual({
+      contactHref:
+        'https://www.gov.uk/government/organisations/british-cattle-movement-service',
+      homeHref: '/',
+      getStartedHref: '/start'
+    })
+  })
+})
+
 describe('createNunjucksContextBuilder() hasPermission()', () => {
   test('grants a permission the user holds on the given cph', () => {
     // Arrange

package/src/nunjucks/plugin.js

@@ -157,14 +157,16 @@ function buildNunjucksEnvironment({
 }
 
 /**
- * @param {{ config: object, logger: object, getRequestBasePath: Function, moduleId?: string }} options
+ * @import { ErrorPageLinks } from './context.js'
+ * @param {{ config: object, logger: object, getRequestBasePath: Function, moduleId?: string, errorPages?: ErrorPageLinks }} options
  * @returns {object}
  */
 export function createNunjucksConfig({
   config,
   logger,
   getRequestBasePath,
-  moduleId
+  moduleId,
+  errorPages
 }) {
   const basePath = moduleId ? getBasePathForModule(moduleId) : ''
   const projectRoot = config.get('root')
@@ -195,7 +197,8 @@ export function createNunjucksConfig({
     getRequestBasePath,
     logger,
     readFileSync,
-    moduleId
+    moduleId,
+    errorPages
   })
 
   const nunjucksConfig = {

package/src/nunjucks/plugin.test.js

@@ -110,4 +110,28 @@ describe('createNunjucksConfig()', () => {
       expect.objectContaining({ backOffice: 'lis-perm-back-office' })
     )
   })
+
+  test('passes the errorPages links through to the view context', () => {
+    // Arrange
+    const config = {
+      get: vi.fn((key) => (key === 'root' ? projectRoot : false))
+    }
+    const errorPages = {
+      contactHref: 'https://example.com/contact',
+      homeHref: '/home',
+      getStartedHref: '/start'
+    }
+
+    // Act
+    const nunjucksConfig = createNunjucksConfig({
+      config,
+      logger: {},
+      getRequestBasePath: vi.fn(() => ''),
+      errorPages
+    })
+    const context = nunjucksConfig.options.context({ headers: {}, path: '/' })
+
+    // Assert
+    expect(context.errorPages).toEqual(errorPages)
+  })
 })

package/src/nunjucks/routes/error/error-pages.test.js

@@ -0,0 +1,194 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import nunjucks from 'nunjucks'
+import { describe, expect, test } from 'vitest'
+
+const routesRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..'
+)
+const layoutFixtureRoot = path.resolve(
+  routesRoot,
+  '../../../test/fixtures/nunjucks'
+)
+const environment = new nunjucks.Environment(
+  new nunjucks.FileSystemLoader([routesRoot, layoutFixtureRoot]),
+  { autoescape: true, trimBlocks: true, lstripBlocks: true }
+)
+
+const errorPages = {
+  contactHref: 'https://example.com/contact',
+  homeHref: '/home',
+  getStartedHref: '/start'
+}
+
+function render(view, context = {}) {
+  return environment.render(view, {
+    errorPages,
+    ...context
+  })
+}
+
+function textOf(html) {
+  return html
+    .replaceAll(/<[^<>]*>/g, '')
+    .replaceAll(/\s+/g, ' ')
+    .trim()
+}
+
+describe('error pages', () => {
+  test('page not found shows the heading, the three links and the support link', () => {
+    // Arrange
+    const context = { pageTitle: 'Page not found' }
+
+    // Act
+    const html = render('error/page-not-found.njk', context)
+
+    // Assert
+    expect(html).toContain(
+      '<title>Page not found - Livestock Information</title>'
+    )
+    expect(html).toContain('<h1 class="govuk-heading-l">Page not found</h1>')
+    expect(textOf(html)).toContain(
+      "Sorry, we could not find the page you were looking for. You might find what you're looking for by visiting: Home page Get started GOV.UK If you cannot find the information you need, contact our support team."
+    )
+    expect(html).toContain('<a class="govuk-link" href="/home">Home page</a>')
+    expect(html).toContain(
+      '<a class="govuk-link" href="/start">Get started</a>'
+    )
+    expect(html).toContain(
+      '<a class="govuk-link" href="https://www.gov.uk">GOV.UK</a>'
+    )
+    expect(html).toContain(
+      '<a class="govuk-link" href="https://example.com/contact">contact our support team</a>'
+    )
+  })
+
+  test('not authorised offers a sign in button when signInHref is given', () => {
+    // Arrange
+    const context = { signInHref: '/auth/login' }
+
+    // Act
+    const html = render('error/not-authorised.njk', context)
+
+    // Assert
+    expect(html).toContain(
+      '<a href="/auth/login" role="button" draggable="false" class="govuk-button" data-module="govuk-button">Sign in</a>'
+    )
+  })
+
+  test('not authorised has no sign in button without signInHref', () => {
+    // Arrange
+    const context = {}
+
+    // Act
+    const html = render('error/not-authorised.njk', context)
+
+    // Assert
+    expect(html).not.toContain('govuk-button')
+    expect(html).not.toContain('Sign in')
+  })
+
+  test('not authorised shows the heading and the support link', () => {
+    // Arrange
+    const context = {
+      pageTitle: 'Sorry, you are not authorised to view this page'
+    }
+
+    // Act
+    const html = render('error/not-authorised.njk', context)
+
+    // Assert
+    expect(html).toContain(
+      '<title>Sorry, you are not authorised to view this page - Livestock Information</title>'
+    )
+    expect(html).toContain(
+      '<h1 class="govuk-heading-l">Sorry, you are not authorised to view this page.</h1>'
+    )
+    expect(textOf(html)).toContain(
+      'Check your details are correct and try again. If you think this is incorrect contact our support team.'
+    )
+    expect(html).toContain(
+      '<a class="govuk-link" href="https://example.com/contact">contact our support team</a>'
+    )
+  })
+
+  test('problem with the service shows the heading and the BCMS link', () => {
+    // Arrange
+    const context = { pageTitle: 'Sorry, there is a problem with the service' }
+
+    // Act
+    const html = render('error/problem-with-service.njk', context)
+
+    // Assert
+    expect(html).toContain(
+      '<title>Sorry, there is a problem with the service - Livestock Information</title>'
+    )
+    expect(html).toContain(
+      '<h1 class="govuk-heading-l">Sorry, there is a problem with the service</h1>'
+    )
+    expect(textOf(html)).toContain(
+      'Try again later. Contact the British Cattle Movement Service (BCMS) if you need to speak to someone about your account.'
+    )
+    expect(html).toContain(
+      '<a class="govuk-link" href="https://example.com/contact">British Cattle Movement Service (BCMS)</a>'
+    )
+  })
+
+  test('service unavailable shows when the service will be available again', () => {
+    // Arrange
+    const context = {
+      pageTitle: 'Sorry, the service is unavailable',
+      availableFrom: '9am on Monday 19 November 2026'
+    }
+
+    // Act
+    const html = render('error/service-unavailable.njk', context)
+
+    // Assert
+    expect(html).toContain(
+      '<title>Sorry, the service is unavailable - Livestock Information</title>'
+    )
+    expect(html).toContain(
+      '<h1 class="govuk-heading-l">Sorry, the service is unavailable</h1>'
+    )
+    expect(textOf(html)).toContain(
+      'You will be able to use the service from 9am on Monday 19 November 2026. Contact the British Cattle Movement Service (BCMS) if you need to speak to someone about your account.'
+    )
+    expect(html).toContain(
+      '<a class="govuk-link" href="https://example.com/contact">British Cattle Movement Service (BCMS)</a>'
+    )
+  })
+
+  test('service unavailable says later when no return time is given', () => {
+    // Arrange
+    const context = { pageTitle: 'Sorry, the service is unavailable' }
+
+    // Act
+    const html = render('error/service-unavailable.njk', context)
+
+    // Assert
+    expect(textOf(html)).toContain('You will be able to use the service later.')
+  })
+
+  test.each([
+    'error/page-not-found.njk',
+    'error/not-authorised.njk',
+    'error/problem-with-service.njk',
+    'error/service-unavailable.njk'
+  ])('%s shows the development message only when one is given', (view) => {
+    // Arrange
+    const withMessage = { developmentMessage: 'Upstream timed out' }
+
+    // Act
+    const htmlWithMessage = render(view, withMessage)
+    const htmlWithoutMessage = render(view)
+
+    // Assert
+    expect(htmlWithMessage).toContain(
+      '<p class="govuk-body">Upstream timed out</p>'
+    )
+    expect(htmlWithoutMessage).not.toContain('Upstream timed out')
+  })
+})

package/src/nunjucks/routes/error/not-authorised.njk

@@ -0,0 +1,17 @@
+{% extends 'layouts/page.njk' %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h1 class="govuk-heading-l">Sorry, you are not authorised to view this page.</h1>
+      <p class="govuk-body">Check your details are correct and try again.</p>
+      <p class="govuk-body">If you think this is incorrect <a class="govuk-link" href="{{ errorPages.contactHref }}">contact our support team</a>.</p>
+      {% if signInHref %}
+        <a href="{{ signInHref }}" role="button" draggable="false" class="govuk-button" data-module="govuk-button">Sign in</a>
+      {% endif %}
+      {% if developmentMessage %}
+        <p class="govuk-body">{{ developmentMessage }}</p>
+      {% endif %}
+    </div>
+  </div>
+{% endblock %}

package/src/nunjucks/routes/error/page-not-found.njk

@@ -0,0 +1,20 @@
+{% extends 'layouts/page.njk' %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h1 class="govuk-heading-l">Page not found</h1>
+      <p class="govuk-body">Sorry, we could not find the page you were looking for.</p>
+      <p class="govuk-body">You might find what you're looking for by visiting:</p>
+      <ul class="govuk-list">
+        <li><a class="govuk-link" href="{{ errorPages.homeHref }}">Home page</a></li>
+        <li><a class="govuk-link" href="{{ errorPages.getStartedHref }}">Get started</a></li>
+        <li><a class="govuk-link" href="https://www.gov.uk">GOV.UK</a></li>
+      </ul>
+      <p class="govuk-body">If you cannot find the information you need, <a class="govuk-link" href="{{ errorPages.contactHref }}">contact our support team</a>.</p>
+      {% if developmentMessage %}
+        <p class="govuk-body">{{ developmentMessage }}</p>
+      {% endif %}
+    </div>
+  </div>
+{% endblock %}

package/src/nunjucks/routes/error/problem-with-service.njk

@@ -0,0 +1,14 @@
+{% extends 'layouts/page.njk' %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h1 class="govuk-heading-l">Sorry, there is a problem with the service</h1>
+      <p class="govuk-body">Try again later.</p>
+      <p class="govuk-body">Contact the <a class="govuk-link" href="{{ errorPages.contactHref }}">British Cattle Movement Service (BCMS)</a> if you need to speak to someone about your account.</p>
+      {% if developmentMessage %}
+        <p class="govuk-body">{{ developmentMessage }}</p>
+      {% endif %}
+    </div>
+  </div>
+{% endblock %}

package/src/nunjucks/routes/error/service-unavailable.njk

@@ -0,0 +1,18 @@
+{% extends 'layouts/page.njk' %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h1 class="govuk-heading-l">Sorry, the service is unavailable</h1>
+      {% if availableFrom %}
+        <p class="govuk-body">You will be able to use the service from {{ availableFrom }}.</p>
+      {% else %}
+        <p class="govuk-body">You will be able to use the service later.</p>
+      {% endif %}
+      <p class="govuk-body">Contact the <a class="govuk-link" href="{{ errorPages.contactHref }}">British Cattle Movement Service (BCMS)</a> if you need to speak to someone about your account.</p>
+      {% if developmentMessage %}
+        <p class="govuk-body">{{ developmentMessage }}</p>
+      {% endif %}
+    </div>
+  </div>
+{% endblock %}

package/src/nunjucks/routes/error/index.njk

@@ -1,13 +0,0 @@
-{% extends 'layouts/page.njk' %}
-
-{% block content %}
-  {{ appHeading({
-    text: heading
-  }) }}
-
-  <div class="govuk-grid-row">
-    <div class="govuk-grid-column-two-thirds">
-      <p>{{ message }}</p>
-    </div>
-  </div>
-{% endblock %}