@znight/http 0.0.0-stage → 0.1.0

package/src/cors.ts

@@ -0,0 +1,349 @@
+/**
+ * CORS policy (RFC 0001 §5.4): option validation and the headers of preflights and replies. Pure:
+ * the pipeline decides when to apply it (preflights are answered before routing and guards, the
+ * same way on every adapter).
+ */
+import type { HeaderValue } from './exceptions.ts'
+
+import { isHeaderName } from './headers.ts'
+import { invalidOption } from './option-error.ts'
+
+/**
+ * Origins allowed to read responses: `'*'` (any origin), an exact origin
+ * (`'https://app.example.com'`), an anchored `RegExp` (`/^https:\/\/[a-z0-9-]+\.example\.com$/`), a
+ * list of those, or a function (awaited; a function that throws or rejects denies the origin).
+ */
+export type CorsOrigin =
+  | '*'
+  | string
+  | RegExp
+  | readonly (string | RegExp)[]
+  | ((origin: string) => boolean | Promise<boolean>)
+
+/** The `cors` option of `HttpPlugin.configure`. */
+export interface CorsOptions {
+  /** Allowed origins (required). */
+  readonly origin: CorsOrigin
+  /** `access-control-allow-credentials: true` (cookies, `Authorization`). Not with `'*'`. Default `false`. */
+  readonly credentials?: boolean
+  /**
+   * `access-control-allow-methods` of preflights. Default: the methods routed on the requested path.
+   * `'*'` (any method) is refused with `credentials`, where browsers read it as a method named `*`.
+   */
+  readonly methods?: readonly string[]
+  /**
+   * `access-control-allow-headers` of preflights. Default: the headers the browser asks for
+   * (`access-control-request-headers`). `'*'` is refused with `credentials`; it covers
+   * `Authorization` too (sent as `*, authorization` when the browser asks for it: browsers never let
+   * `*` alone cover it).
+   */
+  readonly allowHeaders?: readonly string[] | '*'
+  /**
+   * `access-control-expose-headers` of replies. Default: the request id header (none when it is
+   * `false`). `'*'` (every header) is refused with `credentials`, where browsers read it literally.
+   */
+  readonly exposeHeaders?: readonly string[]
+  /** `access-control-max-age` of preflights, in seconds (0 to 86400). Default `600`. */
+  readonly maxAge?: number
+}
+
+/** A resolved CORS policy (internal). */
+export interface CorsPolicy {
+  /** Any origin is allowed: `access-control-allow-origin: *`. */
+  readonly wildcard: boolean
+  /**
+   * Replies get `vary: origin` (every policy but a wildcard one, whose replies all carry
+   * `access-control-allow-origin: *`).
+   */
+  readonly varyOrigin: boolean
+  readonly credentials: boolean
+  /** Joined `methods`, `undefined` for the default (the methods of the path). */
+  readonly methods: string | undefined
+  /** Joined `allowHeaders` or `*`, `undefined` for the default (echo the request). */
+  readonly allowHeaders: string | undefined
+  /** Joined `exposeHeaders`, `undefined` when there are none. */
+  readonly exposeHeaders: string | undefined
+  readonly maxAge: string
+  /** Whether `origin` (the request `origin` header) is allowed. May throw or reject: the caller denies it then. */
+  allows(origin: string): boolean | Promise<boolean>
+}
+
+const KEYS = new Set(['origin', 'credentials', 'methods', 'allowHeaders', 'exposeHeaders', 'maxAge'])
+/** RFC 9110 token (methods). */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+const MAX_AGE_LIMIT = 86_400
+const DEFAULT_MAX_AGE = 600
+const PREFLIGHT_VARY = 'origin, access-control-request-method, access-control-request-headers'
+
+/** Validates the `cors` option (ZNIGHT005). `undefined` / `false`: CORS is disabled. */
+export function resolveCors(
+  options: CorsOptions | false | undefined,
+  requestIdHeader: string | undefined,
+): CorsPolicy | undefined {
+  if (options === undefined || options === false) return undefined
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw invalidOption(
+      'cors',
+      '{ origin, credentials?, methods?, allowHeaders?, exposeHeaders?, maxAge? } or false',
+      options,
+    )
+  }
+  for (const key of Object.keys(options)) {
+    if (!KEYS.has(key)) {
+      throw invalidOption('cors', '{ origin, credentials?, methods?, allowHeaders?, exposeHeaders?, maxAge? }', options)
+    }
+  }
+  const credentials = options.credentials ?? false
+  if (typeof credentials !== 'boolean') throw invalidOption('cors.credentials', 'a boolean', credentials)
+  const origin = resolveOrigin(options.origin)
+  if (credentials && origin.wildcard) {
+    throw invalidOption(
+      'cors.origin',
+      "explicit origins when credentials is true (not '*')",
+      options.origin,
+      undefined,
+      ["Browsers reject 'access-control-allow-origin: *' on credentialed requests: list the origins"],
+    )
+  }
+  const methods = tokenList('cors.methods', options.methods, TOKEN, 'HTTP method names')
+  if (credentials) {
+    refuseWildcard('cors.methods', options.methods, 'HTTP method names', 'a method named "*"')
+    refuseWildcard('cors.allowHeaders', options.allowHeaders, 'header names', 'a header named "*"')
+    refuseWildcard('cors.exposeHeaders', options.exposeHeaders, 'header names', 'a header named "*"')
+  }
+  let allowHeaders: string | undefined
+  if (options.allowHeaders === '*') {
+    if (credentials) {
+      throw invalidOption(
+        'cors.allowHeaders',
+        "a list of header names when credentials is true (not '*')",
+        '*',
+        undefined,
+        ["Browsers ignore 'access-control-allow-headers: *' on credentialed requests"],
+      )
+    }
+    allowHeaders = '*'
+  } else {
+    allowHeaders = headerList('cors.allowHeaders', options.allowHeaders)
+  }
+  const expose =
+    options.exposeHeaders === undefined ? requestIdHeader : headerList('cors.exposeHeaders', options.exposeHeaders)
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE
+  if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) {
+    throw invalidOption('cors.maxAge', `an integer number of seconds between 0 and ${MAX_AGE_LIMIT}`, maxAge)
+  }
+  return Object.freeze({
+    wildcard: origin.wildcard,
+    varyOrigin: !origin.wildcard,
+    credentials,
+    methods,
+    allowHeaders,
+    exposeHeaders: expose === '' ? undefined : expose,
+    maxAge: String(maxAge),
+    allows: origin.allows,
+  })
+}
+
+interface ResolvedOrigin {
+  readonly wildcard: boolean
+  readonly allows: (origin: string) => boolean | Promise<boolean>
+}
+
+function resolveOrigin(value: CorsOrigin | undefined): ResolvedOrigin {
+  if (value === undefined) {
+    throw invalidOption(
+      'cors.origin',
+      "'*', an origin, an anchored RegExp, a list of them or a function",
+      value,
+      undefined,
+      ["cors: { origin: 'https://app.example.com' }"],
+    )
+  }
+  if (typeof value === 'function') {
+    return { wildcard: false, allows: value }
+  }
+  const items: readonly unknown[] = Array.isArray(value) ? value : [value]
+  const exact = new Set<string>()
+  const patterns: RegExp[] = []
+  let wildcard = false
+  for (const item of items) {
+    if (item === '*') wildcard = true
+    else if (typeof item === 'string') exact.add(checkOrigin(item))
+    else if (item instanceof RegExp) patterns.push(checkPattern(item))
+    else {
+      throw invalidOption('cors.origin', "'*', an origin, an anchored RegExp, a list of them or a function", value)
+    }
+  }
+  if (wildcard) return { wildcard: true, allows: () => true }
+  return {
+    wildcard: false,
+    allows: (origin: string): boolean => exact.has(origin) || patterns.some(pattern => pattern.test(origin)),
+  }
+}
+
+/** An origin must be written exactly as browsers send it: `scheme://host[:port]`. */
+function checkOrigin(value: string): string {
+  if (value === 'null') {
+    throw invalidOption('cors.origin', 'a real origin', value, undefined, [
+      'The "null" origin is shared by sandboxed iframes, local files and redirects: never trust it',
+    ])
+  }
+  let url: URL | undefined
+  try {
+    url = new URL(value)
+  } catch {
+    url = undefined
+  }
+  if (url === undefined || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+    throw invalidOption('cors.origin', 'an http(s) origin such as "https://app.example.com"', value)
+  }
+  if (url.origin !== value) {
+    throw invalidOption(
+      'cors.origin',
+      `an origin without path, trailing slash or default port ("${url.origin}")`,
+      value,
+      undefined,
+      [`Write "${url.origin}": browsers send the origin in this exact form`],
+    )
+  }
+  return value
+}
+
+function checkPattern(pattern: RegExp): RegExp {
+  const source = pattern.source
+  const trailingBackslashes = /\\*\$$/.exec(source)?.[0].length ?? 0
+  // `\$` at the end matches a dollar sign: the pattern is not anchored
+  const anchoredEnd = source.endsWith('$') && (trailingBackslashes - 1) % 2 === 0
+  if (!source.startsWith('^') || !anchoredEnd) {
+    throw invalidOption('cors.origin', 'a RegExp anchored with ^ and $', pattern, undefined, [
+      'Without anchors, /example\\.com/ also allows https://example.com.evil.net',
+    ])
+  }
+  if (hasTopLevelAlternation(source)) {
+    throw invalidOption('cors.origin', 'a RegExp anchored with ^ and $ around every alternative', pattern, undefined, [
+      'In /^a|b$/ the anchors bind to one alternative each: write /^(?:a|b)$/',
+    ])
+  }
+  if (pattern.global || pattern.sticky) {
+    throw invalidOption('cors.origin', 'a RegExp without the g or y flag (test() would be stateful)', pattern)
+  }
+  return pattern
+}
+
+/** Whether a pattern source has a `|` outside any group and character class. */
+function hasTopLevelAlternation(source: string): boolean {
+  let depth = 0
+  let inClass = false
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index]
+    if (char === '\\') {
+      index++
+    } else if (inClass) {
+      if (char === ']') inClass = false
+    } else if (char === '[') {
+      inClass = true
+    } else if (char === '(') {
+      depth++
+    } else if (char === ')') {
+      depth--
+    } else if (char === '|' && depth === 0) {
+      return true
+    }
+  }
+  return false
+}
+
+/** `'*'` in a list of a credentialed policy: browsers read it literally there (Fetch, CORS protocol). */
+function refuseWildcard(name: string, value: unknown, what: string, literal: string): void {
+  if (!Array.isArray(value) || !value.includes('*')) return
+  throw invalidOption(name, `a list of ${what} when credentials is true (not '*')`, value, undefined, [
+    `On credentialed requests browsers read '*' as ${literal}, not as a wildcard: list the names`,
+  ])
+}
+
+function tokenList(name: string, value: unknown, grammar: RegExp, what: string): string | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || !value.every(item => typeof item === 'string' && grammar.test(item))) {
+    throw invalidOption(name, `an array of ${what}`, value)
+  }
+  return value.join(', ')
+}
+
+function headerList(name: string, value: unknown): string | undefined {
+  if (value === undefined) return undefined
+  if (!Array.isArray(value) || !value.every(item => typeof item === 'string' && isHeaderName(item))) {
+    throw invalidOption(name, 'an array of header names', value)
+  }
+  return value.map((item: string) => item.toLowerCase()).join(', ')
+}
+
+/**
+ * Whether a request is a CORS preflight: `OPTIONS` with `origin` and
+ * `access-control-request-method`.
+ */
+export function isPreflight(method: string, headers: Readonly<Record<string, string | undefined>>): boolean {
+  return (
+    method === 'OPTIONS' && headers['origin'] !== undefined && headers['access-control-request-method'] !== undefined
+  )
+}
+
+/** Headers of a `204` preflight answer for an allowed origin. */
+export function preflightHeaders(
+  policy: CorsPolicy,
+  origin: string,
+  requestHeaders: Readonly<Record<string, string | undefined>>,
+  allow: string,
+): Record<string, HeaderValue> {
+  const headers: Record<string, HeaderValue> = {
+    'access-control-allow-origin': policy.wildcard ? '*' : origin,
+  }
+  if (policy.credentials) headers['access-control-allow-credentials'] = 'true'
+  const methods = policy.methods ?? allow
+  if (methods !== '') headers['access-control-allow-methods'] = methods
+  const requested = requestedHeaders(requestHeaders['access-control-request-headers'])
+  let allowHeaders = policy.allowHeaders ?? requested
+  // `*` never covers Authorization (Fetch): name it when the browser asks for it
+  if (allowHeaders !== undefined && requested?.split(', ').includes('authorization') === true) {
+    const allowed = allowHeaders.split(', ')
+    if (allowed.includes('*') && !allowed.includes('authorization')) allowHeaders = `${allowHeaders}, authorization`
+  }
+  if (allowHeaders !== undefined && allowHeaders !== '') headers['access-control-allow-headers'] = allowHeaders
+  headers['access-control-max-age'] = policy.maxAge
+  headers['allow'] = allow
+  headers['vary'] = PREFLIGHT_VARY
+  return headers
+}
+
+/** `access-control-request-headers` when it is a valid list of header names, lower-cased. */
+function requestedHeaders(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const names: string[] = []
+  for (const item of value.split(',')) {
+    const name = item.trim()
+    if (name === '') continue
+    if (!isHeaderName(name)) return undefined
+    names.push(name.toLowerCase())
+  }
+  return names.length === 0 ? undefined : names.join(', ')
+}
+
+/** CORS headers of a reply to an allowed origin (added when missing). */
+export function corsReplyHeaders(policy: CorsPolicy, origin: string): Record<string, HeaderValue> {
+  const headers: Record<string, HeaderValue> = { 'access-control-allow-origin': policy.wildcard ? '*' : origin }
+  if (policy.credentials) headers['access-control-allow-credentials'] = 'true'
+  if (policy.exposeHeaders !== undefined) headers['access-control-expose-headers'] = policy.exposeHeaders
+  return headers
+}
+
+/** Adds `token` to the `vary` header, unless it (or `*`) is already listed. */
+export function mergeVary(headers: Record<string, HeaderValue>, token: string): void {
+  const existing = headers['vary']
+  if (existing === undefined) {
+    headers['vary'] = token
+    return
+  }
+  const text = typeof existing === 'string' ? existing : existing.join(', ')
+  const tokens = text.split(',').map(item => item.trim().toLowerCase())
+  if (tokens.includes('*') || tokens.includes(token)) return
+  headers['vary'] = text.trim() === '' ? token : `${text}, ${token}`
+}

package/src/decisions.ts

@@ -0,0 +1,331 @@
+/**
+ * Route decisions (RFC 0001 §5.1, §5.2): route decorator groups as known at boot, the effective
+ * metadata of a route (the nearest decision of a group wins) and the boot check of required and
+ * enforced groups (ZNIGHT023).
+ */
+import type { CoreLogger } from '@znight/core'
+import type { RouteDecoratorInfo } from './decorators.ts'
+import type { HttpMetadata } from './metadata.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+
+import { GROUP_NAME } from './decorators.ts'
+
+/** Route metadata: key → value. */
+export type RouteMeta = Readonly<Record<string, unknown>>
+
+/** Where a group declaration comes from (messages). */
+interface Declaration {
+  readonly group: string
+  readonly required: boolean
+  readonly source: string
+}
+
+/**
+ * The route decorator groups of an application: the compiled `groups` metadata, completed by the
+ * `enforces` declarations of the guards and the `meta` entries of plugin routes. A key absent from
+ * every source is its own group, not required.
+ */
+export class RouteGroups {
+  readonly #keys = new Map<string, Declaration>()
+  readonly #groups = new Map<string, Declaration>()
+  readonly #members = new Map<string, Set<string>>()
+
+  /** Reads `metadata.extensions.http.groups` (ZNIGHT007 when malformed). */
+  static fromMetadata(groups: HttpMetadata['groups']): RouteGroups {
+    const result = new RouteGroups()
+    if (groups === undefined) return result
+    if (groups === null || typeof groups !== 'object' || Array.isArray(groups)) {
+      throw malformed(`expected an object of { keys, required } (received ${describe(groups)})`)
+    }
+    for (const group of Object.keys(groups)) {
+      const entry: unknown = groups[group]
+      const { keys, required } = (entry ?? {}) as { keys?: unknown; required?: unknown }
+      // a group is named explicitly (grammar) or after its single key (a decorator without group)
+      const ownGroup = Array.isArray(keys) && keys.length === 1 && keys[0] === group
+      if (!ownGroup && !GROUP_NAME.test(group)) throw malformed(`invalid group name ${JSON.stringify(group)}`)
+      if (
+        entry === null ||
+        typeof entry !== 'object' ||
+        !Array.isArray(keys) ||
+        keys.length === 0 ||
+        !keys.every(key => typeof key === 'string' && key !== '') ||
+        new Set(keys).size !== keys.length ||
+        typeof required !== 'boolean'
+      ) {
+        throw malformed(`group "${group}" must be { keys: [unique non-empty strings], required: boolean }`)
+      }
+      for (const key of keys as string[]) {
+        const previous = result.#keys.get(key)
+        if (previous !== undefined) {
+          throw malformed(`the key "${key}" belongs to the groups "${previous.group}" and "${group}"`)
+        }
+        result.#add(key, { group, required, source: 'the compiled metadata' })
+      }
+    }
+    return result
+  }
+
+  /**
+   * Declares the group of a key (guard `enforces`, plugin route `meta`). A declaration that
+   * contradicts an earlier one is ZNIGHT005.
+   */
+  declare(info: RouteDecoratorInfo, source: string): void {
+    const known = this.#keys.get(info.key)
+    if (known !== undefined && (known.group !== info.group || known.required !== info.required)) {
+      throw conflict(
+        `the route decorator "${info.key}" is declared with ${describeGroup(info)} by ${source} but with ${describeGroup({ key: info.key, ...known })} by ${known.source}`,
+      )
+    }
+    const group = this.#groups.get(info.group)
+    if (group !== undefined && group.required !== info.required) {
+      throw conflict(
+        `the "${info.group}" group is ${info.required ? '' : 'not '}required for "${info.key}" (${source}) but ${group.required ? '' : 'not '}required for ${[...(this.#members.get(info.group) ?? [])].map(key => `"${key}"`).join(', ')} (${group.source})`,
+      )
+    }
+    if (known === undefined) this.#add(info.key, { group: info.group, required: info.required, source })
+  }
+
+  /** The group of a key (the key itself when no source declares one). */
+  groupOf(key: string): string {
+    return this.#keys.get(key)?.group ?? key
+  }
+
+  /** Groups every route must decide. */
+  required(): Set<string> {
+    const result = new Set<string>()
+    for (const [group, declaration] of this.#groups) if (declaration.required) result.add(group)
+    return result
+  }
+
+  /** Known keys of a group, sorted. */
+  keysOf(group: string): string[] {
+    return [...(this.#members.get(group) ?? [group])].sort()
+  }
+
+  #add(key: string, declaration: Declaration): void {
+    this.#keys.set(key, declaration)
+    if (!this.#groups.has(declaration.group)) this.#groups.set(declaration.group, declaration)
+    let members = this.#members.get(declaration.group)
+    if (members === undefined) {
+      members = new Set()
+      this.#members.set(declaration.group, members)
+    }
+    members.add(key)
+  }
+}
+
+function describeGroup(info: { readonly key: string; readonly group: string; readonly required: boolean }): string {
+  const group = info.group === info.key ? 'its own group' : `the group "${info.group}"`
+  return info.required ? `${group} (required)` : group
+}
+
+/**
+ * The effective metadata of a route: the controller's entries whose group the route does not
+ * decide, then every entry of the route. Frozen.
+ */
+export function effectiveMeta(controller: RouteMeta, route: RouteMeta, groupOf: (key: string) => string): RouteMeta {
+  const decided = new Set(Object.keys(route).map(groupOf))
+  const result: Record<string, unknown> = {}
+  for (const key of Object.keys(controller)) {
+    if (!decided.has(groupOf(key))) result[key] = controller[key]
+  }
+  return Object.freeze(Object.assign(result, route))
+}
+
+/** The key of `meta` sharing its group with another key, as `[first, second, group]`. */
+export function conflictingKeys(
+  meta: RouteMeta,
+  groupOf: (key: string) => string,
+): readonly [string, string, string] | undefined {
+  const seen = new Map<string, string>()
+  for (const key of Object.keys(meta)) {
+    const group = groupOf(key)
+    const first = seen.get(group)
+    if (first !== undefined) return [first, key, group]
+    seen.set(group, key)
+  }
+  return undefined
+}
+
+/** The groups listed by `static enforces` of a guard class (ZNIGHT005 when malformed). */
+export function enforcedBy(guard: unknown, name: string): readonly RouteDecoratorInfo[] {
+  if (typeof guard !== 'function') return []
+  let enforces: unknown
+  try {
+    enforces = (guard as { enforces?: unknown }).enforces
+  } catch (error) {
+    throw invalidEnforces(name, 'reading it threw', error)
+  }
+  if (enforces === undefined) return []
+  if (!Array.isArray(enforces))
+    throw invalidEnforces(name, `expected an array of route decorators (received ${describe(enforces)})`)
+  for (const entry of enforces as unknown[]) {
+    const info = (typeof entry === 'function' || (typeof entry === 'object' && entry !== null) ? entry : {}) as {
+      key?: unknown
+      group?: unknown
+      required?: unknown
+    }
+    if (typeof info.key !== 'string' || typeof info.group !== 'string' || typeof info.required !== 'boolean') {
+      throw invalidEnforces(
+        name,
+        `every entry must be a route decorator ({ key, group, required }), received ${describe(entry)}`,
+      )
+    }
+  }
+  return enforces as readonly RouteDecoratorInfo[]
+}
+
+function invalidEnforces(name: string, reason: string, cause?: unknown): ZnightError {
+  return new ZnightError(
+    ErrorCode.InvalidDecorator,
+    `HttpPlugin: invalid static enforces of the guard ${name}: ${reason}`,
+    {
+      hints: [
+        'static readonly enforces = [Public, Authenticated, Roles] (decorators created with createRouteDecorator)',
+      ],
+      ...(cause === undefined ? {} : { cause }),
+    },
+  )
+}
+
+/** A route as seen by the boot check: one per declared route (no HEAD or trailing-slash variant). */
+export interface CheckedRoute {
+  /** `GET /books (BookController.list)`. */
+  readonly description: string
+  /** Effective metadata. */
+  readonly meta: RouteMeta
+  /** Groups enforced by the guards of its chain (global, controller, route). */
+  readonly enforced: ReadonlySet<string>
+  /** Name of the plugin declaring the route, for plugin routes. */
+  readonly plugin?: string
+}
+
+/** How the boot check reports problems. */
+export type EnforcementMode = 'error' | 'warn'
+
+/**
+ * The boot check (RFC 0001 §5.2): every route decides every required group, and every decision of
+ * a required or enforced group is enforced by a guard of the route's chain. A group is enforced when
+ * a guard of some chain, or a guard class of the application (`enforcers`, in a chain or not),
+ * declares it: a guard registered nowhere does not make its decisions inert. Problems are reported
+ * as one ZNIGHT023 error (`'error'`) or one warning per group (`'warn'`).
+ */
+export function checkDecisions(
+  routes: readonly CheckedRoute[],
+  groups: RouteGroups,
+  mode: EnforcementMode,
+  logger: CoreLogger,
+  enforcers: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): void {
+  const required = groups.required()
+  const known = new Set<string>(enforcers.keys())
+  for (const route of routes) for (const group of route.enforced) known.add(group)
+  const problems = new Map<string, { missing: string[]; unenforced: string[]; plugins: Set<string> }>()
+  const problem = (group: string): { missing: string[]; unenforced: string[]; plugins: Set<string> } => {
+    let entry = problems.get(group)
+    if (entry === undefined) {
+      entry = { missing: [], unenforced: [], plugins: new Set() }
+      problems.set(group, entry)
+    }
+    return entry
+  }
+  for (const route of routes) {
+    const decided = new Set(Object.keys(route.meta).map(key => groups.groupOf(key)))
+    for (const group of required) {
+      if (decided.has(group)) continue
+      const entry = problem(group)
+      entry.missing.push(route.description)
+      if (route.plugin !== undefined) entry.plugins.add(route.plugin)
+    }
+    for (const group of decided) {
+      if ((required.has(group) || known.has(group)) && !route.enforced.has(group)) {
+        problem(group).unenforced.push(route.description)
+      }
+    }
+  }
+  if (problems.size === 0) return
+  const messages: string[] = []
+  const hints: string[] = []
+  for (const group of [...problems.keys()].sort()) {
+    const entry = problems.get(group) as { missing: string[]; unenforced: string[]; plugins: Set<string> }
+    const keys = groups.keysOf(group)
+    const parts: string[] = []
+    const groupHints: string[] = []
+    if (entry.missing.length > 0) {
+      parts.push(
+        `${count(entry.missing.length)} ${entry.missing.length === 1 ? 'has' : 'have'} no "${group}" decision: ${entry.missing.join(', ')}`,
+      )
+      groupHints.push(`Add a decision of the "${group}" group (${keys.join(', ')}) to the route or to its controller`)
+      for (const plugin of [...entry.plugins].sort()) {
+        groupHints.push(
+          `Routes of the plugin "${plugin}" take their metadata from its options: meta: [Decorator.meta()]`,
+        )
+      }
+    }
+    if (entry.unenforced.length > 0) {
+      parts.push(
+        `no guard enforces the ${required.has(group) ? 'required ' : ''}"${group}" group on ${count(entry.unenforced.length)}: ${entry.unenforced.join(', ')}`,
+      )
+      const guards = [...(enforcers.get(group) ?? [])].sort()
+      // a guard of the application that enforces the group, else a name for the one to write
+      const example = guards[0] ?? guardName(group)
+      groupHints.push(
+        `Register a guard declaring \`static enforces\` with the decorators of the "${group}" group (${keys.join(', ')}), e.g. HttpPlugin.configure({ guards: [${example}] })`,
+      )
+      if (guards.length > 0) {
+        groupHints.push(`Guards of the application enforcing the "${group}" group: ${guards.join(', ')}`)
+      }
+    }
+    const message = parts.join('; ')
+    if (mode === 'warn') {
+      logger.warn(`HttpPlugin: ${message}`, { code: ErrorCode.MissingRouteDecision, group })
+    } else {
+      messages.push(message)
+      hints.push(...groupHints)
+    }
+  }
+  if (mode === 'error') {
+    hints.push("Tests that deliberately run without guards can set enforcement: 'warn'")
+    throw new ZnightError(ErrorCode.MissingRouteDecision, `HttpPlugin: ${capitalize(messages.join('; '))}`, { hints })
+  }
+}
+
+function count(routes: number): string {
+  return routes === 1 ? '1 route' : `${routes} routes`
+}
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+/** A class name for the guard of a group: `rateLimit` → `RateLimitGuard`, `auth:public` → `AuthPublicGuard`. */
+function guardName(group: string): string {
+  const name = group
+    .split(/[^A-Za-z0-9]+/)
+    .map(capitalize)
+    .join('')
+    .replace(/^\d+/, '')
+  return `${name === '' ? 'Decision' : name}Guard`
+}
+
+function malformed(reason: string): ZnightError {
+  return new ZnightError(ErrorCode.InvalidRoute, `Invalid metadata.extensions.http.groups: ${reason}`)
+}
+
+function conflict(reason: string): ZnightError {
+  return new ZnightError(ErrorCode.InvalidDecorator, `HttpPlugin: inconsistent route decorator groups: ${reason}`, {
+    hints: [
+      'Every definition of a key must use the same options, and the decorators of a group must agree on required',
+      'Regenerate the metadata when createRouteDecorator options changed',
+    ],
+  })
+}
+
+function describe(value: unknown): string {
+  try {
+    return typeof value === 'function' ? 'a function' : (JSON.stringify(value) ?? String(value))
+  } catch {
+    return typeof value
+  }
+}