@better-forge/config-as-code 0.0.0-stage → 0.1.0

package/src/routes.ts

@@ -0,0 +1,143 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest, onRequestAsyncHookHandler } from 'fastify'
+import { tokenAllows } from '@better-forge/contracts'
+import { clip, ConfigExportError, ConfigInvalidError, type Json } from './document.js'
+import type { ConfigEngine } from './engine.js'
+import { readDocuments, toYaml, toYamlStream } from './yaml.js'
+
+/** A configuration is a few hundred kilobytes at most; this leaves room without letting a request tie up the parser. */
+const BODY_LIMIT = 2 * 1024 * 1024
+const YAML_TYPES = ['application/yaml', 'application/x-yaml', 'text/yaml']
+
+/** Who may export and import one kind of document. */
+export interface KindAccess {
+  /** The API token permission prefix: `<resource>:read` to export, `<resource>:write` to import. */
+  tokenResource: string
+  /** The roles of a signed-in user who may export and import it. */
+  roles: readonly string[]
+  /** The role named in the message when a user may not. */
+  roleLabel: string
+  /** Left out of a full export for a reader who may not see it, instead of refusing the whole export. */
+  optional?: boolean
+}
+
+/** The caller of a request, as far as the routes need to know. */
+export interface ConfigCaller {
+  role: string
+  apiToken?: { scopes: readonly string[] } | undefined
+}
+
+export interface ConfigRoutesOptions<Actor> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  engine: ConfigEngine<any, any, Actor>
+  access: Readonly<Record<string, KindAccess>>
+  identity: (req: FastifyRequest) => ConfigCaller
+  /** What the caller is recorded as in the audit log. */
+  actor: (req: FastifyRequest) => Actor
+  /** Hooks that run before a file is read (the application's own role check). */
+  guards: readonly onRequestAsyncHookHandler[]
+  /** Kinds a file needs permission for beyond the kinds of its documents (for example the kind a document links to). */
+  linkedKinds?: (documents: unknown[]) => readonly string[]
+}
+
+/** The routes to export the configuration as YAML and to validate or apply a YAML file. A plugin to register with `app.register`. */
+export function createConfigRoutes<Actor>(options: ConfigRoutesOptions<Actor>) {
+  const { engine, access, identity } = options
+  const kindNames = engine.kinds
+  const tokenResources = kindNames.map((kind) => access[kind]!.tokenResource)
+
+  /** The kinds `caller` may not read (or write), with the reason, or null when it may do all of them. */
+  function refusal(caller: ConfigCaller, kinds: Iterable<string>, mode: 'read' | 'write'): string | null {
+    const refused: string[] = []
+    for (const kind of kinds) {
+      const rule = access[kind]!
+      if (caller.apiToken) {
+        const needed = `${rule.tokenResource}:${mode}`
+        if (!tokenAllows(caller.apiToken.scopes, needed)) refused.push(`${kind} (the token needs "${needed}")`)
+      } else if (!rule.roles.includes(caller.role)) {
+        refused.push(`${kind} (needs the ${rule.roleLabel} role)`)
+      }
+    }
+    return refused.length ? `You may not ${mode === 'read' ? 'export' : 'import'}: ${refused.join(', ')}` : null
+  }
+
+  /** The kinds a file needs permission for: its own, and those its documents link to. */
+  function kindsNeeded(documents: unknown[]): Set<string> {
+    const kinds = engine.kindsIn(documents)
+    for (const linked of options.linkedKinds?.(documents) ?? []) kinds.add(linked)
+    return kinds
+  }
+
+  const optionalKinds = kindNames.filter((kind) => access[kind]!.optional)
+
+  return async function configRoutes(app: FastifyInstance) {
+    // A YAML body is handed to the handler as text and parsed there, after the request has been authenticated.
+    app.addContentTypeParser(YAML_TYPES, { parseAs: 'string', bodyLimit: BODY_LIMIT }, (_req, body, done) => done(null, body))
+
+    // One document (`?kind=Note&key=first`), or all of them, as YAML.
+    app.get<{ Querystring: { kind?: string; key?: string } }>('/export', async (req, reply) => {
+      const { kind, key } = req.query
+      if (kind !== undefined && !kindNames.includes(kind)) {
+        return reply.code(400).send({ error: `kind must be one of: ${kindNames.join(', ')}` })
+      }
+      if (kind !== undefined && !key) return reply.code(400).send({ error: `key is required to export a ${kind}` })
+
+      const caller = identity(req)
+      const denied = refusal(caller, kind ? [kind] : kindNames.filter((each) => !optionalKinds.includes(each)), 'read')
+      if (denied) return reply.code(403).send({ error: denied })
+      // Without a key a full export holds the optional kinds only for who may read them.
+      const included = new Set(kindNames.filter((each) => !optionalKinds.includes(each) || refusal(caller, [each], 'read') === null))
+
+      let documents: Json[]
+      try {
+        documents = await engine.exportDocuments(kind ? { kind, key: key! } : undefined, { included })
+      } catch (error) {
+        if (error instanceof ConfigExportError) return reply.code(409).send({ error: error.message })
+        throw error
+      }
+      if (kind) {
+        const found = engine.pickDocument(documents, kind, key)
+        if (!found) return reply.code(404).send({ error: `There is no ${kind} with the key "${clip(String(key))}"` })
+        return reply.type('application/yaml; charset=utf-8').send(toYaml(found))
+      }
+      return reply.type('application/yaml; charset=utf-8').send(toYamlStream(documents))
+    })
+
+    async function run(req: FastifyRequest<{ Body: unknown; Querystring: { prune?: string } }>, reply: FastifyReply, dryRun: boolean) {
+      const { prune } = req.query
+      if (prune !== undefined && prune !== 'true' && prune !== 'false') return reply.code(400).send({ error: 'prune must be true or false' })
+      const read = readDocuments(req.body)
+      if ('error' in read) return reply.code(400).send({ error: read.error })
+      if (read.documents.length === 0) return reply.code(400).send({ error: 'The file contains no documents' })
+      const caller = identity(req)
+      const denied = refusal(caller, kindsNeeded(read.documents), 'write')
+      if (denied) return reply.code(403).send({ error: denied })
+
+      try {
+        return await engine.importDocuments(read.documents, { dryRun, actor: options.actor(req), token: caller.apiToken, prune: prune === 'true' })
+      } catch (error) {
+        if (error instanceof ConfigInvalidError) return reply.code(400).send({ error: error.message, problems: error.problems })
+        throw error
+      }
+    }
+
+    // Both check the caller before the body is read: parsing a 2 MiB file is work only someone who may import it may ask for.
+    // What the caller may import is decided per kind of document once the file is read.
+    const mayWriteSomething: onRequestAsyncHookHandler = async (req, reply) => {
+      const token = identity(req).apiToken
+      if (token && !tokenResources.some((resource) => tokenAllows(token.scopes, `${resource}:write`))) {
+        const needs = tokenResources.map((resource) => `"${resource}:write"`)
+        return reply.code(403).send({ error: `This token has no permission to import: it needs ${needs.slice(0, -1).join(', ')} or ${needs.at(-1)}` })
+      }
+    }
+    // Only YAML is read, and this is checked before the body is, so a JSON body is never parsed.
+    const onlyYaml: onRequestAsyncHookHandler = async (req, reply) => {
+      const type = (req.headers['content-type'] ?? '').split(';')[0]!.trim().toLowerCase()
+      if (!YAML_TYPES.includes(type)) return reply.code(415).send({ error: 'Send the documents as YAML, with Content-Type: application/yaml' })
+    }
+    const routeOptions = { onRequest: [...options.guards, mayWriteSomething, onlyYaml], bodyLimit: BODY_LIMIT }
+    // What importing the documents would change, without changing anything.
+    app.post<{ Body: unknown; Querystring: { prune?: string } }>('/validate', routeOptions, (req, reply) => run(req, reply, true))
+    // Makes the installation match the documents, completely or not at all.
+    app.post<{ Body: unknown; Querystring: { prune?: string } }>('/apply', routeOptions, (req, reply) => run(req, reply, false))
+  }
+}

package/src/yaml.ts

@@ -0,0 +1,64 @@
+import { Document, parseAllDocuments, visit } from 'yaml'
+
+/** Anchors are legitimate in a hand-written file, but a few are plenty and unbounded aliases are a decompression bomb. */
+const MAX_YAML_ALIASES = 20
+/** Documents one file may hold. */
+export const MAX_DOCUMENTS = 2_000
+/** Longest part of a parser error that is repeated to the caller. */
+const MAX_ERROR_LENGTH = 300
+
+/**
+ * Strings the library leaves bare although a parser reads them as something else: `<<` is the YAML 1.1 merge key (as a
+ * key it merges, or fails), and `0o17` is a number in YAML 1.2 but a string in 1.1.
+ */
+const NEEDS_QUOTES = /^(<<|=|0o[0-7]+)$/
+
+/**
+ * No line folding: URLs and templates must stay on one line to be readable and diff well. Version 1.1 makes the
+ * writer quote what an older parser would misread ("22:00" is a number there, "yes" and "on" are booleans), so the
+ * file means the same to every YAML tool, Terraform's included.
+ */
+export function toYaml(value: unknown): string {
+  const document = new Document(value, { version: '1.1' })
+  visit(document, {
+    Scalar(position, node) {
+      if (typeof node.value !== 'string' || !NEEDS_QUOTES.test(node.value)) return
+      node.type = 'QUOTE_DOUBLE'
+      // The 1.1 schema recognises the string `<<` as the merge key and would write it bare whatever the style; as a
+      // key it needs an explicit string tag. As a value it is plain text and quoting is enough.
+      if (position === 'key' && node.value === '<<') node.tag = 'tag:yaml.org,2002:str'
+    },
+  })
+  return document.toString({ lineWidth: 0 })
+}
+
+/** Several documents in one YAML file, separated the usual way. */
+export const toYamlStream = (documents: unknown[]): string => documents.map(toYaml).join('---\n')
+
+const clip = (value: string, max: number) => value.length > max ? `${value.slice(0, max)}…` : value
+
+/**
+ * The documents of a YAML text, in the order they are written (empty ones left out), or the reason it was refused.
+ * The text is parsed with the YAML 1.2 core schema; a `%YAML` line would switch to rules under which `yes` is a
+ * boolean and `22:00` a number, so it is refused.
+ */
+export function readDocuments(body: unknown): { documents: unknown[] } | { error: string } {
+  if (typeof body !== 'string') return { error: 'Send the documents as YAML' }
+  if (/^%YAML/m.test(body)) return { error: 'Invalid YAML: %YAML directives are not supported' }
+  try {
+    const documents: unknown[] = []
+    for (const document of parseAllDocuments(body)) {
+      if (document.errors.length) throw document.errors[0]
+      const value: unknown = document.toJS({ maxAliasCount: MAX_YAML_ALIASES })
+      // An alias inside the thing it is an alias of (`a: &x { b: *x }`) parses into a circular object, which JSON
+      // cannot hold and nothing downstream could compare or store.
+      JSON.stringify(value)
+      if (value !== null && value !== undefined) documents.push(value)
+      if (documents.length > MAX_DOCUMENTS) return { error: `Too many documents: at most ${MAX_DOCUMENTS}` }
+    }
+    return { documents }
+  } catch (error) {
+    const circular = error instanceof TypeError && /circular/i.test(error.message)
+    return { error: circular ? 'Invalid YAML: an alias may not refer to a value that contains it' : clip(`Invalid YAML: ${error instanceof Error ? error.message : String(error)}`, MAX_ERROR_LENGTH) }
+  }
+}