@defra/lis-infra-ui-services 0.35.0 → 0.36.0-lreg-504.alpha.1

package/README.md

@@ -279,6 +279,29 @@ await server.register(
 
 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.
 
+### Cookies
+
+The base layout shows the GOV.UK cookie banner until the visitor has made a choice, and its footer links to a cookies page at `/cookies`. The choice is kept for a year in a `cookies_policy` cookie (URL-encoded JSON, readable by client-side scripts so analytics can check it before loading), set by the banner's JavaScript or, without JavaScript, by posting the banner's form to `/cookies`. Each hub registers the page with the essential cookies it sets, which the page lists:
+
+```js
+// server.js, after @hapi/vision is registered
+import { createCookiesPlugin } from '@defra/lis-infra-ui-services/cookies'
+
+await server.register(
+  createCookiesPlugin({
+    essentialCookies: [
+      {
+        name: config.get('session.cache.name'),
+        purpose: 'Keeps you signed in as you move between pages',
+        expires: 'After 4 hours, or when you sign out'
+      }
+    ]
+  })
+)
+```
+
+`GET /cookies` shows the page, with a form to change the choice. `POST /cookies` records a choice (`analytics=yes|no`), ignoring cross-site posts, and redirects to the page with a confirmation and a link back to the same-host page the visitor came from. The `CookieBanner` component is part of `layoutComponents` (see [Layout scripts](#layout-scripts)), so a hub that already initialises those needs no further client-side change. `getCookiesPolicy(request)` from `@defra/lis-infra-ui-services/cookies/cookies-policy` reads the recorded choice server-side.
+
 ### Environment variables
 
 The package reads no environment variables itself. It takes all its settings from the `config` object the consuming app passes in. In the example above, `MAINTENANCE_AVAILABLE_FROM` is a variable the hub defines in its own config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.35.0",
+  "version": "0.36.0-lreg-504.alpha.1",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {
@@ -10,7 +10,10 @@
   "exports": {
     ".": "./src/index.js",
     "./base-path": "./src/base-path.js",
+    "./cookies": "./src/cookies/index.js",
+    "./cookies/cookies-policy": "./src/cookies/cookies-policy.js",
     "./components/autocomplete": "./src/components/autocomplete.js",
+    "./components/cookie-banner": "./src/components/cookie-banner.js",
     "./components/error-pages": "./src/components/error-pages.js",
     "./components/layout": "./src/components/layout.js",
     "./components/scrollable-table": "./src/components/scrollable-table.js",

package/src/components/cookie-banner.js

@@ -0,0 +1,83 @@
+import { Component } from 'govuk-frontend'
+
+import {
+  COOKIES_POLICY_COOKIE_NAME,
+  createCookiesPolicy,
+  serialiseCookiesPolicy
+} from '../cookies/cookies-policy.js'
+import { seconds } from '../duration.js'
+
+/**
+ * Progressive enhancement for the cookie banner: records the choice in the
+ * consent cookie without a round trip and swaps the question for the
+ * confirmation. Without JavaScript the form posts to the cookies page.
+ */
+export class CookieBanner extends Component {
+  static moduleName = 'lis-cookie-banner'
+
+  /**
+   * @param {object} $root - the banner region
+   */
+  constructor($root) {
+    super($root)
+
+    this.$question = this.$root.querySelector('[data-cookie-banner-question]')
+    this.$confirmation = this.$root.querySelector(
+      '[data-cookie-banner-confirmation]'
+    )
+    this.$decision = this.$root.querySelector('[data-cookie-banner-decision]')
+
+    this.$question?.addEventListener('submit', (event) => this.onSubmit(event))
+    this.$root
+      .querySelector('[data-cookie-banner-hide]')
+      ?.addEventListener('click', () => this.hide())
+  }
+
+  /**
+   * @param {object} event - the question form's submit event
+   */
+  onSubmit(event) {
+    const analytics = event.submitter?.value
+
+    if (analytics !== 'yes' && analytics !== 'no') {
+      return
+    }
+
+    event.preventDefault()
+    this.setCookiesPolicy(analytics === 'yes')
+    this.confirm(analytics === 'yes')
+  }
+
+  /**
+   * @param {boolean} analytics
+   */
+  setCookiesPolicy(analytics) {
+    const value = serialiseCookiesPolicy(createCookiesPolicy(analytics))
+
+    document.cookie = `${COOKIES_POLICY_COOKIE_NAME}=${value}; path=/; max-age=${seconds.oneYear}; secure; samesite=lax`
+  }
+
+  /**
+   * @param {boolean} analytics
+   */
+  confirm(analytics) {
+    if (this.$decision) {
+      this.$decision.textContent = analytics ? 'accepted' : 'rejected'
+    }
+    this.$question?.setAttribute('hidden', '')
+    if (this.$confirmation) {
+      this.$confirmation.removeAttribute('hidden')
+      // A div is not focusable until it has a tabindex; -1 keeps it out of
+      // the tab order, matching GOV.UK's own component.
+      this.$confirmation.setAttribute('tabindex', '-1')
+      this.$confirmation.focus()
+    }
+  }
+
+  /**
+   * Removes the banner once the confirmation has been read.
+   */
+  hide() {
+    this.$root.setAttribute('hidden', '')
+  }
+}

package/src/components/cookie-banner.test.js

@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+// @vitest-environment-options { "url": "https://lis.test/" }
+import { createAll } from 'govuk-frontend'
+import { afterEach, beforeAll, describe, expect, test } from 'vitest'
+
+import { CookieBanner } from './cookie-banner.js'
+
+function renderBanner() {
+  document.body.innerHTML = `
+    <div class="govuk-cookie-banner" data-module="lis-cookie-banner">
+      <form method="post" action="/cookies" data-cookie-banner-question>
+        <button type="submit" name="analytics" value="yes">Accept</button>
+        <button type="submit" name="analytics" value="no">Reject</button>
+      </form>
+      <div hidden data-cookie-banner-confirmation>
+        <p>You’ve <span data-cookie-banner-decision>accepted</span> analytics cookies.</p>
+        <button type="button" data-cookie-banner-hide>Hide</button>
+      </div>
+    </div>
+  `
+  createAll(CookieBanner)
+
+  return {
+    $root: document.querySelector('.govuk-cookie-banner'),
+    $question: document.querySelector('[data-cookie-banner-question]'),
+    $confirmation: document.querySelector('[data-cookie-banner-confirmation]'),
+    $decision: document.querySelector('[data-cookie-banner-decision]'),
+    $accept: document.querySelector('button[value="yes"]'),
+    $reject: document.querySelector('button[value="no"]'),
+    $hide: document.querySelector('[data-cookie-banner-hide]')
+  }
+}
+
+function submitVia($button) {
+  const event = new window.SubmitEvent('submit', {
+    bubbles: true,
+    cancelable: true,
+    submitter: $button
+  })
+  $button.form.dispatchEvent(event)
+
+  return event
+}
+
+describe('CookieBanner', () => {
+  beforeAll(() => {
+    document.body.classList.add('govuk-frontend-supported')
+  })
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+    document.cookie = 'cookies_policy=; max-age=0; path=/'
+  })
+
+  test('accepting sets the consent cookie and shows the confirmation', () => {
+    // Arrange
+    const { $question, $confirmation, $decision, $accept } = renderBanner()
+
+    // Act
+    const event = submitVia($accept)
+
+    // Assert
+    expect(event.defaultPrevented).toBe(true)
+    expect(document.cookie).toContain(
+      'cookies_policy=%7B%22essential%22%3Atrue%2C%22analytics%22%3Atrue%7D'
+    )
+    expect($question.hidden).toBe(true)
+    expect($confirmation.hidden).toBe(false)
+    expect($confirmation.getAttribute('tabindex')).toBe('-1')
+    expect(document.activeElement).toBe($confirmation)
+    expect($decision.textContent).toBe('accepted')
+  })
+
+  test('rejecting records analytics as refused', () => {
+    // Arrange
+    const { $decision, $reject } = renderBanner()
+
+    // Act
+    submitVia($reject)
+
+    // Assert
+    expect(document.cookie).toContain(
+      'cookies_policy=%7B%22essential%22%3Atrue%2C%22analytics%22%3Afalse%7D'
+    )
+    expect($decision.textContent).toBe('rejected')
+  })
+
+  test('hide removes the banner', () => {
+    // Arrange
+    const { $root, $accept, $hide } = renderBanner()
+    submitVia($accept)
+
+    // Act
+    $hide.click()
+
+    // Assert
+    expect($root.hidden).toBe(true)
+  })
+
+  test('a submit without a recognised choice is left to the browser', () => {
+    // Arrange
+    const { $question } = renderBanner()
+
+    // Act
+    const event = new window.SubmitEvent('submit', {
+      bubbles: true,
+      cancelable: true
+    })
+    $question.dispatchEvent(event)
+
+    // Assert
+    expect(event.defaultPrevented).toBe(false)
+    expect(document.cookie).not.toContain('cookies_policy')
+  })
+})

package/src/components/layout.js

@@ -1,3 +1,10 @@
-import { ServiceNavigation, SkipLink } from 'govuk-frontend'
+import { NotificationBanner, ServiceNavigation, SkipLink } from 'govuk-frontend'
 
-export const layoutComponents = [ServiceNavigation, SkipLink]
+import { CookieBanner } from './cookie-banner.js'
+
+export const layoutComponents = [
+  ServiceNavigation,
+  SkipLink,
+  NotificationBanner,
+  CookieBanner
+]

package/src/components/layout.test.js

@@ -1,13 +1,19 @@
 // @vitest-environment jsdom
-import { ServiceNavigation, SkipLink } from 'govuk-frontend'
+import { NotificationBanner, ServiceNavigation, SkipLink } from 'govuk-frontend'
 import { describe, expect, test } from 'vitest'
 
+import { CookieBanner } from './cookie-banner.js'
 import { layoutComponents } from './layout.js'
 
 describe('layoutComponents', () => {
   test('contains the layout components in order', () => {
     // Arrange
-    const expected = [ServiceNavigation, SkipLink]
+    const expected = [
+      ServiceNavigation,
+      SkipLink,
+      NotificationBanner,
+      CookieBanner
+    ]
 
     // Act
     const actual = layoutComponents

package/src/cookies/cookies-policy.js

@@ -0,0 +1,74 @@
+/** @import { Request } from '@hapi/hapi' */
+import { milliseconds } from '../duration.js'
+
+export const COOKIES_POLICY_COOKIE_NAME = 'cookies_policy'
+export const COOKIES_PATH = '/cookies'
+
+/**
+ * Hapi state options for the consent cookie. It is readable by client-side
+ * JavaScript so the banner can set it and analytics can later check it.
+ */
+export const cookiesPolicyStateOptions = {
+  ttl: milliseconds.oneYear,
+  path: '/',
+  isSecure: true,
+  isHttpOnly: false,
+  isSameSite: 'Lax',
+  encoding: 'none',
+  clearInvalid: true,
+  ignoreErrors: true
+}
+
+/**
+ * @typedef {object} CookiesPolicy
+ * @property {boolean} essential - always true; essential cookies cannot be refused
+ * @property {boolean} analytics - whether analytics cookies may be set
+ */
+
+/**
+ * @param {boolean} analytics
+ * @returns {CookiesPolicy}
+ */
+export function createCookiesPolicy(analytics) {
+  return { essential: true, analytics: analytics === true }
+}
+
+/**
+ * Encodes a policy as the cookie value: URL-encoded JSON, so the value only
+ * contains cookie-safe characters and client-side code can decode it.
+ * @param {CookiesPolicy} policy
+ * @returns {string}
+ */
+export function serialiseCookiesPolicy(policy) {
+  return encodeURIComponent(JSON.stringify(policy))
+}
+
+/**
+ * @param {string | undefined} value - the raw cookie value
+ * @returns {CookiesPolicy | null} null when absent or malformed
+ */
+export function parseCookiesPolicy(value) {
+  if (typeof value !== 'string' || value === '') {
+    return null
+  }
+
+  try {
+    const parsed = JSON.parse(decodeURIComponent(value))
+
+    if (typeof parsed?.analytics !== 'boolean') {
+      return null
+    }
+
+    return createCookiesPolicy(parsed.analytics)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {Request} [request]
+ * @returns {CookiesPolicy | null}
+ */
+export function getCookiesPolicy(request) {
+  return parseCookiesPolicy(request?.state?.[COOKIES_POLICY_COOKIE_NAME])
+}

package/src/cookies/cookies-policy.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'vitest'
+
+import {
+  createCookiesPolicy,
+  getCookiesPolicy,
+  parseCookiesPolicy,
+  serialiseCookiesPolicy
+} from './cookies-policy.js'
+
+describe('createCookiesPolicy()', () => {
+  test('always keeps essential cookies on', () => {
+    // Arrange
+    // Act
+    const policy = createCookiesPolicy(false)
+
+    // Assert
+    expect(policy).toEqual({ essential: true, analytics: false })
+  })
+
+  test('treats anything but true as refusing analytics', () => {
+    // Arrange
+    // Act
+    const policy = createCookiesPolicy('yes')
+
+    // Assert
+    expect(policy.analytics).toBe(false)
+  })
+})
+
+describe('serialiseCookiesPolicy()', () => {
+  test('URL-encodes the policy as JSON', () => {
+    // Arrange
+    const policy = { essential: true, analytics: true }
+
+    // Act
+    const value = serialiseCookiesPolicy(policy)
+
+    // Assert
+    expect(value).toBe('%7B%22essential%22%3Atrue%2C%22analytics%22%3Atrue%7D')
+  })
+})
+
+describe('parseCookiesPolicy()', () => {
+  test('round-trips a serialised policy', () => {
+    // Arrange
+    const value = serialiseCookiesPolicy(createCookiesPolicy(true))
+
+    // Act
+    const policy = parseCookiesPolicy(value)
+
+    // Assert
+    expect(policy).toEqual({ essential: true, analytics: true })
+  })
+
+  test.each([
+    ['undefined', undefined],
+    ['empty', ''],
+    ['not JSON', 'yes'],
+    ['bad encoding', '%E0%A4%A'],
+    ['missing analytics', '%7B%22essential%22%3Atrue%7D'],
+    ['analytics not boolean', '%7B%22analytics%22%3A%22yes%22%7D']
+  ])('returns null for a %s value', (_label, value) => {
+    // Arrange
+    // Act
+    const policy = parseCookiesPolicy(value)
+
+    // Assert
+    expect(policy).toBeNull()
+  })
+})
+
+describe('getCookiesPolicy()', () => {
+  test('reads the cookies_policy cookie from request state', () => {
+    // Arrange
+    const request = {
+      state: {
+        cookies_policy: serialiseCookiesPolicy(createCookiesPolicy(false))
+      }
+    }
+
+    // Act
+    const policy = getCookiesPolicy(request)
+
+    // Assert
+    expect(policy).toEqual({ essential: true, analytics: false })
+  })
+
+  test('returns null without a request', () => {
+    // Arrange
+    // Act
+    const policy = getCookiesPolicy(undefined)
+
+    // Assert
+    expect(policy).toBeNull()
+  })
+})

package/src/cookies/index.js

@@ -0,0 +1,185 @@
+/** @import { Plugin, Request, ResponseToolkit } from '@hapi/hapi' */
+import { getSameHostReferrerPath } from '../referrer-link.js'
+import {
+  COOKIES_PATH,
+  COOKIES_POLICY_COOKIE_NAME,
+  cookiesPolicyStateOptions,
+  createCookiesPolicy,
+  getCookiesPolicy,
+  serialiseCookiesPolicy
+} from './cookies-policy.js'
+
+const PLUGIN_NAME = 'lis-cookies'
+const PAGE_TITLE = 'Cookies'
+const VIEW = 'cookies/index'
+const CONSENT_VALUES = new Set(['yes', 'no'])
+// Only used to resolve a candidate path; never appears in output.
+const PROBE_ORIGIN = 'https://same-origin.invalid'
+
+/**
+ * @typedef {object} EssentialCookie
+ * @property {string} name
+ * @property {string} purpose
+ * @property {string} expires
+ */
+
+/**
+ * Keeps a candidate on this origin by resolving it the way a browser would:
+ * `//host`, `/\\host` and absolute URLs all resolve elsewhere and are refused.
+ * @param {unknown} candidate
+ * @returns {string} the path when it is on this origin, otherwise the root
+ */
+export function toSameOriginPath(candidate) {
+  if (typeof candidate !== 'string' || !candidate.startsWith('/')) {
+    return '/'
+  }
+
+  try {
+    const url = new URL(candidate, PROBE_ORIGIN)
+
+    // A normalised path starting with // would be protocol-relative in a link.
+    if (url.origin !== PROBE_ORIGIN || url.pathname.startsWith('//')) {
+      return '/'
+    }
+
+    return `${url.pathname}${url.search}`
+  } catch {
+    return '/'
+  }
+}
+
+/**
+ * Returns the same-host path the user came from, so the cookies page can
+ * link back to it after a choice made from the banner without JavaScript.
+ * Anything else, including another host or the cookies page itself, falls
+ * back to the service root.
+ * @param {Request} request
+ * @returns {string}
+ */
+export function getReturnPath(request) {
+  const referrerPath = getSameHostReferrerPath(request)
+
+  if (!referrerPath || referrerPath.split('?')[0] === COOKIES_PATH) {
+    return '/'
+  }
+
+  return toSameOriginPath(referrerPath)
+}
+
+/**
+ * @param {Request} request
+ * @returns {string} the host the browser addressed, as the hub proxy forwards it
+ */
+function getRequestHost(request) {
+  return (request.headers['x-forwarded-host'] ?? request.headers.host ?? '')
+    .split(',')[0]
+    .trim()
+}
+
+/**
+ * Whether a consent POST came from this site. Hapi has no CSRF token here, so
+ * the browser's own signals are used: Sec-Fetch-Site when present, otherwise
+ * the Origin header, which browsers always send on a cross-site form POST.
+ * @param {Request} request
+ * @returns {boolean}
+ */
+export function isSameSiteRequest(request) {
+  const fetchSite = request.headers['sec-fetch-site']
+
+  if (typeof fetchSite === 'string') {
+    return fetchSite === 'same-origin' || fetchSite === 'same-site'
+  }
+
+  const origin = request.headers.origin
+
+  if (typeof origin !== 'string' || origin === '') {
+    return true
+  }
+
+  try {
+    return new URL(origin).host === getRequestHost(request)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {EssentialCookie[]} essentialCookies
+ * @returns {(request: Request, h: ResponseToolkit) => unknown}
+ */
+function createGetHandler(essentialCookies) {
+  return function getCookiesPage(request, h) {
+    const cookiesPolicy = getCookiesPolicy(request)
+    const saved = request.query?.saved === 'true'
+
+    return h.view(VIEW, {
+      pageTitle: PAGE_TITLE,
+      essentialCookieRows: essentialCookies.map((cookie) => [
+        { text: cookie.name },
+        { text: cookie.purpose },
+        { text: cookie.expires }
+      ]),
+      analytics: cookiesPolicy?.analytics === true,
+      saved,
+      returnPath: saved ? toSameOriginPath(request.query?.returnPath) : null
+    })
+  }
+}
+
+/**
+ * @param {Request} request
+ * @param {ResponseToolkit} h
+ * @returns {unknown}
+ */
+function postConsent(request, h) {
+  const analytics = request.payload?.analytics
+
+  if (!CONSENT_VALUES.has(analytics) || !isSameSiteRequest(request)) {
+    return h.redirect(COOKIES_PATH)
+  }
+
+  const policy = createCookiesPolicy(analytics === 'yes')
+  const query = new URLSearchParams({
+    saved: 'true',
+    returnPath: getReturnPath(request)
+  })
+
+  return h
+    .redirect(`${COOKIES_PATH}?${query}`)
+    .state(COOKIES_POLICY_COOKIE_NAME, serialiseCookiesPolicy(policy))
+}
+
+/**
+ * Registers the consent cookie and the cookies page: GET shows the page, POST
+ * records the choice (from the page's form or the banner without JavaScript)
+ * and redirects back to the page with a confirmation.
+ * @param {{ essentialCookies: EssentialCookie[] }} options
+ * @returns {Plugin<void>}
+ */
+export function createCookiesPlugin({ essentialCookies } = {}) {
+  if (!Array.isArray(essentialCookies) || essentialCookies.length === 0) {
+    throw new Error('createCookiesPlugin requires essentialCookies')
+  }
+
+  return {
+    name: PLUGIN_NAME,
+    register(server) {
+      server.state(COOKIES_POLICY_COOKIE_NAME, cookiesPolicyStateOptions)
+
+      server.route([
+        {
+          method: 'GET',
+          path: COOKIES_PATH,
+          options: { auth: { mode: 'try' } },
+          handler: createGetHandler(essentialCookies)
+        },
+        {
+          method: 'POST',
+          path: COOKIES_PATH,
+          options: { auth: { mode: 'try' } },
+          handler: postConsent
+        }
+      ])
+    }
+  }
+}

package/src/cookies/index.test.js

@@ -0,0 +1,323 @@
+import path from 'node:path'
+import { createRequire } from 'node:module'
+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 {
+  createCookiesPlugin,
+  getReturnPath,
+  isSameSiteRequest,
+  toSameOriginPath
+} from './index.js'
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../..'
+)
+const govukFrontendRoot = path.dirname(
+  createRequire(import.meta.url).resolve('govuk-frontend/package.json')
+)
+const environment = new nunjucks.Environment(
+  new nunjucks.FileSystemLoader([
+    path.join(govukFrontendRoot, 'dist'),
+    path.join(packageRoot, 'src/nunjucks/routes'),
+    path.join(packageRoot, 'test/fixtures/nunjucks/layouts/..')
+  ]),
+  { autoescape: true }
+)
+
+const essentialCookies = [
+  {
+    name: 'front-office-session',
+    purpose: 'Keeps you signed in',
+    expires: 'After 4 hours'
+  }
+]
+
+let server
+
+async function createServer() {
+  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: { cookiesPath: '/cookies' }
+    }
+  })
+  server.auth.scheme('none', () => ({
+    authenticate: (_request, h) => h.unauthenticated(new Error('no session'))
+  }))
+  server.auth.strategy('none', 'none')
+  server.auth.default('none')
+  await server.register(createCookiesPlugin({ essentialCookies }))
+  await server.initialize()
+
+  return server
+}
+
+afterEach(async () => {
+  await server?.stop()
+  server = undefined
+})
+
+describe('createCookiesPlugin()', () => {
+  test('throws without essential cookies to list', () => {
+    // Arrange
+    // Act
+    const act = () => createCookiesPlugin({})
+
+    // Assert
+    expect(act).toThrow('createCookiesPlugin requires essentialCookies')
+  })
+
+  test('GET /cookies lists the essential cookies with analytics unchecked by default', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({ method: 'GET', url: '/cookies' })
+
+    // Assert
+    expect(response.statusCode).toBe(200)
+    expect(response.result).toContain(
+      '<h1 class="govuk-heading-l">Cookies</h1>'
+    )
+    expect(response.result).toContain('front-office-session')
+    expect(response.result).toContain('Keeps you signed in')
+    expect(response.result).toMatch(/value="no"[^>]*checked/)
+    expect(response.result).not.toContain('govuk-notification-banner')
+  })
+
+  test('GET /cookies reflects an accepted policy from the cookie', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'GET',
+      url: '/cookies',
+      headers: {
+        cookie:
+          'cookies_policy=%7B%22essential%22%3Atrue%2C%22analytics%22%3Atrue%7D'
+      }
+    })
+
+    // Assert
+    expect(response.result).toMatch(/value="yes"[^>]*checked/)
+  })
+
+  test('GET /cookies?saved=true shows the confirmation with a same-origin return link', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'GET',
+      url: '/cookies?saved=true&returnPath=%2Fcattle%2Fhome%3Fcph%3D1'
+    })
+
+    // Assert
+    expect(response.result).toContain('You’ve set your cookie preferences.')
+    expect(response.result).toContain('href="/cattle/home?cph=1"')
+  })
+
+  test('GET /cookies?saved=true falls back to the root for a foreign return path', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'GET',
+      url: '/cookies?saved=true&returnPath=//evil.example/x'
+    })
+
+    // Assert
+    expect(response.result).toContain('href="/"')
+  })
+
+  test('POST /cookies records acceptance and redirects to the confirmation', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      headers: { host: 'lis.test', referer: 'https://lis.test/cattle/home' },
+      payload: { analytics: 'yes' }
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(302)
+    expect(response.headers.location).toBe(
+      '/cookies?saved=true&returnPath=%2Fcattle%2Fhome'
+    )
+    const setCookie = response.headers['set-cookie'][0]
+    expect(setCookie).toContain(
+      'cookies_policy=%7B%22essential%22%3Atrue%2C%22analytics%22%3Atrue%7D'
+    )
+    expect(setCookie).toContain('Secure')
+    expect(setCookie).toContain('SameSite=Lax')
+    expect(setCookie).toContain('Path=/')
+    expect(setCookie).not.toContain('HttpOnly')
+  })
+
+  test('POST /cookies records refusal', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      payload: { analytics: 'no' }
+    })
+
+    // Assert
+    expect(response.headers['set-cookie'][0]).toContain(
+      'cookies_policy=%7B%22essential%22%3Atrue%2C%22analytics%22%3Afalse%7D'
+    )
+    expect(response.headers.location).toBe('/cookies?saved=true&returnPath=%2F')
+  })
+
+  test('POST /cookies with an invalid choice sets nothing and returns to the page', async () => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      payload: { analytics: 'maybe' }
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(302)
+    expect(response.headers.location).toBe('/cookies')
+    expect(response.headers['set-cookie']).toBeUndefined()
+  })
+})
+
+describe('toSameOriginPath()', () => {
+  test.each([
+    ['/holdings', '/holdings'],
+    ['/a?b=c', '/a?b=c'],
+    ['//evil.example', '/'],
+    ['/\\evil.example/x', '/'],
+    ['/a/../..//evil.example', '/'],
+    ['https://evil.example/', '/'],
+    ['holdings', '/'],
+    [undefined, '/']
+  ])('maps %s to %s', (candidate, expected) => {
+    // Arrange
+    // Act
+    const actual = toSameOriginPath(candidate)
+
+    // Assert
+    expect(actual).toBe(expected)
+  })
+})
+
+describe('getReturnPath()', () => {
+  test.each([
+    ['no referer', {}, '/'],
+    [
+      'same-host referer',
+      { referer: 'https://lis.test/cattle?x=1' },
+      '/cattle?x=1'
+    ],
+    [
+      'a forwarded host',
+      {
+        host: 'internal:3001',
+        'x-forwarded-host': 'lis.test',
+        referer: 'https://lis.test/cattle'
+      },
+      '/cattle'
+    ],
+    ['cross-host referer', { referer: 'https://evil.example/cattle' }, '/'],
+    ['the cookies page itself', { referer: 'https://lis.test/cookies' }, '/'],
+    [
+      'the cookies page with a query',
+      { referer: 'https://lis.test/cookies?saved=true' },
+      '/'
+    ],
+    ['an unparseable referer', { referer: 'not a url' }, '/']
+  ])('handles %s', (_label, headers, expected) => {
+    // Arrange
+    const request = { headers: { host: 'lis.test', ...headers } }
+
+    // Act
+    const actual = getReturnPath(request)
+
+    // Assert
+    expect(actual).toBe(expected)
+  })
+})
+
+describe('isSameSiteRequest()', () => {
+  test.each([
+    ['sec-fetch-site same-origin', { 'sec-fetch-site': 'same-origin' }, true],
+    ['sec-fetch-site same-site', { 'sec-fetch-site': 'same-site' }, true],
+    ['sec-fetch-site cross-site', { 'sec-fetch-site': 'cross-site' }, false],
+    ['sec-fetch-site none', { 'sec-fetch-site': 'none' }, false],
+    ['no signals at all', {}, true],
+    ['matching origin', { origin: 'https://lis.test' }, true],
+    ['foreign origin', { origin: 'https://evil.example' }, false],
+    ['unparseable origin', { origin: 'not a url' }, false],
+    [
+      'origin matching the forwarded host',
+      {
+        host: 'internal:3001',
+        'x-forwarded-host': 'lis.test',
+        origin: 'https://lis.test'
+      },
+      true
+    ]
+  ])('handles %s', (_label, headers, expected) => {
+    // Arrange
+    const request = { headers: { host: 'lis.test', ...headers } }
+
+    // Act
+    const actual = isSameSiteRequest(request)
+
+    // Assert
+    expect(actual).toBe(expected)
+  })
+})
+
+describe('POST /cookies from another site', () => {
+  test.each([
+    ['sec-fetch-site cross-site', { 'sec-fetch-site': 'cross-site' }],
+    ['a foreign origin', { origin: 'https://evil.example' }]
+  ])('ignores a consent POST with %s', async (_label, headers) => {
+    // Arrange
+    await createServer()
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      headers,
+      payload: { analytics: 'yes' }
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(302)
+    expect(response.headers.location).toBe('/cookies')
+    expect(response.headers['set-cookie']).toBeUndefined()
+  })
+})

package/src/duration.js

@@ -4,6 +4,7 @@ const MILLIS_IN_SECOND = 1000
 
 const HOURS_IN_DAY = 24
 const DAYS_IN_WEEK = 7
+const DAYS_IN_YEAR = 365
 
 const TWO = 2
 const FOUR = 4
@@ -25,6 +26,12 @@ export const milliseconds = {
     HOURS_IN_DAY *
     MINUTES_IN_HOUR *
     SECONDS_IN_MINUTE *
+    MILLIS_IN_SECOND,
+  oneYear:
+    DAYS_IN_YEAR *
+    HOURS_IN_DAY *
+    MINUTES_IN_HOUR *
+    SECONDS_IN_MINUTE *
     MILLIS_IN_SECOND
 }
 
@@ -36,7 +43,8 @@ export const seconds = {
   oneHour: MINUTES_IN_HOUR * SECONDS_IN_MINUTE,
   eightHours: EIGHT * MINUTES_IN_HOUR * SECONDS_IN_MINUTE,
   oneDay: HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE,
-  oneWeek: DAYS_IN_WEEK * HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE
+  oneWeek: DAYS_IN_WEEK * HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE,
+  oneYear: DAYS_IN_YEAR * HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE
 }
 
 /**

package/src/nunjucks/context.js

@@ -3,6 +3,8 @@ import path from 'node:path'
 import { hasPermission } from '@defra/lis-hubs-infra-access/authorization'
 import { HUBS, getModuleById } from '@defra/lis-hubs-infra-registry'
 
+import { COOKIES_PATH, getCookiesPolicy } from '../cookies/cookies-policy.js'
+
 const HUB_SERVICE_NAME_PREFIX = 'lis-hubs-'
 
 export const BCMS_CONTACT_HREF =
@@ -108,6 +110,9 @@ export function createNunjucksContextBuilder({
       isBackOffice: requestHubId === 'back-office',
       hasPermission: createPermissionCheck(request),
       logoutUrl: '/signout',
+      cookiesPath: COOKIES_PATH,
+      cookiesPolicy: getCookiesPolicy(request),
+      isCookiesPage: request?.path === COOKIES_PATH,
       errorPages: errorPageLinks,
       getAssetPath(asset) {
         const viteAssetPath = viteManifest?.[asset]?.file

package/src/nunjucks/context.test.js

@@ -201,6 +201,52 @@ test('createNunjucksContextBuilder marks the user signed out without credentials
   assert.equal(context.isSignedIn, false)
 })
 
+describe('createNunjucksContextBuilder() cookies', () => {
+  test('exposes the cookies page path and no policy before consent', () => {
+    // Arrange
+    const contextBuilder = createSignedInContextBuilder()
+
+    // Act
+    const context = contextBuilder({ headers: {}, path: '/', state: {} })
+
+    // Assert
+    assert.equal(context.cookiesPath, '/cookies')
+    assert.equal(context.cookiesPolicy, null)
+    assert.equal(context.isCookiesPage, false)
+  })
+
+  test('exposes the consent recorded in the cookies_policy cookie', () => {
+    // Arrange
+    const contextBuilder = createSignedInContextBuilder()
+
+    // Act
+    const context = contextBuilder({
+      headers: {},
+      path: '/',
+      state: {
+        cookies_policy: '%7B%22essential%22%3Atrue%2C%22analytics%22%3Afalse%7D'
+      }
+    })
+
+    // Assert
+    assert.deepEqual(context.cookiesPolicy, {
+      essential: true,
+      analytics: false
+    })
+  })
+
+  test('flags the cookies page so the layout can hide the banner on it', () => {
+    // Arrange
+    const contextBuilder = createSignedInContextBuilder()
+
+    // Act
+    const context = contextBuilder({ headers: {}, path: '/cookies', state: {} })
+
+    // Assert
+    assert.equal(context.isCookiesPage, true)
+  })
+})
+
 describe('createNunjucksContextBuilder() hub flags', () => {
   test('marks the request as front office when the caller is the front-office hub', () => {
     // Arrange

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

@@ -0,0 +1,67 @@
+{% extends 'layouts/page.njk' %}
+
+{% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/notification-banner/macro.njk" import govukNotificationBanner %}
+{% from "govuk/components/radios/macro.njk" import govukRadios %}
+{% from "govuk/components/table/macro.njk" import govukTable %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      {% if saved %}
+        {% set savedHtml %}
+          <h3 class="govuk-notification-banner__heading">You’ve set your cookie preferences.</h3>
+          <p class="govuk-body"><a class="govuk-notification-banner__link" href="{{ returnPath }}">Go back to the page you were looking at</a></p>
+        {% endset %}
+        {{ govukNotificationBanner({
+          type: "success",
+          html: savedHtml
+        }) }}
+      {% endif %}
+
+      <h1 class="govuk-heading-l">Cookies</h1>
+
+      <p class="govuk-body">Cookies are small files saved on your phone, tablet or computer when you visit a website.</p>
+
+      <p class="govuk-body">We use cookies to make this service work and to collect information about how you use it.</p>
+
+      <h2 class="govuk-heading-m">Essential cookies</h2>
+
+      <p class="govuk-body">Essential cookies keep your information secure while you use this service. We do not need to ask permission to use them.</p>
+
+      {{ govukTable({
+        firstCellIsHeader: false,
+        head: [
+          { text: "Name" },
+          { text: "Purpose" },
+          { text: "Expires" }
+        ],
+        rows: essentialCookieRows
+      }) }}
+
+      <h2 class="govuk-heading-m">Analytics cookies (optional)</h2>
+
+      <p class="govuk-body">With your permission, we may use analytics software to collect anonymised information about how you use this service, for example which pages you visit and how long you spend on them. This helps us improve the service.</p>
+
+      <p class="govuk-body">We do not currently set any analytics cookies. Your choice is saved so that, if we add analytics later, it is respected from the start.</p>
+
+      <form method="post" action="{{ cookiesPath }}" novalidate>
+        {{ govukRadios({
+          name: "analytics",
+          fieldset: {
+            legend: {
+              text: "Do you want to accept analytics cookies?",
+              classes: "govuk-fieldset__legend--s"
+            }
+          },
+          items: [
+            { value: "yes", text: "Yes", checked: analytics },
+            { value: "no", text: "No", checked: not analytics }
+          ]
+        }) }}
+
+        {{ govukButton({ text: "Save cookie settings" }) }}
+      </form>
+    </div>
+  </div>
+{% endblock %}

package/src/nunjucks/templates/layouts/base.njk

@@ -38,6 +38,44 @@
   <link href="{{ getAssetPath('src/client/stylesheets/application.scss') }}" rel="stylesheet">
 {% endblock %}
 
+{% block bodyStart %}
+  {% if not cookiesPolicy and not isCookiesPage %}
+    {# Hand-written rather than govukCookieBanner so the question is a form
+       that works without JavaScript; the markup matches the GOV.UK component. #}
+    <div class="govuk-cookie-banner" data-nosnippet role="region" aria-label="Cookies on Livestock Information" data-module="lis-cookie-banner">
+      <form method="post" action="{{ cookiesPath }}" class="govuk-cookie-banner__message govuk-width-container" data-cookie-banner-question>
+        <div class="govuk-grid-row">
+          <div class="govuk-grid-column-two-thirds">
+            <h2 class="govuk-cookie-banner__heading govuk-heading-m">Cookies on Livestock Information</h2>
+            <div class="govuk-cookie-banner__content">
+              <p class="govuk-body">We use some essential cookies to make this service work.</p>
+              <p class="govuk-body">We’d also like to use analytics cookies so we can understand how you use the service and make improvements.</p>
+            </div>
+          </div>
+        </div>
+        <div class="govuk-button-group">
+          {{ govukButton({ text: "Accept analytics cookies", type: "submit", name: "analytics", value: "yes" }) }}
+          {{ govukButton({ text: "Reject analytics cookies", type: "submit", name: "analytics", value: "no" }) }}
+          <a class="govuk-link" href="{{ cookiesPath }}">View cookies</a>
+        </div>
+      </form>
+
+      <div class="govuk-cookie-banner__message govuk-width-container" role="alert" hidden data-cookie-banner-confirmation>
+        <div class="govuk-grid-row">
+          <div class="govuk-grid-column-two-thirds">
+            <div class="govuk-cookie-banner__content">
+              <p class="govuk-body">You’ve <span data-cookie-banner-decision>accepted</span> analytics cookies. You can <a class="govuk-link" href="{{ cookiesPath }}">change your cookie settings</a> at any time.</p>
+            </div>
+          </div>
+        </div>
+        <div class="govuk-button-group">
+          {{ govukButton({ text: "Hide cookie message", type: "button", attributes: { "data-cookie-banner-hide": "" } }) }}
+        </div>
+      </div>
+    </div>
+  {% endif %}
+{% endblock %}
+
 {% block govukHeader %}
   {{ govukHeader({
     homepageUrl: "https://www.gov.uk/",
@@ -97,7 +135,7 @@
           text: "Privacy"
         },
         {
-          href: "https://www.gov.uk/help/cookies",
+          href: cookiesPath,
           text: "Cookies"
         },
         {