@defra/lis-infra-ui-services 0.40.0 → 0.41.0

package/README.md

@@ -95,6 +95,33 @@ const serveStaticFiles = createStaticFilesPlugin({
 It serves `/favicon.ico` and the files under each asset path. `/status-codes` exports `statusCodes`.
 `/duration` exports the `milliseconds` and `seconds` lookups and `unixEpoch()`.
 
+### Config formats
+
+`/config-formats` exports convict formats for settings the hubs and spokes share. Register each with `convict.addFormat()`; a bad value fails `config.validate()` with the setting named.
+
+- `positiveInteger` (`'positive-integer'`): a whole number of at least 1, for timeouts, TTLs and circuit breaker thresholds, where 0 is a misconfiguration rather than "off". Values from environment variables are coerced from strings.
+- `secret` (`'secret'`): a signing or encryption secret of at least 32 characters with no default, for `HUB_JWT_SECRET` and `SESSION_COOKIE_PASSWORD`. The setting must also be marked `sensitive: true`, or convict appends the value to the validation error.
+
+```js
+import convict from 'convict'
+import { positiveInteger, secret } from '@defra/lis-infra-ui-services/config-formats'
+
+convict.addFormat(positiveInteger)
+convict.addFormat(secret)
+
+timeout: {
+  format: 'positive-integer',
+  default: 5000,
+  env: 'CATTLE_HOME_API_TIMEOUT'
+},
+hubJwtSecret: {
+  format: 'secret',
+  default: null,
+  env: 'HUB_JWT_SECRET',
+  sensitive: true
+}
+```
+
 ### Security headers
 
 `securityHeaders` is a hapi plugin that adds HSTS, `x-content-type-options`, `referrer-policy` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {
@@ -10,6 +10,7 @@
   "exports": {
     ".": "./src/index.js",
     "./base-path": "./src/base-path.js",
+    "./config-formats": "./src/config-formats.js",
     "./cookies": "./src/cookies/index.js",
     "./cookies/cookies-policy": "./src/cookies/cookies-policy.js",
     "./components/autocomplete": "./src/components/autocomplete.js",
@@ -87,6 +88,7 @@
     "@hapi/hapi": "^21.4.10",
     "@vitest/coverage-istanbul": "^4.1.10",
     "audit-ci": "^7.1.0",
+    "convict": "^6.2.5",
     "eslint": "^9.0.0",
     "govuk-frontend": "6.5.0",
     "husky": "^9.1.7",

package/src/config-formats.js

@@ -0,0 +1,56 @@
+/**
+ * A convict format for settings that must be a whole number of at least 1,
+ * such as timeouts and circuit breaker thresholds, where 0 is a
+ * misconfiguration rather than "off". Register it with
+ * `convict.addFormat(positiveInteger)` and use `format: 'positive-integer'`.
+ */
+export const positiveInteger = {
+  name: 'positive-integer',
+  /**
+   * @param {unknown} value the raw value, a string when it came from an environment variable
+   * @returns {unknown} the value as a number when it is numeric, otherwise unchanged so validate() can reject it
+   */
+  coerce(value) {
+    if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+      return Number(value)
+    }
+    return value
+  },
+  /**
+   * @param {unknown} value the coerced value
+   */
+  validate(value) {
+    if (
+      typeof value !== 'number' ||
+      !Number.isSafeInteger(value) ||
+      value < 1
+    ) {
+      throw new Error('must be a positive integer')
+    }
+  }
+}
+
+const MINIMUM_SECRET_LENGTH = 32
+
+/**
+ * A convict format for a signing or encryption secret: a string of at least
+ * 32 characters, with no default. The format's own error names the setting,
+ * never the value, but convict appends the value to a validation error unless
+ * the setting is marked `sensitive: true`. Register it with
+ * `convict.addFormat(secret)` and use `format: 'secret'` with
+ * `default: null` and `sensitive: true`.
+ */
+export const secret = {
+  name: 'secret',
+  /**
+   * @param {unknown} value
+   */
+  validate(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error('must be set')
+    }
+    if (value.length < MINIMUM_SECRET_LENGTH) {
+      throw new Error(`must be at least ${MINIMUM_SECRET_LENGTH} characters`)
+    }
+  }
+}

package/src/config-formats.test.js

@@ -0,0 +1,158 @@
+import { describe, expect, test } from 'vitest'
+import convict from 'convict'
+
+import { positiveInteger, secret } from './config-formats.js'
+
+convict.addFormat(positiveInteger)
+convict.addFormat(secret)
+
+function createConfig(value) {
+  return convict({
+    timeout: {
+      format: 'positive-integer',
+      default: 5000,
+      env: 'TEST_TIMEOUT'
+    }
+  }).load({ timeout: value })
+}
+
+describe('positiveInteger', () => {
+  test('is registered as the positive-integer format', () => {
+    // Assert
+    expect(positiveInteger.name).toBe('positive-integer')
+  })
+
+  test.each([1, 30000])('accepts %s', (value) => {
+    // Act
+    let error
+    try {
+      createConfig(value).validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+  })
+
+  test('coerces a numeric string from an environment variable', () => {
+    // Arrange
+    process.env.TEST_TIMEOUT = '2500'
+
+    // Act
+    let config, error
+    try {
+      config = convict({
+        timeout: {
+          format: 'positive-integer',
+          default: 5000,
+          env: 'TEST_TIMEOUT'
+        }
+      })
+      config.validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    } finally {
+      delete process.env.TEST_TIMEOUT
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+    expect(config.get('timeout')).toBe(2500)
+  })
+
+  test.each([0, -1, 1.5, '0', 'abc', '', null, true, '99999999999999999999'])(
+    'rejects %j naming the setting',
+    (value) => {
+      // Act
+      let error
+      try {
+        createConfig(value).validate({ allowed: 'strict' })
+      } catch (e) {
+        error = e
+      }
+
+      // Assert
+      expect(error.message).toContain('timeout: must be a positive integer')
+    }
+  )
+})
+
+describe('secret', () => {
+  function createSecretConfig(value) {
+    return convict({
+      password: {
+        format: 'secret',
+        default: null,
+        sensitive: true
+      }
+    }).load({ password: value })
+  }
+
+  test('is registered as the secret format', () => {
+    // Assert
+    expect(secret.name).toBe('secret')
+  })
+
+  test('accepts a string of at least 32 characters', () => {
+    // Act
+    let error
+    try {
+      createSecretConfig('a'.repeat(32)).validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+  })
+
+  test.each([null, '', 42])('rejects %j as unset', (value) => {
+    // Act
+    let error
+    try {
+      createSecretConfig(value).validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error.message).toContain('password: must be set')
+  })
+
+  test('rejects a short secret without echoing it', () => {
+    // Arrange
+    const value = 'too-short-secret'
+
+    // Act
+    let error
+    try {
+      createSecretConfig(value).validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error.message).toContain('password: must be at least 32 characters')
+    expect(error.message).not.toContain(value)
+  })
+
+  test('relies on sensitive: true to keep the value out of the error', () => {
+    // Arrange
+    const value = 'too-short-secret'
+    const config = convict({
+      password: { format: 'secret', default: null }
+    }).load({ password: value })
+
+    // Act
+    let error
+    try {
+      config.validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error.message).toContain(value)
+  })
+})