@centralping/ergo 0.1.0-beta.1

package/lib/json-api-query/schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "jsonapi.json",
+  "title": "JSON API Request Validation",
+  "description": "Validation schema for validating JSON API querystrings",
+  "type": "object",
+  "properties": {
+    "fields": {
+      "description": "https://jsonapi.org/format/#fetching-sparse-fieldsets",
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "uniqueItems": true,
+        "minItems": 1
+      },
+      "minProperties": 1
+    },
+    "filter": {
+      "description": "https://jsonapi.org/format/#fetching-filtering",
+      "type": "object",
+      "minProperties": 1
+    },
+    "include": {
+      "description": "https://jsonapi.org/format/#fetching-includes",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "page": {
+      "description": "https://jsonapi.org/format/#fetching-pagination",
+      "type": "object",
+      "properties": {
+        "cursor": {
+          "type": "string",
+          "minLength": 1
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "dependentRequired": {
+        "offset": ["limit"],
+        "number": ["size"]
+      },
+      "additionalProperties": false,
+      "minProperties": 1,
+      "if": {"required": ["cursor"]},
+      "then": {"maxProperties": 1},
+      "else": {
+        "maxProperties": 2,
+        "if": {"required": ["size"]},
+        "then": {"not": {"required": ["limit"]}}
+      }
+    },
+    "sort": {
+      "description": "https://jsonapi.org/format/#fetching-sorting",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true,
+      "minItems": 1
+    }
+  },
+  "patternProperties": {
+    "[^a-z]": {
+      "description": "https://jsonapi.org/format/#query-parameters",
+      "type": ["array", "boolean", "integer", "null", "number", "object", "string"]
+    }
+  },
+  "additionalProperties": false,
+  "if": {
+    "required": ["page"],
+    "properties": {"page": {"required": ["cursor"]}}
+  },
+  "then": {
+    "not": {
+      "anyOf": [
+        {"required": ["fields"]},
+        {"required": ["filter"]},
+        {"required": ["include"]},
+        {"required": ["sort"]}
+      ]
+    }
+  }
+}

package/lib/json-api-query/validate.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview JSON:API query parameter validator using AJV 8 with JSON Schema 2020-12.
+ *
+ * Compiles the JSON:API query schema once and returns a validator function. The compiled
+ * validator is augmented with an `errors` property (populated on validation failure) for
+ * downstream error reporting.
+ *
+ * Options mirror a subset of AJV constructor options. By default, array coercion is enabled
+ * to handle single-value query parameters that may be strings instead of arrays.
+ *
+ * @module lib/json-api-query/validate
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ajv/dist/2020.js
+ * @requires ./schema.json
+ *
+ * @example
+ * import validate from 'ergo/lib/json-api-query/validate';
+ *
+ * const validator = validate();
+ * const valid = validator({include: ['author'], fields: {articles: ['title']}});
+ * if (!valid) console.log(validator.errors);
+ */
+import Ajv2020 from 'ajv/dist/2020.js';
+
+import defaultSchema from './schema.json' with {type: 'json'};
+
+/**
+ * Creates a compiled JSON API query validator.
+ *
+ * @example
+ * const validator = validate();
+ * const valid = validator(queryParams); // where queryParams is an object
+ *
+ * if (!valid) {
+ *   console.log(validator.errors);
+ * }
+ *
+ * @param {object} [options] - Any AJV option.
+ * @param {boolean|string} [options.coerceTypes='array'] - Coerce validated values to specified types.
+ * @param {boolean} [options.ownProperties=true] - Restrict validation to own properties of data object.
+ * @param {object} [schema] - JSON Schema 2020-12. Defaults to the included schema.
+ * @returns {function} - The configured validator function.
+ */
+export default (
+  {coerceTypes = 'array', ownProperties = true, ...ajvOptions} = {},
+  schema = defaultSchema
+) => {
+  const ajv = new Ajv2020({
+    ...ajvOptions,
+    coerceTypes,
+    ownProperties
+  });
+
+  return ajv.compile(schema);
+};

package/lib/link.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview RFC 8288 Web Linking utilities.
+ *
+ * Provides functions for formatting `Link` response headers per RFC 8288.
+ * `formatLinkHeader` is the low-level formatter; `paginationLinks` is a
+ * convenience helper that generates `first`, `prev`, `next`, `last` link
+ * objects from pagination parameters.
+ *
+ * These are pure utility functions (not middleware). Consumers wire the
+ * formatted header value into the accumulator's `headers` array for `send()`.
+ *
+ * @module lib/link
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8288 RFC 8288 - Web Linking}
+ *
+ * @example
+ * import {formatLinkHeader, paginationLinks} from 'ergo/lib/link';
+ *
+ * const links = paginationLinks({
+ *   baseUrl: '/articles',
+ *   searchParams: 'sort=date',
+ *   page: 3,
+ *   perPage: 25,
+ *   total: 100
+ * });
+ * const header = formatLinkHeader(links);
+ * // '</articles?sort=date&page=1&per_page=25>; rel="first", ...'
+ */
+import sanitizeQuotedString from './sanitize-quoted-string.js';
+
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~\w]+$/;
+
+/**
+ * Formats an array of link objects into an RFC 8288 `Link` header value.
+ *
+ * @param {Array<{href: string, rel: string}>} links - Link descriptors. Each object
+ *   must have `href` and `rel`; additional properties become link parameters.
+ * @returns {string} - Formatted header value (e.g. `<url>; rel="next", <url>; rel="prev"`)
+ * @throws {TypeError} If `href` contains `>` or a parameter key is not a valid token
+ */
+export function formatLinkHeader(links) {
+  return links
+    .map(({href, rel, ...params}) => {
+      if (String(href).includes('>')) {
+        throw new TypeError('Link href must not contain ">"');
+      }
+      let entry = `<${href}>; rel="${sanitizeQuotedString(rel)}"`;
+      for (const [key, value] of Object.entries(params)) {
+        if (!TOKEN_RE.test(key)) {
+          throw new TypeError(`Link parameter key "${key}" is not a valid token`);
+        }
+        entry += `; ${key}="${sanitizeQuotedString(value)}"`;
+      }
+      return entry;
+    })
+    .join(', ');
+}
+
+/**
+ * Generates pagination link objects for first, prev, next, and last pages.
+ *
+ * Only includes `prev` when `page > 1` and `next` when `page < lastPage`.
+ * `first` and `last` are always included.
+ *
+ * @param {object} options - Pagination parameters
+ * @param {string} options.baseUrl - Base URL path (e.g. '/articles')
+ * @param {number} options.page - Current page number (1-based)
+ * @param {number} options.perPage - Items per page
+ * @param {number} options.total - Total item count
+ * @param {string} [options.searchParams=''] - Additional query parameters to preserve
+ *   (e.g. 'sort=date&filter=active'). Appended before pagination params.
+ * @returns {Array<{href: string, rel: string}>} - Array of link objects
+ */
+export function paginationLinks({baseUrl, page, perPage, total, searchParams = ''}) {
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+  const sep = searchParams ? '&' : '';
+  const prefix = `${baseUrl}?${searchParams}${sep}`;
+
+  const buildHref = p => `${prefix}page=${p}&per_page=${perPage}`;
+
+  const links = [{href: buildHref(1), rel: 'first'}];
+
+  if (page > 1) {
+    links.push({href: buildHref(page - 1), rel: 'prev'});
+  }
+
+  if (page < lastPage) {
+    links.push({href: buildHref(page + 1), rel: 'next'});
+  }
+
+  links.push({href: buildHref(lastPage), rel: 'last'});
+
+  return links;
+}

package/lib/prefer.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Pure Prefer header parser (RFC 7240).
+ *
+ * Parses the HTTP `Prefer` request header into a plain object of preference
+ * name-value pairs. Supports:
+ * - Simple tokens (`respond-async` -> `{'respond-async': true}`)
+ * - Token=value pairs (`return=minimal` -> `{return: 'minimal'}`)
+ * - Quoted values (`foo="bar baz"` -> `{foo: 'bar baz'}`)
+ * - Multiple comma-separated preferences
+ * - Per-preference parameters after semicolons (stripped; only the main token is kept)
+ *
+ * Used by:
+ * - `http/prefer.js` (ergo pipeline middleware)
+ *
+ * @module lib/prefer
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import parsePrefer from 'ergo/lib/prefer';
+ *
+ * parsePrefer('return=minimal');
+ * // {return: 'minimal'}
+ *
+ * parsePrefer('respond-async, wait=100');
+ * // {'respond-async': true, wait: '100'}
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7240 RFC 7240 - Prefer Header for HTTP}
+ */
+
+/**
+ * Parse a Prefer header value into a preferences object.
+ *
+ * @param {string} [header] - Raw Prefer header value
+ * @returns {object} - Map of preference name to value (string) or `true` for bare tokens
+ */
+export default function parsePrefer(header) {
+  if (!header) return Object.create(null);
+
+  const preferences = Object.create(null);
+
+  for (const part of header.split(',')) {
+    const [main] = part.split(';');
+    const match = main.trim().match(/^([a-zA-Z][\w-]*)(?:\s*=\s*"([^"]*)"|\s*=\s*(\S+))?$/);
+
+    if (match) {
+      preferences[match[1]] = match[2] ?? match[3] ?? true;
+    }
+  }
+
+  return preferences;
+}

package/lib/query.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Query string parser for URL query strings and JSON:API parameters.
+ *
+ * Parses raw query strings (after `?`) into nested objects, supporting:
+ * - Bracket notation: `fields[articles]=title` → `{fields: {articles: 'title'}}`
+ * - Array notation: `include[]=a&include[]=b` → `{include: ['a', 'b']}`
+ * - Comma-separated values: `sort=name,age` → `{sort: ['name', 'age']}`
+ * - Repeated keys: `tag=a&tag=b` → `{tag: ['a', 'b']}`
+ *
+ * Used by `http/url.js` for URL query parsing and `lib/json-api-query` for
+ * JSON:API query parameter parsing.
+ *
+ * @module lib/query
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../utils/set.js
+ *
+ * @example
+ * import parse from 'ergo/lib/query';
+ *
+ * parse('include=author&fields%5Barticles%5D=title%2Cbody');
+ * // => {include: 'author', fields: {articles: ['title', 'body']}}
+ *
+ * parse('tag=a&tag=b');
+ * // => {tag: ['a', 'b']}
+ */
+import set from '../utils/set.js';
+
+const subpropRegExp = /^([^[]+)(?:\[(.*)\]|)$/;
+
+/**
+ * Safely decode a URI component, returning the raw string on invalid sequences.
+ * @param {string} s - Percent-encoded URI component
+ * @returns {string} - Decoded string, or the raw input if decoding fails
+ */
+function safeDecode(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+/**
+ * Parses a query string into key-value pairs with support for bracket notation
+ * and multi-value parameters.
+ *
+ * @param {string} query - Raw query string (portion after `?`)
+ * @param {object} [options] - Parser options
+ * @param {boolean} [options.split=true] - Split comma-separated values into arrays
+ * @param {number} [options.maxPairs=256] - Maximum number of query pairs to parse (DoS protection)
+ * @param {number} [options.maxLength=8192] - Maximum raw query string length (prevents allocation bomb)
+ * @returns {object} - Parsed key-value object; multi-value keys become arrays
+ */
+export default (query, {split = true, maxPairs = 256, maxLength = 8192} = {}) => {
+  if (!query) {
+    return Object.create(null);
+  }
+
+  const bounded = query.length > maxLength ? query.slice(0, maxLength) : query;
+
+  // Single-pass parse: split on '&', decode, accumulate repeated keys
+  const q = Object.create(null);
+  const pairs = bounded.split('&');
+  const limit = Math.min(pairs.length, maxPairs);
+
+  for (let i = 0; i < limit; i++) {
+    const pair = pairs[i];
+    if (!pair) {
+      continue;
+    }
+    const eqIdx = pair.indexOf('=');
+    const rawKey = eqIdx === -1 ? pair : pair.slice(0, eqIdx);
+    const rawVal = eqIdx === -1 ? '' : pair.slice(eqIdx + 1);
+    const key = safeDecode(rawKey.replaceAll('+', ' '));
+    const val = safeDecode(rawVal.replaceAll('+', ' '));
+
+    if (key in q) {
+      if (Array.isArray(q[key])) {
+        q[key].push(val);
+      } else {
+        q[key] = [q[key], val];
+      }
+    } else {
+      q[key] = val;
+    }
+  }
+
+  const acc = Object.create(null);
+
+  for (const [k, v] of Object.entries(q)) {
+    const match = subpropRegExp.exec(k);
+    if (!match) continue;
+    let [, prop, subprop] = match;
+    let val = v;
+
+    if (subprop === '') {
+      val = [v].flat();
+    } else {
+      if (subprop !== undefined) {
+        prop += `.${subprop}`;
+      }
+
+      if (typeof v === 'string' && v.includes(',') && split) {
+        val = v.split(',').map(s => s.trim());
+      }
+    }
+
+    set(acc, prop, val);
+  }
+
+  return acc;
+};

package/lib/rate-limit.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Rate limiting shared primitives.
+ *
+ * Provides the core building blocks for both pipeline-level and transport-level
+ * rate limiting. The `MemoryStore` implements a sliding-window counter using
+ * per-key timestamp arrays. `checkRateLimit` computes the current state
+ * (remaining quota, reset time, whether the client is limited) from any store
+ * that implements the `hit(key, windowMs)` interface.
+ *
+ * Used by:
+ * - `http/rate-limit.js` (ergo pipeline middleware)
+ * - `ergo-router/lib/transport/rate-limit.js` (transport-level rate limiting)
+ *
+ * @module lib/rate-limit
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import {MemoryStore, checkRateLimit, defaultKeyGenerator} from 'ergo/lib/rate-limit';
+ *
+ * const store = new MemoryStore();
+ * const key = defaultKeyGenerator(req);
+ * const result = checkRateLimit(store, key, 100, 60000);
+ * // result.limited === true when over quota
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6585#section-4 RFC 6585 Section 4 - 429 Too Many Requests}
+ */
+
+/**
+ * In-memory sliding-window rate limit store.
+ * Each key maps to an array of request timestamps. Expired entries are pruned
+ * on every `hit()` call.
+ */
+export class MemoryStore {
+  constructor({maxKeys = 10_000} = {}) {
+    this._hits = new Map();
+    this._maxKeys = maxKeys;
+  }
+
+  /**
+   * Record a hit and return the current count within the window.
+   * @param {string} key - Client identifier
+   * @param {number} windowMs - Window size in milliseconds
+   * @returns {{count: number, resetMs: number}} - Current count and ms until the oldest entry expires
+   */
+  hit(key, windowMs) {
+    const now = Date.now();
+    const cutoff = now - windowMs;
+    let timestamps = this._hits.get(key);
+
+    if (!timestamps) {
+      timestamps = [];
+      this._hits.set(key, timestamps);
+    }
+
+    while (timestamps.length && timestamps[0] <= cutoff) {
+      timestamps.shift();
+    }
+
+    if (!timestamps.length) {
+      // Delete-then-set refreshes Map insertion order for FIFO eviction
+      this._hits.delete(key);
+      timestamps = [now];
+      this._hits.set(key, timestamps);
+    } else {
+      timestamps.push(now);
+    }
+
+    // Eviction is silent by design; custom stores can add observability
+    if (this._hits.size > this._maxKeys) {
+      const oldest = this._hits.keys().next().value;
+      this._hits.delete(oldest);
+    }
+
+    const resetMs = timestamps[0] + windowMs - now;
+
+    return {count: timestamps.length, resetMs};
+  }
+}
+
+/**
+ * Compute rate limit state from a store hit.
+ *
+ * @param {object} store - Store implementing `hit(key, windowMs) => {count, resetMs}`
+ * @param {string} key - Client identifier
+ * @param {number} max - Maximum requests allowed per window
+ * @param {number} windowMs - Window size in milliseconds
+ * @returns {{count: number, remaining: number, reset: number, limited: boolean, retryAfter: number|undefined}}
+ *   - `count`: total hits in the current window
+ *   - `remaining`: requests remaining before limit
+ *   - `reset`: Unix timestamp (seconds) when the window resets
+ *   - `limited`: true when count exceeds max
+ *   - `retryAfter`: seconds until retry is allowed (only when limited)
+ */
+export function checkRateLimit(store, key, max, windowMs) {
+  const {count, resetMs} = store.hit(key, windowMs);
+  const limited = count > max;
+
+  return {
+    count,
+    remaining: Math.max(0, max - count),
+    reset: Math.ceil((Date.now() + resetMs) / 1000),
+    limited,
+    retryAfter: limited ? Math.ceil(resetMs / 1000) : undefined
+  };
+}
+
+/**
+ * Default key generator: uses the remote IP address.
+ * @param {object} req - HTTP request
+ * @returns {string} - Client identifier
+ */
+export function defaultKeyGenerator(req) {
+  return req.socket?.remoteAddress ?? 'unknown';
+}

package/lib/sanitize-quoted-string.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Shared quoted-string sanitizer per RFC 7230 section 3.2.6.
+ *
+ * Escapes backslashes and double-quotes and strips control characters (all CTL chars
+ * except HTAB, which is valid in `qdtext` per RFC 7230 §3.2.6) so the result is safe
+ * for inclusion between double-quote delimiters in HTTP headers such as
+ * `WWW-Authenticate`, `Link`, and `Set-Cookie`.
+ *
+ * @module lib/sanitize-quoted-string
+ * @version 0.1.0
+ * @since 0.1.0
+ */
+
+/**
+ * Escape a value for use inside a quoted-string per RFC 7230 section 3.2.6.
+ *
+ * @param {string} str - Raw value
+ * @returns {string} - Value safe for inclusion between double-quote delimiters
+ */
+export default function sanitizeQuotedString(str) {
+  return (
+    String(str)
+      .replaceAll('\\', '\\\\')
+      .replaceAll('"', '\\"')
+      // eslint-disable-next-line no-control-regex -- intentional: strip CTLs per RFC 7230 §3.2.6
+      .replaceAll(/[\x00-\x08\x0a-\x1f\x7f]/g, '')
+  );
+}

package/lib/security-headers.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Shared security header tuple builder.
+ *
+ * Builds an array of `[header-name, header-value]` tuples from a configuration
+ * object. Used by both ergo's pipeline middleware (`http/security-headers.js`)
+ * and ergo-router's transport layer. Each header can be overridden (string),
+ * disabled (`false`), or left at its default.
+ *
+ * `strictTransportSecurity` accepts either a directive string (e.g.
+ * `'max-age=31536000; includeSubDomains'`) or a structured object
+ * `{maxAge, includeSubDomains, preload}` for programmatic construction.
+ *
+ * @module lib/security-headers
+ * @version 0.1.0
+ * @since 0.1.0
+ *
+ * @example
+ * import buildSecurityHeaderTuples from 'ergo/lib/security-headers';
+ *
+ * const tuples = buildSecurityHeaderTuples({
+ *   xFrameOptions: 'SAMEORIGIN',
+ *   strictTransportSecurity: {maxAge: 31536000, includeSubDomains: true}
+ * });
+ * // [['Content-Security-Policy', "default-src 'none'"], ['Strict-Transport-Security', 'max-age=31536000; includeSubDomains'], ...]
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6797 RFC 6797 - HTTP Strict Transport Security}
+ * @see {@link https://www.w3.org/TR/CSP3/ W3C Content Security Policy Level 3}
+ */
+
+/**
+ * Default security header values for a REST API.
+ * @type {object}
+ */
+const DEFAULTS = {
+  contentSecurityPolicy: "default-src 'none'",
+  strictTransportSecurity: false,
+  xContentTypeOptions: 'nosniff',
+  xFrameOptions: 'DENY',
+  referrerPolicy: 'no-referrer',
+  xXssProtection: '0',
+  permissionsPolicy: undefined
+};
+
+/**
+ * Build an array of security header tuples from a configuration object.
+ *
+ * @param {object} [options] - Security header configuration
+ * @param {string|false} [options.contentSecurityPolicy="default-src 'none'"] - Content-Security-Policy
+ * @param {string|object|false} [options.strictTransportSecurity=false] - HSTS directive string or
+ *   `{maxAge, includeSubDomains, preload}` object. Defaults to `false`.
+ * @param {string|boolean|false} [options.xContentTypeOptions='nosniff'] - X-Content-Type-Options.
+ *   `true` is treated as `'nosniff'`.
+ * @param {string|false} [options.xFrameOptions='DENY'] - X-Frame-Options
+ * @param {string|false} [options.referrerPolicy='no-referrer'] - Referrer-Policy
+ * @param {string|false} [options.xXssProtection='0'] - X-XSS-Protection
+ * @param {string} [options.permissionsPolicy] - Permissions-Policy (omitted by default)
+ * @returns {Array<[string, string]>} - Header tuples suitable for `res.setHeader()` or accumulator storage
+ */
+export default function buildSecurityHeaderTuples({
+  contentSecurityPolicy = DEFAULTS.contentSecurityPolicy,
+  strictTransportSecurity = DEFAULTS.strictTransportSecurity,
+  xContentTypeOptions = DEFAULTS.xContentTypeOptions,
+  xFrameOptions = DEFAULTS.xFrameOptions,
+  referrerPolicy = DEFAULTS.referrerPolicy,
+  xXssProtection = DEFAULTS.xXssProtection,
+  permissionsPolicy = DEFAULTS.permissionsPolicy
+} = {}) {
+  const tuples = [];
+
+  if (contentSecurityPolicy !== false && contentSecurityPolicy) {
+    tuples.push(['Content-Security-Policy', contentSecurityPolicy]);
+  }
+
+  if (strictTransportSecurity !== false && strictTransportSecurity) {
+    const value =
+      typeof strictTransportSecurity === 'object'
+        ? buildHstsDirective(strictTransportSecurity)
+        : strictTransportSecurity;
+    tuples.push(['Strict-Transport-Security', value]);
+  }
+
+  if (xContentTypeOptions !== false && xContentTypeOptions) {
+    tuples.push([
+      'X-Content-Type-Options',
+      xContentTypeOptions === true ? 'nosniff' : xContentTypeOptions
+    ]);
+  }
+
+  if (xFrameOptions !== false && xFrameOptions) {
+    tuples.push(['X-Frame-Options', xFrameOptions]);
+  }
+
+  if (referrerPolicy !== false && referrerPolicy) {
+    tuples.push(['Referrer-Policy', referrerPolicy]);
+  }
+
+  if (xXssProtection !== false && xXssProtection !== undefined) {
+    tuples.push(['X-XSS-Protection', String(xXssProtection)]);
+  }
+
+  if (permissionsPolicy) {
+    tuples.push(['Permissions-Policy', permissionsPolicy]);
+  }
+
+  return tuples;
+}
+
+/**
+ * Build an HSTS directive string from a structured options object.
+ * @param {object} opts - HSTS options
+ * @param {number} [opts.maxAge=31536000] - max-age in seconds
+ * @param {boolean} [opts.includeSubDomains=true] - include includeSubDomains directive
+ * @param {boolean} [opts.preload=false] - include preload directive
+ * @returns {string} - HSTS directive string
+ */
+function buildHstsDirective({maxAge = 31536000, includeSubDomains = true, preload = false} = {}) {
+  let value = `max-age=${maxAge}`;
+  if (includeSubDomains !== false) {
+    value += '; includeSubDomains';
+  }
+  if (preload) {
+    value += '; preload';
+  }
+  return value;
+}