@defra/forms-engine-plugin 0.0.4 → 0.0.6

package/src/server/plugins/nunjucks/types.js

@@ -0,0 +1,40 @@
+/**
+ * @typedef {object} MacroOptions
+ * @property {string} [callBlock] - Nunjucks call block content
+ * @property {object} [params] - Nunjucks macro params
+ */
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {object} [context] - Nunjucks render context
+ */
+
+/**
+ * @typedef {object} ViewContext - Nunjucks view context
+ * @property {string} appVersion - Application version
+ * @property {string} assetPath - Asset path
+ * @property {Partial<Config>} config - Application config properties
+ * @property {CookieConsent} [cookieConsent] - Cookie consent preferences
+ * @property {string} [crumb] - Cross-Site Request Forgery (CSRF) token
+ * @property {string} [cspNonce] - Content Security Policy (CSP) nonce
+ * @property {string} [currentPath] - Current path
+ * @property {string} [previewMode] - Preview mode
+ * @property {string} [slug] - Form slug
+ * @property {(asset?: string) => string} getAssetPath - Asset path resolver
+ * @property {FormContext} [context] - the current form context
+ */
+
+/**
+ * @typedef {ReturnType<typeof config['getProperties']>} Config - Application config properties
+ */
+
+/**
+ * @typedef NunjucksContext
+ * @property {ViewContext} ctx - the current nunjucks view context
+ */
+
+/**
+ * @import { CookieConsent } from '~/src/common/types.js'
+ * @import { config } from '~/src/config/index.js'
+ * @import { FormContext } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/pulse.ts

@@ -0,0 +1,11 @@
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import pulse from 'hapi-pulse'
+
+export default {
+  plugin: pulse,
+  options: {
+    timeout: 800
+  }
+} satisfies ServerRegisterPluginObject<{
+  timeout: number
+}>

package/src/server/plugins/router.ts

@@ -0,0 +1,201 @@
+import { slugSchema } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import humanizeDuration from 'humanize-duration'
+import Joi from 'joi'
+
+import {
+  defaultConsent,
+  parseCookieConsent,
+  serialiseCookieConsent
+} from '~/src/common/cookies.js'
+import { type CookieConsent } from '~/src/common/types.js'
+import { config } from '~/src/config/index.js'
+import { isPathRelative } from '~/src/server/plugins/engine/helpers.js'
+import { getFormMetadata } from '~/src/server/plugins/engine/services/formsService.js'
+import { healthRoute, publicRoutes } from '~/src/server/routes/index.js'
+import { crumbSchema } from '~/src/server/schemas/index.js'
+
+const routes = [...publicRoutes, healthRoute]
+
+export default {
+  plugin: {
+    name: 'router',
+    register: (server) => {
+      server.route(routes)
+
+      // Shared help routes params schema & options
+      const params = Joi.object()
+        .keys({
+          slug: slugSchema
+        })
+        .required()
+
+      const options = {
+        validate: {
+          params
+        }
+      }
+
+      server.route<{ Params: { slug: string } }>({
+        method: 'get',
+        path: '/help/get-support/{slug}',
+        async handler(request, h) {
+          const { slug } = request.params
+          const form = await getFormMetadata(slug)
+
+          return h.view('help/get-support', { form })
+        },
+        options
+      })
+
+      server.route<{ Params: { slug: string } }>({
+        method: 'get',
+        path: '/help/privacy/{slug}',
+        async handler(request, h) {
+          const { slug } = request.params
+          const form = await getFormMetadata(slug)
+
+          return h.view('help/privacy-notice', { form })
+        },
+        options
+      })
+
+      server.route<{ Params: { slug: string } }>({
+        method: 'get',
+        path: '/help/cookies/{slug}',
+        handler(_request, h) {
+          const sessionTimeout = config.get('sessionTimeout')
+
+          const sessionDurationPretty = humanizeDuration(sessionTimeout)
+
+          return h.view('help/cookies', {
+            googleAnalyticsContainerId: config
+              .get('googleAnalyticsTrackingId')
+              .replace(/^G-/, ''),
+            sessionDurationPretty
+          })
+        },
+        options
+      })
+
+      server.route<{
+        Params: { slug: string }
+        Payload: {
+          crumb?: string
+          'cookies[analytics]'?: string
+          'cookies[dismissed]'?: string
+        }
+        Query: { returnUrl?: string }
+      }>({
+        method: 'post',
+        path: '/help/cookie-preferences/{slug}',
+        handler(request, h) {
+          const { params, payload, query } = request
+          const { slug } = params
+          let { returnUrl } = query
+
+          if (returnUrl && !isPathRelative(returnUrl)) {
+            throw Boom.badRequest('Return URL must be relative')
+          }
+
+          const analyticsDecision = (
+            payload['cookies[analytics]'] ?? ''
+          ).toLowerCase()
+
+          const dismissedDecision = (
+            payload['cookies[dismissed]'] ?? ''
+          ).toLowerCase()
+
+          // move the parser into our JS code so we can delegate to the frontend in a future iteration
+          let cookieConsent: CookieConsent
+
+          if (typeof request.state.cookieConsent === 'string') {
+            cookieConsent = parseCookieConsent(request.state.cookieConsent)
+          } else {
+            cookieConsent = defaultConsent
+          }
+
+          if (analyticsDecision) {
+            cookieConsent.analytics = analyticsDecision === 'yes'
+            cookieConsent.dismissed = false
+          }
+
+          if (dismissedDecision) {
+            cookieConsent.dismissed = dismissedDecision === 'yes'
+          }
+
+          if (!returnUrl) {
+            cookieConsent.dismissed = true // this page already has a confirmation message, don't show another
+            returnUrl = `/help/cookie-preferences/${slug}`
+          }
+
+          const serialisedCookieConsent = serialiseCookieConsent(cookieConsent)
+          h.state('cookieConsent', serialisedCookieConsent)
+
+          return h.redirect(returnUrl)
+        },
+        options: {
+          validate: {
+            params,
+            payload: Joi.object({
+              crumb: crumbSchema,
+              'cookies[analytics]': Joi.string().valid('yes', 'no').optional(),
+              'cookies[dismissed]': Joi.string().valid('yes', 'no').optional()
+            }),
+            query: Joi.object({
+              returnUrl: Joi.string().optional()
+            })
+          }
+        }
+      })
+
+      server.route({
+        method: 'get',
+        path: '/',
+        handler() {
+          throw Boom.notFound()
+        }
+      })
+
+      server.route<{ Params: { slug: string } }>({
+        method: 'get',
+        path: '/help/cookie-preferences/{slug}',
+        handler(request, h) {
+          const { params } = request
+          const { slug } = params
+          let cookieConsentDismissed = false
+
+          if (typeof request.state.cookieConsent === 'string') {
+            const cookieConsent = parseCookieConsent(
+              request.state.cookieConsent
+            )
+
+            cookieConsentDismissed = cookieConsent.dismissed
+          }
+
+          // if the user has come back to this page after updating their preferences
+          // override the 'dismissed' behaviour to show a success notification instead of
+          // the cookie banner
+          const showConsentSuccess =
+            cookieConsentDismissed &&
+            request.info.referrer.endsWith(`/help/cookie-preferences/${slug}`)
+
+          return h.view('help/cookie-preferences', {
+            cookieConsentUpdated: showConsentSuccess
+          })
+        },
+        options
+      })
+
+      server.route<{ Params: { slug: string } }>({
+        method: 'get',
+        path: '/help/accessibility-statement/{slug}',
+        handler(_request, h) {
+          return h.view('help/accessibility-statement')
+        },
+        options
+      })
+    }
+  }
+} satisfies ServerRegisterPluginObject<void>

package/src/server/plugins/session.ts

@@ -0,0 +1,28 @@
+import { type ServerRegisterPluginObject } from '@hapi/hapi'
+import yar, { type YarOptions } from '@hapi/yar'
+
+import { config } from '~/src/config/index.js'
+
+/**
+ * Yar is used for temporary session data but not form submissions, e.g. UI helpers, session flags.
+ */
+export default {
+  plugin: yar,
+  options: {
+    maxCookieSize: 0, // Always use server-side storage
+    cache: {
+      cache: 'session',
+      segment: 'session',
+      expiresIn: config.get('sessionTimeout')
+    },
+    /**
+     * @todo storeBlank is current commented out as it's a minor efficiency gain but breaks the auth tests if enabled.
+     * this only seems to affect the auth code, which we might remove anyway so it's temporarily disabled.
+     */
+    // storeBlank: false,
+    cookieOptions: {
+      password: config.get('sessionCookiePassword'),
+      isSecure: config.get('isProduction')
+    }
+  }
+} satisfies ServerRegisterPluginObject<YarOptions>

package/src/server/routes/health.js

@@ -0,0 +1,13 @@
+import { StatusCodes } from 'http-status-codes'
+
+export default /** @type {ServerRoute} */ ({
+  method: 'GET',
+  path: '/health',
+  handler(_, h) {
+    return h.response({ message: 'success' }).code(StatusCodes.OK)
+  }
+})
+
+/**
+ * @import { ServerRoute } from '@hapi/hapi'
+ */

package/src/server/routes/health.test.js

@@ -0,0 +1,35 @@
+import { createServer } from '~/src/server/index.js'
+
+describe('Health check route', () => {
+  const startServer = async () => {
+    const server = await createServer()
+    await server.initialize()
+    return server
+  }
+
+  /** @type {Server} */
+  let server
+
+  afterEach(async () => {
+    await server.stop()
+  })
+
+  test('/health route response is correct', async () => {
+    server = await startServer()
+
+    const options = {
+      method: 'GET',
+      url: '/health'
+    }
+
+    const { result } = await server.inject(options)
+
+    expect(result).toMatchObject({
+      message: 'success'
+    })
+  })
+})
+
+/**
+ * @import { Server } from '@hapi/hapi'
+ */

package/src/server/routes/index.test.ts

@@ -0,0 +1,125 @@
+import { type Server } from '@hapi/hapi'
+import { StatusCodes } from 'http-status-codes'
+
+import { config } from '~/src/config/index.js'
+import { createServer } from '~/src/server/index.js'
+import { getFormMetadata } from '~/src/server/plugins/engine/services/formsService.js'
+import * as fixtures from '~/test/fixtures/index.js'
+import { renderResponse } from '~/test/helpers/component-helpers.js'
+
+jest.mock('~/src/server/plugins/engine/services/formsService.js')
+
+describe('Routes', () => {
+  let server: Server
+
+  beforeAll(async () => {
+    server = await createServer()
+    await server.initialize()
+  })
+
+  afterAll(async () => {
+    await server.stop()
+  })
+
+  test('cookies page is served with 24 hour duration', async () => {
+    config.set('sessionTimeout', 86400000)
+
+    const options = {
+      method: 'GET',
+      url: '/help/cookies/slug'
+    }
+
+    const { container } = await renderResponse(server, options)
+
+    const $heading = container.getByRole('heading', {
+      name: 'Cookies',
+      level: 1
+    })
+
+    const $googleAnalyticsRowheader = container.getByRole('rowheader', {
+      name: '_ga_123456789'
+    })
+
+    const $sessionDurationRow = container.getByRole('row', {
+      name: 'session Remembers the information you enter When you close the browser, or after 1 day'
+    })
+
+    expect($heading).toBeInTheDocument()
+    expect($heading).toHaveClass('govuk-heading-l')
+    expect($googleAnalyticsRowheader).toBeInTheDocument()
+    expect($sessionDurationRow).toBeInTheDocument()
+  })
+
+  test('accessibility statement page is served', async () => {
+    const options = {
+      method: 'GET',
+      url: '/help/accessibility-statement/slug'
+    }
+
+    const { container } = await renderResponse(server, options)
+
+    const $heading = container.getByRole('heading', {
+      name: 'Accessibility statement for this form',
+      level: 1
+    })
+
+    expect($heading).toBeInTheDocument()
+    expect($heading).toHaveClass('govuk-heading-l')
+  })
+
+  test('Help page is served', async () => {
+    jest.mocked(getFormMetadata).mockResolvedValue(fixtures.form.metadata)
+
+    const options = {
+      method: 'GET',
+      url: '/help/get-support/slug'
+    }
+
+    const res = await server.inject(options)
+
+    expect(res.statusCode).toBe(StatusCodes.OK)
+  })
+
+  test('Service banner is not shown by default', async () => {
+    const { container } = await renderResponse(server, {
+      method: 'GET',
+      url: '/'
+    })
+
+    const $banner = container.queryByRole('complementary', {
+      name: 'Service status'
+    })
+
+    expect($banner).not.toBeInTheDocument()
+  })
+
+  test('Service banner is not shown when empty', async () => {
+    config.set('serviceBannerText', '')
+
+    const { container } = await renderResponse(server, {
+      method: 'GET',
+      url: '/'
+    })
+
+    const $banner = container.queryByRole('complementary', {
+      name: 'Service status'
+    })
+
+    expect($banner).not.toBeInTheDocument()
+  })
+
+  test('Service banner is shown when configured', async () => {
+    config.set('serviceBannerText', 'Hello world')
+
+    const { container } = await renderResponse(server, {
+      method: 'GET',
+      url: '/'
+    })
+
+    const $banner = container.getByRole('complementary', {
+      name: 'Service status'
+    })
+
+    expect($banner).toHaveTextContent('Hello world')
+  })
+})

package/src/server/routes/index.ts

@@ -0,0 +1,2 @@
+export { default as publicRoutes } from '~/src/server/routes/public.js'
+export { default as healthRoute } from '~/src/server/routes/health.js'

package/src/server/routes/public.ts

@@ -0,0 +1,47 @@
+import { join } from 'node:path'
+
+import { type HandlerDecorations, type ServerRoute } from '@hapi/hapi'
+
+import { config } from '~/src/config/index.js'
+
+export default [
+  {
+    from: '/javascripts/{path*}',
+    to: join(config.get('publicDir'), 'javascripts'),
+    immutable: true
+  },
+  {
+    from: '/stylesheets/{path*}',
+    to: join(config.get('publicDir'), 'stylesheets'),
+    immutable: true
+  },
+  {
+    from: '/assets/fonts/{path*}',
+    to: join(config.get('publicDir'), 'assets/fonts'),
+    immutable: true
+  },
+  {
+    from: '/assets/{path*}',
+    to: join(config.get('publicDir'), 'assets'),
+    immutable: false
+  }
+].map((options) => {
+  return {
+    method: 'GET',
+    path: options.from,
+    options: {
+      cache: {
+        // Historically, an infinite max-age is the 32-bit maximum 2,147,483,648
+        // https://datatracker.ietf.org/doc/html/rfc9111#section-1.2.2
+        otherwise: options.immutable
+          ? 'public, max-age=2147483648, immutable'
+          : 'public, max-age=0, must-revalidate'
+      },
+      handler: {
+        directory: {
+          path: options.to
+        }
+      } satisfies HandlerDecorations
+    }
+  } satisfies ServerRoute
+})

package/src/server/routes/types.ts

@@ -0,0 +1,48 @@
+import { type ReqRefDefaults, type Request } from '@hapi/hapi'
+
+import { type FormPayload } from '~/src/server/plugins/engine/types.js'
+
+export interface FormQuery extends Partial<Record<string, string>> {
+  /**
+   * Allow preview URL direct access without relevant page checks
+   */
+  force?: string
+
+  /**
+   * Redirect location after 'continue' form action
+   */
+  returnUrl?: string
+}
+
+export interface FormParams extends Partial<Record<string, string>> {
+  path: string
+  slug: string
+  state?: FormStatus
+}
+
+export interface FormRequestRefs
+  extends Omit<ReqRefDefaults, 'Params' | 'Payload' | 'Query'> {
+  Params: FormParams
+  Payload: object | undefined
+  Query: FormQuery
+}
+
+export interface FormRequestPayloadRefs extends FormRequestRefs {
+  Payload: FormPayload
+}
+
+export type FormRequest = Request<FormRequestRefs>
+export type FormRequestPayload = Request<FormRequestPayloadRefs>
+
+export enum FormAction {
+  Continue = 'continue',
+  Validate = 'validate',
+  Delete = 'delete',
+  AddAnother = 'add-another',
+  Send = 'send'
+}
+
+export enum FormStatus {
+  Draft = 'draft',
+  Live = 'live'
+}

package/src/server/schemas/index.ts

@@ -0,0 +1,34 @@
+import Joi from 'joi'
+
+import { type FormParams } from '~/src/server/plugins/engine/types.js'
+import { FormAction, FormStatus } from '~/src/server/routes/types.js'
+
+export const stateSchema = Joi.string<FormStatus>()
+  .valid(FormStatus.Draft, FormStatus.Live)
+  .required()
+
+export const actionSchema = Joi.string<FormAction>()
+  .valid(
+    FormAction.Continue,
+    FormAction.Validate,
+    FormAction.Delete,
+    FormAction.AddAnother,
+    FormAction.Send
+  )
+  .default(FormAction.Validate)
+  .optional()
+
+export const pathSchema = Joi.string().required()
+export const itemIdSchema = Joi.string().uuid().required()
+export const crumbSchema = Joi.string().optional().allow('')
+export const confirmSchema = Joi.boolean().empty(false)
+
+export const paramsSchema = Joi.object<FormParams>()
+  .keys({
+    action: actionSchema,
+    confirm: confirmSchema,
+    crumb: crumbSchema,
+    itemId: itemIdSchema.optional()
+  })
+  .default({})
+  .optional()

package/src/server/secure-context.js

@@ -0,0 +1,43 @@
+import tls from 'node:tls'
+
+import { getTrustStoreCerts } from '~/src/server/utils/secure-context/get-trust-store-certs.js'
+
+/**
+ * @type {SecureContext}
+ */
+export let secureContext
+
+/**
+ * Prepares the TLS secure context
+ * @param {Server} server
+ * @returns
+ */
+export function prepareSecureContext(server) {
+  const originalCreateSecureContext = tls.createSecureContext
+
+  tls.createSecureContext = function (options = {}) {
+    const trustStoreCerts = getTrustStoreCerts(process.env)
+
+    if (!trustStoreCerts.length) {
+      server.logger.info('Could not find any TRUSTSTORE_ certificates')
+    }
+
+    const originalSecureContext = originalCreateSecureContext(options)
+
+    trustStoreCerts.forEach((cert) => {
+      // eslint-disable-next-line -- Node.js API not documented
+      originalSecureContext.context.addCACert(cert)
+    })
+
+    return originalSecureContext
+  }
+
+  secureContext = tls.createSecureContext()
+
+  return secureContext
+}
+
+/**
+ * @import { Server } from '@hapi/hapi'
+ * @import { SecureContext } from 'node:tls'
+ */