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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {
@@ -30,6 +30,7 @@
     "./nunjucks-context": "./src/nunjucks-context.js",
     "./proxy/setup-proxy": "./src/proxy/setup-proxy.js",
     "./redis-client": "./src/redis-client.js",
+    "./referrer-link": "./src/referrer-link.js",
     "./session-cache": "./src/session-cache.js",
     "./session-cache/cache-engine": "./src/session-cache/cache-engine.js",
     "./static-files": "./src/static-files.js",

package/src/duration.js

@@ -17,6 +17,7 @@ export const milliseconds = {
   tenSeconds: TEN * MILLIS_IN_SECOND,
   thirtySeconds: THIRTY * MILLIS_IN_SECOND,
   fiveMinutes: FIVE * SECONDS_IN_MINUTE * MILLIS_IN_SECOND,
+  oneHour: MINUTES_IN_HOUR * SECONDS_IN_MINUTE * MILLIS_IN_SECOND,
   fourHours: FOUR * MINUTES_IN_HOUR * SECONDS_IN_MINUTE * MILLIS_IN_SECOND,
   oneDay: HOURS_IN_DAY * MINUTES_IN_HOUR * SECONDS_IN_MINUTE * MILLIS_IN_SECOND,
   oneWeek:

package/src/nunjucks/components/search-form/search-form.test.js

@@ -55,6 +55,28 @@ describe('searchForm()', () => {
     expect(html).not.toContain('aria-describedby')
   })
 
+  test('carries hidden fields inside the form so they survive a submit', () => {
+    // Act
+    const html = render({
+      label: 'Search',
+      hiddenFields: [{ name: 'referrer', value: 'abc-123' }]
+    })
+
+    // Assert
+    expect(html).toContain(
+      '<input type="hidden" name="referrer" value="abc-123">'
+    )
+    expect(html.indexOf('<form')).toBeLessThan(html.indexOf('type="hidden"'))
+  })
+
+  test('renders no hidden fields when none are given', () => {
+    // Act
+    const html = render({ label: 'Search' })
+
+    // Assert
+    expect(html).not.toContain('type="hidden"')
+  })
+
   test('defaults the input name and id to "search"', () => {
     // Act
     const html = render({ label: 'Search' })

package/src/nunjucks/components/search-form/template.njk

@@ -12,6 +12,9 @@
   {%- endif -%}
 
   <form method="GET" class="lis-search-form">
+    {%- for field in params.hiddenFields -%}
+      <input type="hidden" name="{{ field.name }}" value="{{ field.value }}">
+    {%- endfor -%}
     <div class="lis-search-form__wrapper">
       <input
         class="govuk-input lis-search-form__input"

package/src/referrer-link.js

@@ -0,0 +1,159 @@
+/** @import { Request, Server } from '@hapi/hapi' */
+import { randomUUID } from 'node:crypto'
+
+import { milliseconds } from './duration.js'
+
+const idPattern =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+/**
+ * The browser sends the hub's public URL as the referrer, and the hub proxy
+ * passes the host it was called on as x-forwarded-host, so the two are
+ * compared to keep a link built from the referrer on the current domain.
+ *
+ * @param {Request} request
+ * @returns {string | undefined} the referrer's path and query, when it is on the same host as the request
+ */
+export function getSameHostReferrerPath(request) {
+  const { referer } = request.headers
+  if (!referer) {
+    return undefined
+  }
+
+  let refererUrl
+  try {
+    refererUrl = new URL(referer)
+  } catch {
+    return undefined
+  }
+
+  const requestHost = (
+    request.headers['x-forwarded-host'] ??
+    request.headers.host ??
+    ''
+  )
+    .split(',')[0]
+    .trim()
+
+  // A path starting with // would make the link protocol-relative, i.e.
+  // another site.
+  if (refererUrl.host !== requestHost || refererUrl.pathname.startsWith('//')) {
+    return undefined
+  }
+
+  return `${refererUrl.pathname}${refererUrl.search}`
+}
+
+/**
+ * @param {string} href
+ * @param {string} queryParam
+ * @param {string | null} id
+ * @returns {string} href with the referrer id appended, or unchanged when there is no id
+ */
+function appendReferrerId(href, queryParam, id) {
+  if (!id) {
+    return href
+  }
+  const separator = href.includes('?') ? '&' : '?'
+  return `${href}${separator}${queryParam}=${id}`
+}
+
+/**
+ * @param {Request} request
+ * @returns {string | null} the signed-in user's subject, which keys what is remembered for them
+ */
+function userKey(request) {
+  const sub = request.auth?.credentials?.user?.sub
+  return typeof sub === 'string' && sub.length > 0 ? sub : null
+}
+
+/**
+ * Remembers where a user came from so pages reached from a list can link
+ * back to it, including its query, after moving between related pages.
+ *
+ * On a request whose same-host referrer the caller allows, the referrer path
+ * is stored in the server cache under a new id, keyed with the user, and the
+ * page links to its related pages carrying `?<queryParam>=<id>`. A request
+ * carrying an id resolves it from the cache, for the same user only.
+ *
+ * @typedef {object} ReferrerLink
+ * @property {string | null} id the id to carry on links to related pages, or null when there is nothing to carry
+ * @property {string} href the back link: the remembered referrer, or the fallback
+ */
+
+/**
+ * @param {Server} server
+ * @param {object} options
+ * @param {string} options.cacheName a cache provisioned on the server
+ * @param {(path: string) => boolean} options.allow whether a same-host referrer path is one worth remembering
+ * @param {string} options.fallbackHref the back link when nothing is remembered
+ * @param {(request: Request) => boolean} [options.when] whether the request gets a back link at all; defaults to always
+ * @param {string} [options.queryParam] query parameter carrying the id; defaults to "referrer"
+ * @param {string} [options.segment] cache segment; defaults to "referrer-link"
+ * @param {number} [options.expiresIn] how long a remembered referrer lasts, in milliseconds; defaults to one hour
+ * @returns {{ resolve: (request: Request) => Promise<ReferrerLink | null>, link: (href: string, id: string | null) => string }}
+ */
+export function createReferrerLink(
+  server,
+  {
+    cacheName,
+    allow,
+    fallbackHref,
+    when = () => true,
+    queryParam = 'referrer',
+    segment = 'referrer-link',
+    expiresIn = milliseconds.oneHour
+  }
+) {
+  if (typeof cacheName !== 'string' || cacheName.length === 0) {
+    throw new TypeError('createReferrerLink() requires a cacheName')
+  }
+  if (typeof allow !== 'function') {
+    throw new TypeError('createReferrerLink() requires an allow function')
+  }
+  if (typeof fallbackHref !== 'string' || fallbackHref.length === 0) {
+    throw new TypeError('createReferrerLink() requires a fallbackHref')
+  }
+
+  const store = server.cache({ cache: cacheName, segment, expiresIn })
+
+  /**
+   * A route pre method: resolves the back link for the request. Null when
+   * `when` rules the request out, so the page shows no back link.
+   * @param {Request} request
+   * @returns {Promise<ReferrerLink | null>}
+   */
+  async function resolve(request) {
+    if (!when(request)) {
+      return null
+    }
+
+    const user = userKey(request)
+    const requestedId = request.query?.[queryParam]
+
+    if (
+      user &&
+      typeof requestedId === 'string' &&
+      idPattern.test(requestedId)
+    ) {
+      const remembered = await store.get(`${user}:${requestedId}`)
+      if (typeof remembered === 'string') {
+        return { id: requestedId, href: remembered }
+      }
+    }
+
+    const referrerPath = getSameHostReferrerPath(request)
+    if (user && referrerPath && allow(referrerPath)) {
+      const id = randomUUID()
+      await store.set(`${user}:${id}`, referrerPath)
+      return { id, href: referrerPath }
+    }
+
+    return { id: null, href: fallbackHref }
+  }
+
+  return {
+    resolve,
+    link: (href, id) => appendReferrerId(href, queryParam, id)
+  }
+}

package/src/referrer-link.test.js

@@ -0,0 +1,280 @@
+import { afterEach, beforeAll, describe, expect, test, vi } from 'vitest'
+
+import { createReferrerLink, getSameHostReferrerPath } from './referrer-link.js'
+
+const uuidPattern =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+const mocks = {
+  get: vi.fn(),
+  set: vi.fn(),
+  cache: vi.fn()
+}
+
+const server = { cache: mocks.cache }
+
+function createRequest({ query = {}, headers = {}, sub = 'user-1' } = {}) {
+  return {
+    query,
+    headers: { 'x-forwarded-host': 'back-office.lis.defra', ...headers },
+    auth: { credentials: { user: sub ? { sub } : undefined } }
+  }
+}
+
+describe('getSameHostReferrerPath()', () => {
+  test('it returns the path and query of a referrer on the forwarded host', () => {
+    // Arrange
+    const request = {
+      headers: {
+        referer: 'https://back-office.lis.defra/holdings?search=oak&page=2',
+        'x-forwarded-host': 'back-office.lis.defra',
+        host: 'localhost:3221'
+      }
+    }
+
+    // Act
+    const result = getSameHostReferrerPath(request)
+
+    // Assert
+    expect(result).toBe('/holdings?search=oak&page=2')
+  })
+
+  test('it ignores a referrer on another host', () => {
+    // Arrange
+    const request = {
+      headers: {
+        referer: 'https://evil.example/holdings',
+        'x-forwarded-host': 'back-office.lis.defra'
+      }
+    }
+
+    // Act
+    const result = getSameHostReferrerPath(request)
+
+    // Assert
+    expect(result).toBeUndefined()
+  })
+
+  test('it ignores a referrer path that would point at another site', () => {
+    // Arrange
+    const request = {
+      headers: {
+        referer: 'https://back-office.lis.defra//evil.example',
+        'x-forwarded-host': 'back-office.lis.defra'
+      }
+    }
+
+    // Act
+    const result = getSameHostReferrerPath(request)
+
+    // Assert
+    expect(result).toBeUndefined()
+  })
+
+  test('it returns undefined when there is no referrer or it is not a URL', () => {
+    // Arrange
+    const noReferrer = { headers: { host: 'back-office.lis.defra' } }
+    const badReferrer = {
+      headers: { referer: 'not a url', host: 'back-office.lis.defra' }
+    }
+
+    // Act
+    const first = getSameHostReferrerPath(noReferrer)
+    const second = getSameHostReferrerPath(badReferrer)
+
+    // Assert
+    expect(first).toBeUndefined()
+    expect(second).toBeUndefined()
+  })
+})
+
+describe('createReferrerLink()', () => {
+  beforeAll(() => {
+    mocks.cache.mockReturnValue({ get: mocks.get, set: mocks.set })
+    mocks.get.mockResolvedValue(null)
+    mocks.set.mockResolvedValue(undefined)
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  function createSubject(overrides = {}) {
+    return createReferrerLink(server, {
+      cacheName: 'test-cache',
+      allow: (path) => path === '/holdings' || path.startsWith('/holdings?'),
+      fallbackHref: '/holdings',
+      ...overrides
+    })
+  }
+
+  test('it provisions a cache segment with the given name and expiry', () => {
+    // Arrange
+    const expiresIn = 1234
+
+    // Act
+    createSubject({ segment: 'list-referrer', expiresIn })
+
+    // Assert
+    expect(mocks.cache).toHaveBeenCalledWith({
+      cache: 'test-cache',
+      segment: 'list-referrer',
+      expiresIn
+    })
+  })
+
+  test('it throws when the cache name, allow rule or fallback is missing', () => {
+    // Arrange
+    const incomplete = [
+      { allow: () => true, fallbackHref: '/x' },
+      { cacheName: 'c', fallbackHref: '/x' },
+      { cacheName: 'c', allow: () => true }
+    ]
+
+    // Act
+    const errors = incomplete.map((options) => {
+      try {
+        createReferrerLink(server, options)
+        return undefined
+      } catch (e) {
+        return e
+      }
+    })
+
+    // Assert
+    expect(errors.map((e) => e?.message)).toEqual([
+      'createReferrerLink() requires a cacheName',
+      'createReferrerLink() requires an allow function',
+      'createReferrerLink() requires a fallbackHref'
+    ])
+  })
+
+  test('it remembers an allowed same-host referrer under a new id for the user', async () => {
+    // Arrange
+    const subject = createSubject()
+    const request = createRequest({
+      headers: {
+        referer: 'https://back-office.lis.defra/holdings?search=oak&page=2'
+      }
+    })
+
+    // Act
+    const result = await subject.resolve(request)
+
+    // Assert
+    expect(result.href).toBe('/holdings?search=oak&page=2')
+    expect(result.id).toMatch(uuidPattern)
+    expect(mocks.set).toHaveBeenCalledWith(
+      `user-1:${result.id}`,
+      '/holdings?search=oak&page=2'
+    )
+  })
+
+  test('it resolves a carried id from the cache for the same user', async () => {
+    // Arrange
+    const subject = createSubject()
+    const id = '0f0f0f0f-0f0f-4f0f-8f0f-0f0f0f0f0f0f'
+    mocks.get.mockResolvedValueOnce('/holdings?search=oak')
+    const request = createRequest({ query: { referrer: id } })
+
+    // Act
+    const result = await subject.resolve(request)
+
+    // Assert
+    expect(mocks.get).toHaveBeenCalledWith(`user-1:${id}`)
+    expect(result).toEqual({ id, href: '/holdings?search=oak' })
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
+  test('it falls back when a carried id is unknown, expired or not a uuid', async () => {
+    // Arrange
+    const subject = createSubject()
+    const unknown = createRequest({
+      query: { referrer: '0f0f0f0f-0f0f-4f0f-8f0f-0f0f0f0f0f0f' }
+    })
+    const malformed = createRequest({ query: { referrer: '../etc' } })
+
+    // Act
+    const first = await subject.resolve(unknown)
+    const second = await subject.resolve(malformed)
+
+    // Assert
+    expect(first).toEqual({ id: null, href: '/holdings' })
+    expect(second).toEqual({ id: null, href: '/holdings' })
+    expect(mocks.get).toHaveBeenCalledTimes(1)
+  })
+
+  test('it falls back when the referrer is not allowed, off-host or missing', async () => {
+    // Arrange
+    const subject = createSubject()
+    const notAllowed = createRequest({
+      headers: { referer: 'https://back-office.lis.defra/cattle/holdings/1' }
+    })
+    const offHost = createRequest({
+      headers: { referer: 'https://evil.example/holdings' }
+    })
+    const missing = createRequest()
+
+    // Act
+    const results = await Promise.all(
+      [notAllowed, offHost, missing].map((request) => subject.resolve(request))
+    )
+
+    // Assert
+    expect(results).toEqual([
+      { id: null, href: '/holdings' },
+      { id: null, href: '/holdings' },
+      { id: null, href: '/holdings' }
+    ])
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
+  test('it never remembers or resolves anything for a request without a user', async () => {
+    // Arrange
+    const subject = createSubject()
+    const request = createRequest({
+      sub: null,
+      query: { referrer: '0f0f0f0f-0f0f-4f0f-8f0f-0f0f0f0f0f0f' },
+      headers: { referer: 'https://back-office.lis.defra/holdings' }
+    })
+
+    // Act
+    const result = await subject.resolve(request)
+
+    // Assert
+    expect(result).toEqual({ id: null, href: '/holdings' })
+    expect(mocks.get).not.toHaveBeenCalled()
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
+  test('it returns null when the request is ruled out by "when"', async () => {
+    // Arrange
+    const subject = createSubject({ when: () => false })
+    const request = createRequest({
+      headers: { referer: 'https://back-office.lis.defra/holdings' }
+    })
+
+    // Act
+    const result = await subject.resolve(request)
+
+    // Assert
+    expect(result).toBeNull()
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
+  test('it appends the id to a link, after any existing query', () => {
+    // Arrange
+    const subject = createSubject({ queryParam: 'from' })
+    const id = '0f0f0f0f-0f0f-4f0f-8f0f-0f0f0f0f0f0f'
+
+    // Act
+    const plain = subject.link('/cattle/holdings/22/001/0001', id)
+    const withQuery = subject.link('/cattle/holdings/x/animals?page=2', id)
+    const noId = subject.link('/cattle/holdings/22/001/0001', null)
+
+    // Assert
+    expect(plain).toBe(`/cattle/holdings/22/001/0001?from=${id}`)
+    expect(withQuery).toBe(`/cattle/holdings/x/animals?page=2&from=${id}`)
+    expect(noId).toBe('/cattle/holdings/22/001/0001')
+  })
+})