@defra/lis-infra-ui-services 0.44.0 → 0.45.0

package/README.md

@@ -100,15 +100,25 @@ It serves `/favicon.ico` and the files under each asset path. `/status-codes` ex
 `/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.
+- `duration({ max })` (`'duration'`, or `'duration-max-P7D'` when `max` is given): a length of time read as milliseconds. An environment variable may give an ISO 8601 duration of days, hours, minutes and seconds (`PT4H`, `P7D`, `P1DT12H`) or a whole number of milliseconds; both are coerced to milliseconds (the schema `default` must be a number). `max` is itself an ISO 8601 duration and rejects anything longer, for `SESSION_CACHE_TTL` where CDP requires sessions to expire within 7 days.
 - `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'
+import { duration, positiveInteger, secret } from '@defra/lis-infra-ui-services/config-formats'
+import { milliseconds } from '@defra/lis-infra-ui-services/duration'
 
+const sessionTtl = duration({ max: 'P7D' })
 convict.addFormat(positiveInteger)
+convict.addFormat(sessionTtl)
 convict.addFormat(secret)
 
+sessionCacheTtl: {
+  format: sessionTtl.name,
+  default: milliseconds.fourHours,
+  env: 'SESSION_CACHE_TTL'
+},
+
 timeout: {
   format: 'positive-integer',
   default: 5000,
@@ -138,7 +148,9 @@ await server.register(securityHeaders)
 
 `getCacheEngine` picks Redis or in-memory Catbox. `createSessionCachePluginForConfig` registers
 [yar](https://hapi.dev/module/yar/) from the `session` config (`cache.name`, `cache.ttl`,
-`cookie.password`, `cookie.ttl`). Session cookies are always `Secure`.
+`cookie.password`, `cookie.ttl`). Session cookies are always `Secure`. Both engines cap the ttl of
+every write at `MAX_CACHE_TTL` (7 days), so no cache policy can keep session data longer than
+CDP allows.
 
 ```js
 import { getCacheEngine } from '@defra/lis-infra-ui-services/session-cache/cache-engine'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/lis-infra-ui-services",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "UI-Services shared definitions for the livestock taxonomy topology.",
   "main": "src/index.js",
   "repository": {

package/src/config-formats.js

@@ -1,3 +1,5 @@
+import { milliseconds } from './duration.js'
+
 /**
  * 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
@@ -54,3 +56,88 @@ export const secret = {
     }
   }
 }
+
+const ISO_DURATION_DATE = /^P(?:(\d+)D)?(?:T(.+))?$/
+const ISO_DURATION_TIME = /^(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?$/
+const MILLIS_IN_SECOND = 1000
+const SECONDS_IN_MINUTE = 60
+const MILLIS_IN_MINUTE = SECONDS_IN_MINUTE * MILLIS_IN_SECOND
+const MILLIS_IN_HOUR = milliseconds.oneHour
+const MILLIS_IN_DAY = milliseconds.oneDay
+
+/**
+ * Parses an ISO 8601 duration made of days, hours, minutes and seconds
+ * (for example `P7D`, `PT4H`, `P1DT12H`) into milliseconds. Years, months
+ * and weeks are not supported because their length is not fixed.
+ *
+ * @param {string} value
+ * @returns {number | undefined} milliseconds, or undefined when it is not a supported duration
+ */
+export function parseIsoDuration(value) {
+  const dateMatch = ISO_DURATION_DATE.exec(value.trim())
+  if (!dateMatch) {
+    return undefined
+  }
+  const [, days = 0, time] = dateMatch
+  const timeMatch = time === undefined ? [] : ISO_DURATION_TIME.exec(time)
+  if (!timeMatch || (days === 0 && !time) || timeMatch[0] === '') {
+    return undefined
+  }
+  const [, hours = 0, minutes = 0, seconds = 0] = timeMatch
+  return Math.round(
+    Number(days) * MILLIS_IN_DAY +
+      Number(hours) * MILLIS_IN_HOUR +
+      Number(minutes) * MILLIS_IN_MINUTE +
+      Number(seconds) * MILLIS_IN_SECOND
+  )
+}
+
+/**
+ * Builds a convict format for a duration setting that is read as
+ * milliseconds. An environment variable may give either an ISO 8601
+ * duration such as `PT4H` or `P7D`, or a whole number of milliseconds; both
+ * are coerced to milliseconds. Only values loaded from the environment are
+ * coerced, so the schema `default` must be a number of milliseconds. The
+ * value must be at least 1ms and, when `max` is given, no more than that
+ * duration. Register the result with
+ * `convict.addFormat(...)` and use its `name` as the setting's `format`.
+ *
+ * @param {{ max?: string }} [options] `max` is an ISO 8601 duration, e.g. `'P7D'`
+ * @returns {{ name: string, coerce: (value: unknown) => unknown, validate: (value: unknown) => void }}
+ */
+export function duration({ max } = {}) {
+  const maxDuration = max?.trim()
+  const maxMilliseconds =
+    maxDuration === undefined ? undefined : parseIsoDuration(maxDuration)
+  if (maxDuration !== undefined && maxMilliseconds === undefined) {
+    throw new Error(`max must be an ISO 8601 duration, got ${max}`)
+  }
+  return {
+    name:
+      maxDuration === undefined ? 'duration' : `duration-max-${maxDuration}`,
+    coerce(value) {
+      if (typeof value !== 'string') {
+        return value
+      }
+      const trimmed = value.trim()
+      if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed)
+      }
+      return parseIsoDuration(trimmed) ?? value
+    },
+    validate(value) {
+      if (
+        typeof value !== 'number' ||
+        !Number.isSafeInteger(value) ||
+        value < 1
+      ) {
+        throw new Error(
+          'must be an ISO 8601 duration (e.g. PT4H) or a positive number of milliseconds'
+        )
+      }
+      if (maxMilliseconds !== undefined && value > maxMilliseconds) {
+        throw new Error(`must be no more than ${maxDuration}`)
+      }
+    }
+  }
+}

package/src/config-formats.test.js

@@ -1,7 +1,12 @@
 import { describe, expect, test } from 'vitest'
 import convict from 'convict'
 
-import { positiveInteger, secret } from './config-formats.js'
+import {
+  duration,
+  parseIsoDuration,
+  positiveInteger,
+  secret
+} from './config-formats.js'
 
 convict.addFormat(positiveInteger)
 convict.addFormat(secret)
@@ -156,3 +161,152 @@ describe('secret', () => {
     expect(error.message).toContain(value)
   })
 })
+
+describe('parseIsoDuration', () => {
+  test.each([
+    ['PT1S', 1000],
+    ['PT1M', 60000],
+    ['PT4H', 14400000],
+    ['P7D', 604800000],
+    ['P1DT12H30M', 131400000],
+    ['PT0.5S', 500]
+  ])('parses %s to %d ms', (value, expected) => {
+    // Act
+    const result = parseIsoDuration(value)
+
+    // Assert
+    expect(result).toBe(expected)
+  })
+
+  test.each(['', 'P', 'PT', 'P1W', 'P1M', 'P1Y', '4h', '14400000', 'abc'])(
+    'returns undefined for %j',
+    (value) => {
+      // Act
+      const result = parseIsoDuration(value)
+
+      // Assert
+      expect(result).toBeUndefined()
+    }
+  )
+})
+
+describe('duration', () => {
+  const sessionTtl = duration({ max: 'P7D' })
+  convict.addFormat(sessionTtl)
+  convict.addFormat(duration())
+
+  function createDurationConfig(value, format = sessionTtl.name) {
+    return convict({
+      ttl: { format, default: 1000, env: 'TEST_TTL' }
+    }).load({ ttl: value })
+  }
+
+  test('names the format after its maximum', () => {
+    // Assert
+    expect(sessionTtl.name).toBe('duration-max-P7D')
+    expect(duration({ max: ' P7D ' }).name).toBe('duration-max-P7D')
+    expect(duration().name).toBe('duration')
+  })
+
+  test('rejects a max that is not an ISO 8601 duration', () => {
+    // Act
+    let error
+    try {
+      duration({ max: '7 days' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error.message).toBe('max must be an ISO 8601 duration, got 7 days')
+  })
+
+  test.each([
+    ['PT4H', 14400000],
+    ['P7D', 604800000],
+    ['14400000', 14400000],
+    [14400000, 14400000]
+  ])('accepts %j as %d ms', (value, expected) => {
+    // Act
+    let config, error
+    try {
+      config = createDurationConfig(value)
+      config.validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+    expect(config.get('ttl')).toBe(expected)
+  })
+
+  test('coerces an ISO 8601 duration from an environment variable', () => {
+    // Arrange
+    process.env.TEST_TTL = 'PT4H'
+
+    // Act
+    let config, error
+    try {
+      config = convict({
+        ttl: { format: sessionTtl.name, default: 1000, env: 'TEST_TTL' }
+      })
+      config.validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    } finally {
+      delete process.env.TEST_TTL
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+    expect(config.get('ttl')).toBe(14400000)
+  })
+
+  test.each(['P7DT1S', 'P8D', 604800001])(
+    'rejects %j as over the maximum',
+    (value) => {
+      // Act
+      let error
+      try {
+        createDurationConfig(value).validate({ allowed: 'strict' })
+      } catch (e) {
+        error = e
+      }
+
+      // Assert
+      expect(error.message).toContain('ttl: must be no more than P7D')
+    }
+  )
+
+  test('accepts any length when no maximum is given', () => {
+    // Act
+    let error
+    try {
+      createDurationConfig('P400D', 'duration').validate({ allowed: 'strict' })
+    } catch (e) {
+      error = e
+    }
+
+    // Assert
+    expect(error).toBeUndefined()
+  })
+
+  test.each([0, -1, 1.5, '0', 'P1W', '4h', 'abc', '', null, true])(
+    'rejects %j naming the setting',
+    (value) => {
+      // Act
+      let error
+      try {
+        createDurationConfig(value).validate({ allowed: 'strict' })
+      } catch (e) {
+        error = e
+      }
+
+      // Assert
+      expect(error.message).toContain(
+        'ttl: must be an ISO 8601 duration (e.g. PT4H) or a positive number of milliseconds'
+      )
+    }
+  )
+})

package/src/session-cache/cache-engine.js

@@ -2,6 +2,37 @@ import { Engine as CatboxRedis } from '@hapi/catbox-redis'
 import { Engine as CatboxMemory } from '@hapi/catbox-memory'
 
 import { buildRedisClient } from '../redis-client.js'
+import { milliseconds } from '../duration.js'
+
+/**
+ * The longest any key may live in the session store. CDP requires session
+ * data to expire within 7 days; this is enforced on every write so that no
+ * cache policy, however configured, can exceed it.
+ */
+export const MAX_CACHE_TTL = milliseconds.oneWeek
+
+/**
+ * Wraps a catbox engine so that every write's ttl is capped at `maxTtl`.
+ *
+ * @template {new (...args: any[]) => { set: (key: object, value: unknown, ttl: number) => Promise<void> }} T
+ * @param {T} EngineClass
+ * @param {number} maxTtl milliseconds
+ * @returns {T}
+ */
+export function withMaxTtl(EngineClass, maxTtl) {
+  return class extends EngineClass {
+    /**
+     * @param {object} key
+     * @param {unknown} value
+     * @param {number} ttl milliseconds; a missing ttl gets the maximum
+     * @returns {Promise<void>}
+     */
+    set(key, value, ttl) {
+      const cappedTtl = typeof ttl === 'number' ? Math.min(ttl, maxTtl) : maxTtl
+      return super.set(key, value, cappedTtl)
+    }
+  }
+}
 
 /**
  * @param {{ engine: string, config: object, logger: object, buildRedisClientFn?: Function, CatboxRedisClass?: Function, CatboxMemoryClass?: Function }} options
@@ -21,7 +52,8 @@ export function getCacheEngine({
       redisConfig: config.get('redis'),
       logger
     })
-    return new CatboxRedisClass({ client: redisClient })
+    const CappedRedis = withMaxTtl(CatboxRedisClass, MAX_CACHE_TTL)
+    return new CappedRedis({ client: redisClient })
   }
 
   if (config.get('isProduction')) {
@@ -31,5 +63,6 @@ export function getCacheEngine({
   }
 
   logger.info('Using Catbox Memory session cache')
-  return new CatboxMemoryClass()
+  const CappedMemory = withMaxTtl(CatboxMemoryClass, MAX_CACHE_TTL)
+  return new CappedMemory()
 }

package/src/session-cache/cache-engine.test.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { test, vi } from 'vitest'
 
-import { getCacheEngine } from './cache-engine.js'
+import { getCacheEngine, MAX_CACHE_TTL } from './cache-engine.js'
 
 test('creates a Redis cache engine with the configured client', () => {
   const client = { connected: true }
@@ -59,3 +59,50 @@ test('uses memory without warning outside production', () => {
 
   assert.equal(logger.error.mock.calls.length, 0)
 })
+
+test('caps the ttl of every Redis write at one week', async () => {
+  const set = vi.fn()
+  class RedisEngine {
+    set(...args) {
+      return set(...args)
+    }
+  }
+  const logger = { info: vi.fn(), error: vi.fn() }
+  const config = { get: vi.fn(() => ({ host: 'redis' })) }
+  const engine = getCacheEngine({
+    engine: 'redis',
+    config,
+    logger,
+    buildRedisClientFn: vi.fn(() => ({})),
+    CatboxRedisClass: RedisEngine
+  })
+
+  await engine.set({ id: 'a' }, 'value', MAX_CACHE_TTL + 1)
+  await engine.set({ id: 'b' }, 'value', 1000)
+  await engine.set({ id: 'c' }, 'value', undefined)
+
+  assert.deepEqual(set.mock.calls[0], [{ id: 'a' }, 'value', MAX_CACHE_TTL])
+  assert.deepEqual(set.mock.calls[1], [{ id: 'b' }, 'value', 1000])
+  assert.deepEqual(set.mock.calls[2], [{ id: 'c' }, 'value', MAX_CACHE_TTL])
+})
+
+test('caps the ttl of every memory write at one week', async () => {
+  const set = vi.fn()
+  class MemoryEngine {
+    set(...args) {
+      return set(...args)
+    }
+  }
+  const logger = { info: vi.fn(), error: vi.fn() }
+  const config = { get: vi.fn(() => false) }
+  const engine = getCacheEngine({
+    engine: 'memory',
+    config,
+    logger,
+    CatboxMemoryClass: MemoryEngine
+  })
+
+  await engine.set({ id: 'a' }, 'value', MAX_CACHE_TTL * 2)
+
+  assert.deepEqual(set.mock.calls[0], [{ id: 'a' }, 'value', MAX_CACHE_TTL])
+})