@defra/forms-engine-plugin 0.0.1

package/src/server/index.ts

@@ -0,0 +1,140 @@
+import { Engine as CatboxMemory } from '@hapi/catbox-memory'
+import { Engine as CatboxRedis } from '@hapi/catbox-redis'
+import hapi, {
+  type Request,
+  type ResponseToolkit,
+  type ServerOptions
+} from '@hapi/hapi'
+import inert from '@hapi/inert'
+import Scooter from '@hapi/scooter'
+import Wreck from '@hapi/wreck'
+import Schmervice from '@hapipal/schmervice'
+import blipp from 'blipp'
+import { ProxyAgent } from 'proxy-agent'
+
+import { config } from '~/src/config/index.js'
+import { requestLogger } from '~/src/server/common/helpers/logging/request-logger.js'
+import { requestTracing } from '~/src/server/common/helpers/logging/request-tracing.js'
+import { buildRedisClient } from '~/src/server/common/helpers/redis-client.js'
+import { configureBlankiePlugin } from '~/src/server/plugins/blankie.js'
+import { configureCrumbPlugin } from '~/src/server/plugins/crumb.js'
+import { configureEnginePlugin } from '~/src/server/plugins/engine/index.js'
+import pluginErrorPages from '~/src/server/plugins/errorPages.js'
+import { plugin as pluginViews } from '~/src/server/plugins/nunjucks/index.js'
+import pluginPulse from '~/src/server/plugins/pulse.js'
+import pluginRouter from '~/src/server/plugins/router.js'
+import pluginSession from '~/src/server/plugins/session.js'
+import { prepareSecureContext } from '~/src/server/secure-context.js'
+import { CacheService } from '~/src/server/services/index.js'
+import { type RouteConfig } from '~/src/server/types.js'
+
+const proxyAgent = new ProxyAgent()
+
+Wreck.agents = {
+  https: proxyAgent,
+  http: proxyAgent,
+  httpsAllowUnauthorized: proxyAgent
+}
+
+const serverOptions = (): ServerOptions => {
+  const serverOptions: ServerOptions = {
+    debug: { request: [`${config.get('isDevelopment')}`] },
+    port: config.get('port'),
+    router: {
+      stripTrailingSlash: true
+    },
+    routes: {
+      validate: {
+        options: {
+          abortEarly: false
+        }
+      },
+      security: {
+        hsts: {
+          maxAge: 31536000,
+          includeSubDomains: true,
+          preload: false
+        },
+        xss: 'enabled',
+        noSniff: true,
+        xframe: true
+      }
+    },
+    cache: [
+      {
+        name: 'session',
+        engine: config.get('isTest')
+          ? new CatboxMemory()
+          : new CatboxRedis({
+              client: buildRedisClient()
+            })
+      }
+    ]
+  }
+
+  return serverOptions
+}
+
+export async function createServer(routeConfig?: RouteConfig) {
+  const server = hapi.server(serverOptions())
+
+  await server.register(requestLogger)
+
+  if (config.get('isProduction')) {
+    prepareSecureContext(server)
+  }
+
+  const pluginEngine = await configureEnginePlugin(routeConfig)
+  const pluginCrumb = configureCrumbPlugin(routeConfig)
+  const pluginBlankie = configureBlankiePlugin()
+
+  await server.register(pluginSession)
+  await server.register(pluginPulse)
+  await server.register(inert)
+  await server.register(Scooter)
+  await server.register(pluginBlankie)
+  await server.register(pluginCrumb)
+  await server.register(Schmervice)
+
+  server.registerService(CacheService)
+
+  server.ext('onPreResponse', (request: Request, h: ResponseToolkit) => {
+    const { response } = request
+
+    if ('isBoom' in response) {
+      return h.continue
+    }
+
+    // Prevent search engine indexing
+    response.header('x-robots-tag', 'noindex, nofollow')
+
+    // Disable cache to ensure back/foward navigation updates progress
+    if (
+      !request.path.startsWith('/javascripts/') &&
+      !request.path.startsWith('/stylesheets/') &&
+      !request.path.startsWith('/assets/')
+    ) {
+      response.header('cache-control', 'no-store')
+    }
+
+    return h.continue
+  })
+
+  await server.register(pluginViews)
+  await server.register(pluginEngine)
+  await server.register(pluginRouter)
+  await server.register(pluginErrorPages)
+  await server.register(blipp)
+  await server.register(requestTracing)
+
+  server.state('cookieConsent', {
+    ttl: 365 * 24 * 60 * 60 * 1000, // 1 year in ms
+    clearInvalid: true,
+    isHttpOnly: false,
+    isSecure: config.get('isProduction'),
+    path: '/',
+    encoding: 'none' // handle this inside the application so we can share frontend/backend cookie modification
+  })
+
+  return server
+}

package/src/server/plugins/blankie.test.ts

@@ -0,0 +1,73 @@
+import { config } from '~/src/config/index.js'
+import { configureBlankiePlugin } from '~/src/server/plugins/blankie.js'
+
+describe('Server Blankie Plugin', () => {
+  test('configuration default options are provided', () => {
+    config.set('googleAnalyticsTrackingId', '')
+
+    const { options } = configureBlankiePlugin()
+
+    expect(options).toEqual({
+      defaultSrc: ['self'],
+      fontSrc: ['self', 'data:'],
+      frameSrc: ['self', 'data:'],
+      connectSrc: ['self', 'https://test-uploader.cdp-int.defra.cloud'],
+      scriptSrc: ['self', 'strict-dynamic', 'unsafe-inline'],
+      styleSrc: ['self', 'unsafe-inline'],
+      imgSrc: ['self'],
+      generateNonces: true
+    })
+  })
+
+  test('configuration default and GA options are provided', () => {
+    config.set('googleAnalyticsTrackingId', '12345')
+
+    const { options } = configureBlankiePlugin()
+
+    expect(options).toEqual({
+      defaultSrc: ['self'],
+      fontSrc: ['self', 'data:'],
+      frameSrc: ['self', 'data:'],
+      connectSrc: [
+        'self',
+        'https://*.google-analytics.com',
+        'https://*.analytics.google.com',
+        'https://*.googletagmanager.com',
+        'https://test-uploader.cdp-int.defra.cloud'
+      ],
+      scriptSrc: [
+        'self',
+        'strict-dynamic',
+        'unsafe-inline',
+        'https://*.googletagmanager.com'
+      ],
+      styleSrc: ['self', 'unsafe-inline'],
+      imgSrc: [
+        'self',
+        'https://*.google-analytics.com',
+        'https://*.googletagmanager.com'
+      ],
+      generateNonces: true
+    })
+  })
+
+  test('configuration includes uploaderUrl when provided', () => {
+    config.set('googleAnalyticsTrackingId', '')
+    config.set('uploaderUrl', 'https://some-random-uploader.example.com')
+
+    const { options } = configureBlankiePlugin()
+
+    expect(options?.connectSrc).toContain(
+      'https://some-random-uploader.example.com'
+    )
+  })
+
+  test('configuration does not include uploaderUrl when not provided', () => {
+    config.set('googleAnalyticsTrackingId', '')
+    config.set('uploaderUrl', '')
+
+    const { options } = configureBlankiePlugin()
+
+    expect(options?.connectSrc).toEqual(['self'])
+  })
+})

package/src/server/plugins/blankie.ts

@@ -0,0 +1,48 @@
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import Blankie from 'blankie'
+
+import { config } from '~/src/config/index.js'
+
+const googleAnalyticsOptions = {
+  scriptSrc: ['https://*.googletagmanager.com'],
+  imgSrc: ['https://*.google-analytics.com', 'https://*.googletagmanager.com'],
+  connectSrc: [
+    'https://*.google-analytics.com',
+    'https://*.analytics.google.com',
+    'https://*.googletagmanager.com'
+  ]
+}
+
+export const configureBlankiePlugin = (): ServerRegisterPluginObject<
+  Record<string, boolean | string | string[]>
+> => {
+  const gaTrackingId = config.get('googleAnalyticsTrackingId')
+  const uploaderUrl = config.get('uploaderUrl')
+
+  /*
+  Note that unsafe-inline is a fallback for old browsers that don't support nonces. It will be ignored by modern browsers as the nonce is provided.
+  */
+  return {
+    plugin: Blankie,
+    options: {
+      defaultSrc: ['self'],
+      fontSrc: ['self', 'data:'],
+      connectSrc: [
+        ['self'],
+        gaTrackingId ? googleAnalyticsOptions.connectSrc : [],
+        uploaderUrl ? [uploaderUrl] : []
+      ].flat(),
+      scriptSrc: [
+        ['self', 'strict-dynamic', 'unsafe-inline'],
+        gaTrackingId ? googleAnalyticsOptions.scriptSrc : []
+      ].flat(),
+      styleSrc: ['self', 'unsafe-inline'],
+      imgSrc: [
+        ['self'],
+        gaTrackingId ? googleAnalyticsOptions.imgSrc : []
+      ].flat(),
+      frameSrc: ['self', 'data:'],
+      generateNonces: true
+    }
+  }
+}

package/src/server/plugins/crumb.ts

@@ -0,0 +1,20 @@
+import crumb, { type RegisterOptions } from '@hapi/crumb'
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+
+import { config } from '~/src/config/index.js'
+import { type RouteConfig } from '~/src/server/types.js'
+
+export const configureCrumbPlugin = (
+  routeConfig?: RouteConfig
+): ServerRegisterPluginObject<RegisterOptions> => {
+  return {
+    plugin: crumb,
+    options: {
+      logUnauthorized: true,
+      enforce: routeConfig?.enforceCsrf ?? config.get('enforceCsrf'),
+      cookieOptions: {
+        isSecure: config.get('isProduction')
+      }
+    }
+  }
+}

package/src/server/plugins/engine/README.md

@@ -0,0 +1,87 @@
+# forms-engine
+
+Form hapi-plugin
+
+...
+
+## Templates
+
+The following elements support [LiquidJS templates](https://liquidjs.com/):
+
+- Page **title**
+- Form component **titles**
+  - Support for fieldset legend text or label text
+  - This includes when the title is used in **error messages**
+- Html (guidance) component **content**
+- Summary component **row** key title (check answers and repeater summary)
+
+### Template data
+
+The data the templates are evaluated against is the raw answers the user has provided up to the page they're currently on.
+For example, given a YesNoField component called `TKsWbP`, the template `{{ TKsWbP }}` would render "true" or "false" depending on how the user answered the question.
+
+The current FormContext is also available as `context` in the templates. This allows access to the full data including the path the user has taken in their journey and any miscellaneous data returned from `Page event`s in `context.data`.
+
+### Liquid Filters
+
+There are a number of `LiquidJS` filters available to you from within the templates:
+
+- `page` - returns the page definition for the given path
+- `field` - returns the component definition for the given name
+- `href` - returns the page href for the given page path
+- `answer` - returns the user's answer for a given component
+- `evaluate` - evaluates and returns a Liquid template using the current context
+
+### Examples
+
+```json
+"pages": [
+  {
+    "title": "What's your name?",
+    "path": "/full-name",
+    "components": [
+      {
+        "name": "WmHfSb",
+        "title": "What's your full name?",
+        "type": "TextField"
+      }
+    ]
+  },
+  // This example shows how a component can use an answer to a previous question (What's your full name) in it's title
+  {
+    "title": "Are you in England?",
+    "path": "/are-you-in-england",
+    "components": [
+      {
+        "name": "TKsWbP",
+        "title": "Are you in England, {{ WmHfSb }}?",
+        "type": "YesNoField"
+      }
+    ]
+  },
+  // This example shows how a Html (guidance) component can use the available filters to get the form definition and user answers and display them
+  {
+    "title": "Template example for {{ WmHfSb }}?",
+    "path": "/example",
+    "components": [
+      {
+        "title": "Html",
+        "type": "Html",
+        "content": "<p class=\"govuk-body\">
+          // Use Liquid's `assign` to create a variable that holds reference to the \"/are-you-in-england\" page
+          {%- assign inEngland = \"/are-you-in-england\" | page -%}
+
+          // Use the reference to `evaluate` the title
+          {{ inEngland.title | evaluate }}<br>
+
+          // Use the href filter to display the full page path
+          {{ \"/are-you-in-england\" | href }}<br>
+
+          // Use the `answer` filter to render the user provided answer to a question
+          {{ 'TKsWbP' | answer }}
+        </p>\n"
+      }
+    ]
+  }
+]
+```

package/src/server/plugins/engine/components/AutocompleteField.test.ts

@@ -0,0 +1,294 @@
+import {
+  ComponentType,
+  type AutocompleteFieldComponent
+} from '@defra/forms-model'
+
+import { AutocompleteField } from '~/src/server/plugins/engine/components/AutocompleteField.js'
+import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
+import {
+  getAnswer,
+  type Field
+} from '~/src/server/plugins/engine/components/helpers.js'
+import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import {
+  listNumber,
+  listNumberExamples,
+  listString,
+  listStringExamples
+} from '~/test/fixtures/list.js'
+import definition from '~/test/form/definitions/blank.js'
+import { getFormData, getFormState } from '~/test/helpers/component-helpers.js'
+
+describe.each([
+  {
+    component: {
+      title: 'String list',
+      name: 'myComponent',
+      type: ComponentType.AutocompleteField,
+      list: 'listString',
+      options: {}
+    } satisfies AutocompleteFieldComponent,
+
+    options: {
+      list: listString,
+      examples: listStringExamples,
+      allow: ['1', '2', '3', '4']
+    }
+  },
+  {
+    component: {
+      title: 'Number list',
+      name: 'myComponent',
+      type: ComponentType.AutocompleteField,
+      list: 'listNumber',
+      options: {}
+    } satisfies AutocompleteFieldComponent,
+
+    options: {
+      list: listNumber,
+      examples: listNumberExamples,
+      allow: [1, 2, 3, 4]
+    }
+  }
+])('AutocompleteField: $component.title', ({ component: def, options }) => {
+  let model: FormModel
+  let collection: ComponentCollection
+  let field: Field
+
+  beforeEach(() => {
+    const updated = structuredClone(definition)
+    updated.lists = [options.list]
+
+    model = new FormModel(updated, {
+      basePath: 'test'
+    })
+
+    collection = new ComponentCollection([def], { model })
+    field = collection.fields[0]
+  })
+
+  describe('Defaults', () => {
+    describe('Schema', () => {
+      it('uses component title as label', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({ label: def.title })
+          })
+        )
+      })
+
+      it('uses component name as keys', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(field.keys).toEqual(['myComponent'])
+        expect(field.collection).toBeUndefined()
+
+        for (const key of field.keys) {
+          expect(keys).toHaveProperty(key)
+        }
+      })
+
+      it('is required by default', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            flags: expect.objectContaining({
+              presence: 'required'
+            })
+          })
+        )
+      })
+
+      it('is optional when configured', () => {
+        const collectionOptional = new ComponentCollection(
+          [{ ...def, options: { required: false } }],
+          { model }
+        )
+
+        const { formSchema } = collectionOptional
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            allow: expect.arrayContaining([''])
+          })
+        )
+
+        const result = collectionOptional.validate(getFormData(''))
+        expect(result.errors).toBeUndefined()
+      })
+
+      it('is configured with autocomplete suggestions', () => {
+        const { formSchema } = collection
+        const { keys } = formSchema.describe()
+
+        expect(keys).toHaveProperty(
+          'myComponent',
+          expect.objectContaining({
+            allow: options.allow,
+            type: options.list.type
+          })
+        )
+      })
+
+      it.each([...options.allow])(
+        'accepts valid list item (value: %s)',
+        (value) => {
+          const result = collection.validate(getFormData(value))
+          expect(result.errors).toBeUndefined()
+        }
+      )
+
+      it('adds errors for empty value', () => {
+        const result = collection.validate(getFormData(''))
+
+        expect(result.errors).toEqual([
+          expect.objectContaining({
+            text: `Enter ${def.title.toLowerCase()}`
+          })
+        ])
+      })
+
+      it('adds errors for invalid values', () => {
+        const result1 = collection.validate(getFormData('invalid'))
+        const result2 = collection.validate(
+          // @ts-expect-error - Allow invalid param for test
+          getFormData({ unknown: 'invalid' })
+        )
+
+        expect(result1.errors).toBeTruthy()
+        expect(result2.errors).toBeTruthy()
+      })
+    })
+
+    describe('State', () => {
+      it.each([...options.examples])('returns text from state', (item) => {
+        const state1 = getFormState(item.state)
+        const state2 = getFormState(null)
+
+        const answer1 = getAnswer(field, state1)
+        const answer2 = getAnswer(field, state2)
+
+        expect(answer1).toBe(item.text)
+        expect(answer2).toBe('')
+      })
+
+      it.each([...options.examples])('returns payload from state', (item) => {
+        const state1 = getFormState(item.state)
+        const state2 = getFormState(null)
+
+        const payload1 = field.getFormDataFromState(state1)
+        const payload2 = field.getFormDataFromState(state2)
+
+        expect(payload1).toEqual(getFormData(item.value))
+        expect(payload2).toEqual(getFormData())
+      })
+
+      it.each([...options.examples])('returns value from state', (item) => {
+        const state1 = getFormState(item.state)
+        const state2 = getFormState(null)
+
+        const value1 = field.getFormValueFromState(state1)
+        const value2 = field.getFormValueFromState(state2)
+
+        expect(value1).toBe(item.value)
+        expect(value2).toBeUndefined()
+      })
+
+      it.each([...options.examples])(
+        'returns context for conditions and form submission',
+        (item) => {
+          const state1 = getFormState(item.state)
+          const state2 = getFormState(null)
+
+          const value1 = field.getContextValueFromState(state1)
+          const value2 = field.getContextValueFromState(state2)
+
+          expect(value1).toEqual(item.value)
+          expect(value2).toBeNull()
+        }
+      )
+
+      it.each([...options.examples])('returns state from payload', (item) => {
+        const payload1 = getFormData(item.value)
+        const payload2 = getFormData()
+
+        const value1 = field.getStateFromValidForm(payload1)
+        const value2 = field.getStateFromValidForm(payload2)
+
+        expect(value1).toEqual(getFormState(item.state))
+        expect(value2).toEqual(getFormState(null))
+      })
+    })
+
+    describe('View model', () => {
+      it('sets Nunjucks component defaults', () => {
+        const item = options.examples[0]
+
+        const viewModel = field.getViewModel(getFormData(item.value))
+
+        expect(viewModel).toEqual(
+          expect.objectContaining({
+            label: { text: def.title },
+            name: 'myComponent',
+            id: 'myComponent',
+            value: item.value
+          })
+        )
+      })
+
+      it.each([...options.examples])(
+        'sets Nunjucks component autocomplete suggestions',
+        (item) => {
+          const viewModel = field.getViewModel(getFormData(item.value))
+
+          expect(viewModel.items?.[0]).toMatchObject({
+            value: '' // First item is always empty
+          })
+
+          expect(viewModel.items).toEqual(
+            expect.arrayContaining([
+              expect.objectContaining({
+                text: item.text,
+                value: item.value,
+                selected: true
+              })
+            ])
+          )
+        }
+      )
+    })
+
+    describe('Autocomplete suggestions', () => {
+      it('returns autocomplete suggestions', () => {
+        expect(field).toMatchObject({
+          items: options.list.items
+        })
+      })
+
+      it('returns autocomplete suggestions matching type', () => {
+        expect(field).toMatchObject({
+          values: expect.arrayContaining([])
+        })
+      })
+
+      it('returns empty items when missing', () => {
+        const model = new FormModel(definition, {
+          basePath: 'test'
+        })
+
+        const { items } = new AutocompleteField(def, { model })
+        expect(items).toEqual([])
+      })
+    })
+  })
+})