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

package/src/csrf/index.js

@@ -0,0 +1,245 @@
+/** @import { Plugin, Request, ResponseToolkit } from '@hapi/hapi' */
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+
+import Boom from '@hapi/boom'
+import { logger } from '@defra/lis-hubs-infra-core'
+
+import {
+  CSRF_FIELD_NAME,
+  CSRF_PLUGIN_NAME,
+  CSRF_SESSION_KEY,
+  CSRF_TOKEN_HEADER
+} from './constants.js'
+import { isSameOriginRequest } from './same-origin.js'
+
+export {
+  CSRF_FIELD_NAME,
+  CSRF_PLUGIN_NAME,
+  CSRF_SESSION_KEY,
+  CSRF_TOKEN_HEADER
+}
+export { isSameOriginRequest }
+
+const TOKEN_BYTES = 32
+const SAFE_METHODS = new Set(['get', 'head', 'options'])
+
+const tokenResolvers = {
+  session: resolveSessionToken,
+  header: resolveHeaderToken
+}
+
+/**
+ * @typedef {object} CsrfPluginOptions
+ * @property {'session' | 'header'} tokenSource - `session` for a hub, which
+ * keeps the token in its yar session; `header` for a spoke, which gets it from
+ * the hub in the `x-lis-csrf-token` header
+ */
+
+/**
+ * @typedef {(request: Request, h: ResponseToolkit) => unknown} CsrfFailAction
+ * Answers a request that failed a check, in place of the 403. It must respond
+ * (e.g. `h.redirect('/')`) or return an error: `h.continue` is refused with a
+ * 403 all the same, so a failed request never reaches the handler.
+ */
+
+/**
+ * @typedef {false | { enabled?: boolean, token?: boolean, failAction?: CsrfFailAction }} CsrfRouteOptions
+ * Route `options.plugins['lis-csrf']`: `false` or `{ enabled: false }` skips
+ * every check; `{ token: false }` keeps the origin check only; `failAction`
+ * answers a failed check in place of the 403, after the warning is logged.
+ */
+
+/**
+ * A session gets a token only once signed in, so an anonymous visitor is not
+ * given a session for it.
+ * @param {Request} request
+ * @returns {string | undefined}
+ */
+function resolveSessionToken(request) {
+  const stored = request.yar?.get(CSRF_SESSION_KEY)
+
+  if (typeof stored === 'string' && stored !== '') {
+    return stored
+  }
+
+  if (!request.auth.isAuthenticated || !request.yar) {
+    return undefined
+  }
+
+  const token = randomBytes(TOKEN_BYTES).toString('base64url')
+  request.yar.set(CSRF_SESSION_KEY, token)
+
+  return token
+}
+
+/**
+ * @param {Request} request
+ * @returns {string | undefined}
+ */
+function resolveHeaderToken(request) {
+  const token = request.headers[CSRF_TOKEN_HEADER]
+
+  return typeof token === 'string' && token !== '' ? token : undefined
+}
+
+/**
+ * @param {Request} request
+ * @returns {{ enabled: boolean, checkToken: boolean, failAction?: CsrfFailAction }}
+ */
+function getRouteSettings(request) {
+  const settings = request.route.settings.plugins?.[CSRF_PLUGIN_NAME]
+
+  if (settings === false || settings?.enabled === false) {
+    return { enabled: false, checkToken: false }
+  }
+
+  return {
+    enabled: true,
+    checkToken: settings?.token !== false,
+    ...(typeof settings?.failAction === 'function' && {
+      failAction: settings.failAction
+    })
+  }
+}
+
+/**
+ * Only a parsed form or JSON body can carry the field: a streamed or raw body
+ * fails the check unless the route opted out of it.
+ * @param {unknown} payload
+ * @returns {payload is Record<string, unknown>}
+ */
+function isParsedObject(payload) {
+  if (typeof payload !== 'object' || payload === null) {
+    return false
+  }
+
+  const prototype = Object.getPrototypeOf(payload)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * @param {unknown} submitted
+ * @param {string | undefined} expected
+ * @returns {boolean}
+ */
+function tokensMatch(submitted, expected) {
+  if (
+    typeof submitted !== 'string' ||
+    typeof expected !== 'string' ||
+    expected === ''
+  ) {
+    return false
+  }
+
+  const submittedBytes = Buffer.from(submitted)
+  const expectedBytes = Buffer.from(expected)
+
+  return (
+    submittedBytes.length === expectedBytes.length &&
+    timingSafeEqual(submittedBytes, expectedBytes)
+  )
+}
+
+/**
+ * @param {Request} request
+ * @param {ResponseToolkit} h
+ * @param {'origin' | 'token'} check
+ * @param {CsrfFailAction} [failAction]
+ * @returns {Promise<unknown>} the route's failAction response, taken over, or a 403
+ */
+async function reject(request, h, check, failAction) {
+  logger.warn(
+    {
+      http: { request: { method: request.method } },
+      url: { path: request.path },
+      event: { reason: `csrf-${check}` }
+    },
+    `CSRF ${check} check failed`
+  )
+
+  if (!failAction) {
+    return Boom.forbidden()
+  }
+
+  const result = await failAction(request, h)
+
+  if (result === h.continue) {
+    return Boom.forbidden()
+  }
+
+  return typeof result?.takeover === 'function' ? result.takeover() : result
+}
+
+/**
+ * @param {(request: Request) => string | undefined} resolveToken
+ * @returns {(request: Request, h: ResponseToolkit) => Promise<unknown>}
+ */
+function createOnPostAuth(resolveToken) {
+  return async function protectAgainstCsrf(request, h) {
+    const token = resolveToken(request)
+    request.plugins[CSRF_PLUGIN_NAME] = { token }
+
+    const { enabled, checkToken, failAction } = getRouteSettings(request)
+
+    if (!enabled || SAFE_METHODS.has(request.method)) {
+      return h.continue
+    }
+
+    if (!isSameOriginRequest(request)) {
+      return reject(request, h, 'origin', failAction)
+    }
+
+    if (!checkToken) {
+      return h.continue
+    }
+
+    const { payload } = request
+
+    if (
+      !isParsedObject(payload) ||
+      !tokensMatch(payload[CSRF_FIELD_NAME], token)
+    ) {
+      return reject(request, h, 'token', failAction)
+    }
+
+    // Route payload validation runs after onPostAuth, so it never sees the field.
+    delete payload[CSRF_FIELD_NAME]
+
+    return h.continue
+  }
+}
+
+/**
+ * Drops the session's token, so the next signed-in request is issued a new
+ * one. Call it when a user signs in, unless the session is reset there.
+ * @param {Request} request
+ */
+export function clearCsrfToken(request) {
+  request.yar?.clear(CSRF_SESSION_KEY)
+  request.plugins[CSRF_PLUGIN_NAME] = {}
+}
+
+/**
+ * Refuses a POST, PUT, PATCH or DELETE that is not from this origin or does
+ * not carry the token in its `_csrf` field. The token is resolved after
+ * authentication on every request and published at
+ * `request.plugins['lis-csrf'].token` for views and the hub proxy.
+ * @type {Plugin<CsrfPluginOptions>}
+ */
+export const csrfPlugin = {
+  name: CSRF_PLUGIN_NAME,
+  register(server, { tokenSource } = {}) {
+    if (!Object.hasOwn(tokenResolvers, tokenSource ?? '')) {
+      throw new Error(
+        `${CSRF_PLUGIN_NAME} tokenSource must be 'session' or 'header'`
+      )
+    }
+
+    if (tokenSource === 'session') {
+      server.dependency('@hapi/yar')
+    }
+
+    server.ext('onPostAuth', createOnPostAuth(tokenResolvers[tokenSource]))
+  }
+}

package/src/csrf/index.test.js

@@ -0,0 +1,284 @@
+import { randomBytes } from 'node:crypto'
+
+import Boom from '@hapi/boom'
+import hapi from '@hapi/hapi'
+import yar from '@hapi/yar'
+import Joi from 'joi'
+import { afterEach, describe, expect, test, vi } from 'vitest'
+
+import {
+  CSRF_FIELD_NAME,
+  CSRF_PLUGIN_NAME,
+  CSRF_TOKEN_HEADER,
+  clearCsrfToken,
+  csrfPlugin
+} from './index.js'
+
+// The shared logger's methods are getters, so it cannot be spied on.
+const { logger } = vi.hoisted(() => ({ logger: { warn: vi.fn() } }))
+
+vi.mock('@defra/lis-hubs-infra-core', () => ({ logger }))
+
+const sameOrigin = { host: 'lis.test', 'sec-fetch-site': 'same-origin' }
+const signedIn = { 'x-test-user': 'keeper' }
+
+const tokenRoute = {
+  method: 'GET',
+  path: '/token',
+  handler: (request) => ({
+    token: request.plugins[CSRF_PLUGIN_NAME].token ?? null
+  })
+}
+
+function echoRoute(options = {}) {
+  return {
+    method: 'POST',
+    path: '/submit',
+    options,
+    handler: (request) => request.payload ?? { streamed: true }
+  }
+}
+
+let server
+
+async function createServer({ tokenSource, routes }) {
+  server = hapi.server()
+  server.validator(Joi)
+  await server.register({
+    plugin: yar,
+    options: {
+      storeBlank: false,
+      maxCookieSize: 0,
+      cookieOptions: {
+        password: randomBytes(32).toString('hex'),
+        isSecure: false
+      }
+    }
+  })
+  server.auth.scheme('test', () => ({
+    authenticate: (request, h) =>
+      request.headers['x-test-user']
+        ? h.authenticated({ credentials: { user: { id: 'keeper' } } })
+        : h.unauthenticated(Boom.unauthorized())
+  }))
+  server.auth.strategy('test', 'test')
+  server.auth.default({ strategy: 'test', mode: 'try' })
+  await server.register({ plugin: csrfPlugin, options: { tokenSource } })
+  server.route(routes)
+  await server.initialize()
+}
+
+async function signInAndGetToken() {
+  const response = await server.inject({
+    method: 'GET',
+    url: '/token',
+    headers: signedIn
+  })
+
+  return {
+    token: response.result.token,
+    cookie: response.headers['set-cookie'][0].split(';')[0]
+  }
+}
+
+describe('csrfPlugin', () => {
+  afterEach(async () => {
+    vi.clearAllMocks()
+    await server?.stop()
+    server = undefined
+  })
+
+  describe('registration', () => {
+    test.each([undefined, 'cookie', 'constructor'])(
+      'refuses tokenSource %s',
+      async (tokenSource) => {
+        // Arrange
+        let error
+
+        // Act
+        try {
+          await createServer({ tokenSource, routes: [tokenRoute] })
+        } catch (e) {
+          error = e
+        }
+
+        // Assert
+        expect(error.message).toBe(
+          "lis-csrf tokenSource must be 'session' or 'header'"
+        )
+      }
+    )
+
+    test('requires yar in session mode', async () => {
+      // Arrange
+      server = hapi.server()
+      await server.register({
+        plugin: csrfPlugin,
+        options: { tokenSource: 'session' }
+      })
+      let error
+
+      // Act
+      try {
+        await server.initialize()
+      } catch (e) {
+        error = e
+      }
+
+      // Assert
+      expect(error.message).toContain('@hapi/yar')
+    })
+  })
+
+  describe('session token', () => {
+    test('issues a 32-byte base64url token to a signed-in session', async () => {
+      // Arrange
+      await createServer({ tokenSource: 'session', routes: [tokenRoute] })
+
+      // Act
+      const response = await server.inject({
+        method: 'GET',
+        url: '/token',
+        headers: signedIn
+      })
+
+      // Assert
+      expect(response.result.token).toMatch(/^[\w-]{43}$/)
+      expect(response.headers['set-cookie']).toBeDefined()
+    })
+
+    test('reuses the session token on later requests', async () => {
+      // Arrange
+      await createServer({ tokenSource: 'session', routes: [tokenRoute] })
+      const { token, cookie } = await signInAndGetToken()
+
+      // Act
+      const response = await server.inject({
+        method: 'GET',
+        url: '/token',
+        headers: { ...signedIn, cookie }
+      })
+
+      // Assert
+      expect(response.result.token).toBe(token)
+    })
+
+    test('gives an anonymous visitor no token and no session', async () => {
+      // Arrange
+      await createServer({ tokenSource: 'session', routes: [tokenRoute] })
+
+      // Act
+      const response = await server.inject({ method: 'GET', url: '/token' })
+
+      // Assert
+      expect(response.result.token).toBeNull()
+      expect(response.headers['set-cookie']).toBeUndefined()
+    })
+
+    test('accepts a same-origin post carrying the session token', async () => {
+      // Arrange
+      await createServer({
+        tokenSource: 'session',
+        routes: [tokenRoute, echoRoute()]
+      })
+      const { token, cookie } = await signInAndGetToken()
+
+      // Act
+      const response = await server.inject({
+        method: 'POST',
+        url: '/submit',
+        headers: { ...signedIn, ...sameOrigin, cookie },
+        payload: { [CSRF_FIELD_NAME]: token, name: 'Daisy' }
+      })
+
+      // Assert
+      expect(response.statusCode).toBe(200)
+      expect(response.result).toEqual({ name: 'Daisy' })
+    })
+
+    test('issues a new token once the old one is cleared', async () => {
+      // Arrange
+      await createServer({
+        tokenSource: 'session',
+        routes: [
+          tokenRoute,
+          {
+            method: 'GET',
+            path: '/clear',
+            handler(request) {
+              clearCsrfToken(request)
+              return { token: request.plugins[CSRF_PLUGIN_NAME].token ?? null }
+            }
+          }
+        ]
+      })
+      const { token, cookie } = await signInAndGetToken()
+
+      // Act
+      const cleared = await server.inject({
+        method: 'GET',
+        url: '/clear',
+        headers: { ...signedIn, cookie }
+      })
+      const reissued = await server.inject({
+        method: 'GET',
+        url: '/token',
+        headers: { ...signedIn, cookie }
+      })
+
+      // Assert
+      expect(cleared.result.token).toBeNull()
+      expect(reissued.result.token).toMatch(/^[\w-]{43}$/)
+      expect(reissued.result.token).not.toBe(token)
+    })
+  })
+
+  describe('header token', () => {
+    test('publishes the token from the hub header', async () => {
+      // Arrange
+      await createServer({ tokenSource: 'header', routes: [tokenRoute] })
+
+      // Act
+      const response = await server.inject({
+        method: 'GET',
+        url: '/token',
+        headers: { [CSRF_TOKEN_HEADER]: 'hub-token' }
+      })
+
+      // Assert
+      expect(response.result.token).toBe('hub-token')
+    })
+
+    test.each([
+      ['a matching token', 'hub-token', 'hub-token', 200],
+      ['a different token of the same length', 'hub-token', 'bad-token', 403],
+      ['a shorter token', 'hub-token', 'hub', 403],
+      ['a longer token', 'hub-token', 'hub-token-and-more', 403],
+      ['no submitted token', 'hub-token', undefined, 403],
+      ['two submitted tokens', 'hub-token', ['hub-token', 'hub-token'], 403],
+      ['no hub token', undefined, 'hub-token', 403],
+      ['two empty tokens', '', '', 403]
+    ])(
+      'answers a same-origin post with %s',
+      async (_label, headerToken, submitted, expectedStatus) => {
+        // Arrange
+        await createServer({ tokenSource: 'header', routes: [echoRoute()] })
+        const headers = {
+          ...sameOrigin,
+          ...(headerToken !== undefined && { [CSRF_TOKEN_HEADER]: headerToken })
+        }
+
+        // Act
+        const response = await server.inject({
+          method: 'POST',
+          url: '/submit',
+          headers,
+          payload: { [CSRF_FIELD_NAME]: submitted, name: 'Daisy' }
+        })
+
+        // Assert
+        expect(response.statusCode).toBe(expectedStatus)
+      }
+    )
+  })
+})

package/src/csrf/same-origin.js

@@ -0,0 +1,42 @@
+/** @import { Request } from '@hapi/hapi' */
+
+/**
+ * @param {Request} request
+ * @returns {string} the host the browser addressed, as the hub proxy forwards it
+ */
+export function getRequestHost(request) {
+  return (request.headers['x-forwarded-host'] ?? request.headers.host ?? '')
+    .split(',')[0]
+    .trim()
+}
+
+/**
+ * Whether a request came from a page on this origin, by the browser's own
+ * signals. Same-site is not enough: deployed hubs share a platform domain with
+ * other tenants. Sec-Fetch-Site `none` is a navigation the user started (e.g.
+ * from the address bar), which can never be a form posted from a page, so it
+ * fails too. A request with neither header fails: current browsers send at
+ * least one of them on a form POST, but those that send neither on a
+ * same-origin one (IE11, Firefox before 70) are refused.
+ * @param {Request} request
+ * @returns {boolean}
+ */
+export function isSameOriginRequest(request) {
+  const fetchSite = request.headers['sec-fetch-site']
+
+  if (typeof fetchSite === 'string') {
+    return fetchSite === 'same-origin'
+  }
+
+  const origin = request.headers.origin
+
+  if (typeof origin !== 'string' || origin === '') {
+    return false
+  }
+
+  try {
+    return new URL(origin).host === getRequestHost(request)
+  } catch {
+    return false
+  }
+}

package/src/csrf/same-origin.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'vitest'
+
+import { getRequestHost, isSameOriginRequest } from './same-origin.js'
+
+describe('isSameOriginRequest()', () => {
+  test.each([
+    ['sec-fetch-site same-origin', { 'sec-fetch-site': 'same-origin' }, 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],
+    [
+      'sec-fetch-site same-site with a matching origin',
+      { 'sec-fetch-site': 'same-site', origin: 'https://lis.test' },
+      false
+    ],
+    ['no signals at all', {}, false],
+    ['an empty origin', { origin: '' }, false],
+    ['matching origin', { origin: 'https://lis.test' }, true],
+    ['foreign origin', { origin: 'https://evil.example' }, false],
+    ['sibling subdomain origin', { origin: 'https://other.lis.test' }, false],
+    ['opaque origin', { origin: 'null' }, 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
+    ],
+    [
+      'origin matching only the internal host behind a proxy',
+      {
+        host: 'internal:3001',
+        'x-forwarded-host': 'lis.test',
+        origin: 'https://internal:3001'
+      },
+      false
+    ]
+  ])('handles %s', (_label, headers, expected) => {
+    // Arrange
+    const request = { headers: { host: 'lis.test', ...headers } }
+
+    // Act
+    const actual = isSameOriginRequest(request)
+
+    // Assert
+    expect(actual).toBe(expected)
+  })
+})
+
+describe('getRequestHost()', () => {
+  test.each([
+    ['the host header', { host: 'lis.test' }, 'lis.test'],
+    [
+      'the first forwarded host',
+      { host: 'internal:3001', 'x-forwarded-host': 'lis.test, proxy.test' },
+      'lis.test'
+    ],
+    ['nothing when neither is sent', {}, '']
+  ])('returns %s', (_label, headers, expected) => {
+    // Arrange
+    const request = { headers }
+
+    // Act
+    const actual = getRequestHost(request)
+
+    // Assert
+    expect(actual).toBe(expected)
+  })
+})