@defra/lis-infra-ui-services 0.50.0 → 0.51.0

package/README.md

@@ -321,6 +321,19 @@ import { DatePicker } from '@defra/lis-infra-ui-services/components/date-picker'
 createAll(DatePicker)
 ```
 
+#### Form
+
+The `lisForm` template component renders a `novalidate` form with the CSRF token in a hidden `_csrf` field (see [CSRF protection](#csrf-protection)) around the caller's body. It takes `action` (left out when not given, so the form posts to the page itself), `method` (default `post`), `classes` and `attributes`. Import it `with context` so it reads `csrfToken` from the page, or pass `csrfToken` yourself. A `GET` form gets no token field, which would otherwise end up in the URL. A `POST` form with no token gets no field either, so its submission is refused with a 403: that usually means the macro was imported without `with context`, or the CSRF plugin is not registered on the server.
+
+```njk
+{% from "form/macro.njk" import lisForm with context %}
+
+{% call lisForm({ action: "/holdings/12/345/6789/edit", classes: "lis-edit-form" }) %}
+  {{ govukInput({ id: "nickname", name: "nickname", label: { text: "Nickname" } }) }}
+  {{ govukButton({ text: "Save" }) }}
+{% endcall %}
+```
+
 ### Styles
 
 Import the Sass files you need from your app's stylesheet: `components/autocomplete.scss`,
@@ -381,7 +394,43 @@ await server.register(
 )
 ```
 
-`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.
+`GET /cookies` shows the page, with a form to change the choice. `POST /cookies` records a choice (`analytics=yes|no`), ignoring any post that is not same-origin (it opts out of the CSRF plugin, as a signed-out visitor has no token), 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.
+
+### CSRF protection
+
+`csrfPlugin` from `@defra/lis-infra-ui-services/csrf` refuses, with a 403 and a warning log naming the failed check, every request other than `GET`, `HEAD` and `OPTIONS` that is not same-origin or does not carry the token. Register it after authentication and, on a hub, after the session:
+
+```js
+import { csrfPlugin } from '@defra/lis-infra-ui-services/csrf'
+
+// hub: the token lives in the yar session, issued once the user is signed in
+await server.register({
+  plugin: csrfPlugin,
+  options: { tokenSource: 'session' }
+})
+
+// spoke: the token comes from the hub in the x-lis-csrf-token header (CSRF_TOKEN_HEADER)
+await server.register({
+  plugin: csrfPlugin,
+  options: { tokenSource: 'header' }
+})
+```
+
+- **Origin check**: `Sec-Fetch-Site` must be `same-origin` (`same-site`, `cross-site` and `none` fail, as other tenants share the platform domain). Without it, the `Origin` host must match the host the browser addressed (`x-forwarded-host`, then `host`); the scheme is not compared, as TLS ends before the hub and spoke. A request with neither fails. `isSameOriginRequest(request)` exposes the check.
+- **Token check**: the `_csrf` field (`CSRF_FIELD_NAME`) of a parsed form or JSON body must match the request's token, compared in constant time. A streamed or raw body fails. The field is removed from `request.payload` before route validation, so schemas need not allow it.
+- The token is published at `request.plugins['lis-csrf'].token` and given to every view as `csrfToken`. `clearCsrfToken(request)` drops it from the session, so the next signed-in request gets a new one.
+
+**Known limitation:** browsers that send neither `Sec-Fetch-Site` nor `Origin` on a same-origin form `POST` (Internet Explorer 11, Firefox before 70) are refused with a 403.
+
+**Stricter `isSameSiteRequest`:** `isSameSiteRequest` from `@defra/lis-infra-ui-services/cookies` is kept for existing callers but deprecated, and now behaves as `isSameOriginRequest`: a `same-site` request, or one with neither `Sec-Fetch-Site` nor `Origin`, which it used to accept, is now refused.
+
+A route opts out through `options.plugins['lis-csrf']`: `false` or `{ enabled: false }` skips every check; `{ token: false }` keeps only the origin check, for a proxied (streamed) body or a form a signed-out visitor submits.
+
+A route can answer a failed check itself with `options.plugins['lis-csrf'] = { failAction: (request, h) => h.redirect('/') }`: the warning is still logged, then the plugin takes over with what `failAction` returns (a response or an error) in place of the 403. Returning `h.continue` still gets a 403, so a failed request never reaches the handler. Hub sign-out uses it to send an expired or forged sign-out home.
+
+The token is kept in the hub session under `lis-csrf-token` (`CSRF_SESSION_KEY`), which `@defra/lis-hubs-infra-access` clears at sign-in. A hub proxy sends it to spokes in `x-lis-csrf-token` and leaves the token check to the spoke.
+
+The base layout's header Sign out and the `error/not-authorised` view's Sign out (given a `signOutHref`) are links to `/signout`. A hub answers that `GET` with the `auth/sign-out` view, which asks the user to confirm: an `Are you sure you want to sign out?` heading, a `Sign out` button in a form posting the token to `signOutHref`, and a `Cancel` link to `/`. Pass `pageTitle` and `signOutHref`; render it only when there is a `csrfToken`.
 
 ### Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {
@@ -13,6 +13,7 @@
     "./config-formats": "./src/config-formats.js",
     "./cookies": "./src/cookies/index.js",
     "./cookies/cookies-policy": "./src/cookies/cookies-policy.js",
+    "./csrf": "./src/csrf/index.js",
     "./components/autocomplete": "./src/components/autocomplete.js",
     "./components/cookie-banner": "./src/components/cookie-banner.js",
     "./components/date-picker": "./src/components/date-picker.js",
@@ -63,6 +64,7 @@
   "author": "Defra DDTS",
   "license": "OGL-UK-3.0",
   "dependencies": {
+    "@hapi/boom": "10.0.1",
     "@hapi/catbox-memory": "6.0.2",
     "@hapi/catbox-redis": "7.0.2",
     "@hapi/vision": "7.0.3",
@@ -96,6 +98,7 @@
     "eslint": "^9.0.0",
     "govuk-frontend": "6.5.0",
     "husky": "^9.1.7",
+    "joi": "17.13.8",
     "jsdom": "^29.1.1",
     "prettier": "^3.8.4",
     "vitest": "^4.1.10"

package/src/cookies/index.js

@@ -1,4 +1,6 @@
 /** @import { Plugin, Request, ResponseToolkit } from '@hapi/hapi' */
+import { CSRF_PLUGIN_NAME } from '../csrf/constants.js'
+import { isSameOriginRequest } from '../csrf/same-origin.js'
 import { getSameHostReferrerPath } from '../referrer-link.js'
 import {
   COOKIES_PATH,
@@ -67,40 +69,14 @@ export function getReturnPath(request) {
 }
 
 /**
- * @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.
+ * @deprecated Use isSameOriginRequest from `@defra/lis-infra-ui-services/csrf`.
+ * Kept for existing callers; it now requires the same origin, so a same-site
+ * request, or one with neither Sec-Fetch-Site nor Origin, no longer passes.
  * @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
-  }
+  return isSameOriginRequest(request)
 }
 
 /**
@@ -134,7 +110,7 @@ function createGetHandler(essentialCookies) {
 function postConsent(request, h) {
   const analytics = request.payload?.analytics
 
-  if (!CONSENT_VALUES.has(analytics) || !isSameSiteRequest(request)) {
+  if (!CONSENT_VALUES.has(analytics) || !isSameOriginRequest(request)) {
     return h.redirect(COOKIES_PATH)
   }
 
@@ -176,7 +152,13 @@ export function createCookiesPlugin({ essentialCookies } = {}) {
         {
           method: 'POST',
           path: COOKIES_PATH,
-          options: { auth: { mode: 'try' } },
+          // A signed-out visitor has no CSRF token, and a refused post
+          // returns to the page rather than a 403, so the handler checks the
+          // origin itself.
+          options: {
+            auth: { mode: 'try' },
+            plugins: { [CSRF_PLUGIN_NAME]: false }
+          },
           handler: postConsent
         }
       ])

package/src/cookies/index.test.js

@@ -13,6 +13,7 @@ import {
   isSameSiteRequest,
   toSameOriginPath
 } from './index.js'
+import { csrfPlugin } from '../csrf/index.js'
 
 const packageRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -40,7 +41,7 @@ const essentialCookies = [
 
 let server
 
-async function createServer() {
+async function createServer({ withCsrf = false } = {}) {
   server = hapi.server()
   await server.register({
     plugin: hapiVision,
@@ -62,6 +63,12 @@ async function createServer() {
   }))
   server.auth.strategy('none', 'none')
   server.auth.default('none')
+  if (withCsrf) {
+    await server.register({
+      plugin: csrfPlugin,
+      options: { tokenSource: 'header' }
+    })
+  }
   await server.register(createCookiesPlugin({ essentialCookies }))
   await server.initialize()
 
@@ -156,7 +163,11 @@ describe('createCookiesPlugin()', () => {
     const response = await server.inject({
       method: 'POST',
       url: '/cookies',
-      headers: { host: 'lis.test', referer: 'https://lis.test/cattle/home' },
+      headers: {
+        host: 'lis.test',
+        referer: 'https://lis.test/cattle/home',
+        'sec-fetch-site': 'same-origin'
+      },
       payload: { analytics: 'yes' }
     })
 
@@ -183,6 +194,7 @@ describe('createCookiesPlugin()', () => {
     const response = await server.inject({
       method: 'POST',
       url: '/cookies',
+      headers: { 'sec-fetch-site': 'same-origin' },
       payload: { analytics: 'no' }
     })
 
@@ -201,6 +213,7 @@ describe('createCookiesPlugin()', () => {
     const response = await server.inject({
       method: 'POST',
       url: '/cookies',
+      headers: { 'sec-fetch-site': 'same-origin' },
       payload: { analytics: 'maybe' }
     })
 
@@ -271,10 +284,10 @@ describe('getReturnPath()', () => {
 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 same-site', { 'sec-fetch-site': 'same-site' }, false],
     ['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],
+    ['no signals at all', {}, false],
     ['matching origin', { origin: 'https://lis.test' }, true],
     ['foreign origin', { origin: 'https://evil.example' }, false],
     ['unparseable origin', { origin: 'not a url' }, false],
@@ -302,7 +315,9 @@ describe('isSameSiteRequest()', () => {
 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' }]
+    ['sec-fetch-site same-site', { 'sec-fetch-site': 'same-site' }],
+    ['a foreign origin', { origin: 'https://evil.example' }],
+    ['neither sec-fetch-site nor origin', {}]
   ])('ignores a consent POST with %s', async (_label, headers) => {
     // Arrange
     await createServer()
@@ -321,3 +336,40 @@ describe('POST /cookies from another site', () => {
     expect(response.headers['set-cookie']).toBeUndefined()
   })
 })
+
+describe('POST /cookies with the CSRF plugin registered', () => {
+  test('records a signed-out same-origin choice without a token', async () => {
+    // Arrange
+    await createServer({ withCsrf: true })
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      headers: { 'sec-fetch-site': 'same-origin' },
+      payload: { analytics: 'yes' }
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(302)
+    expect(response.headers.location).toBe('/cookies?saved=true&returnPath=%2F')
+  })
+
+  test('still returns a cross-site post to the page rather than a 403', async () => {
+    // Arrange
+    await createServer({ withCsrf: true })
+
+    // Act
+    const response = await server.inject({
+      method: 'POST',
+      url: '/cookies',
+      headers: { 'sec-fetch-site': 'cross-site' },
+      payload: { analytics: 'yes' }
+    })
+
+    // Assert
+    expect(response.statusCode).toBe(302)
+    expect(response.headers.location).toBe('/cookies')
+    expect(response.headers['set-cookie']).toBeUndefined()
+  })
+})