mega-framework 0.1.0

package/src/core/multipart.js

@@ -0,0 +1,282 @@
+// @ts-check
+/**
+ * MegaApp 파일 업로드 자동 등록 — `@fastify/multipart` 통합.
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   웹에서 사진·문서를 올리면 브라우저는 `multipart/form-data` 라는 형식으로 파일을 쪼개 보낸다.
+ *   본 모듈은 검증된 공개 플러그인 `@fastify/multipart` 를 앱 config 의 `upload` 키 기반으로 자동 등록하고,
+ *   그 위에 **보안(허용 MIME·크기·개수·경로 탐색)** 과 **관측성(트레이싱 span·메트릭)** 을 얹는다.
+ *
+ * # 동작 한눈에 (security.js / session.js 형제 패턴)
+ *   1. `registerMultipart(fastify, { upload })` — `upload` 가 있을 때만 옵트인 등록(없으면 multipart 미지원=415).
+ *   2. `@fastify/multipart` 를 `limits`(fileSize/files/parts) + `throwFileSizeLimit:true` 로 등록 →
+ *      `req.file()/req.files()/parts()/saveRequestFiles()` 데코레이터 제공.
+ *   3. multipart 요청에 한해 `req.file()/req.files()` 를 **MIME 화이트리스트 게이트**로 감싼다(비허용 → 415).
+ *   4. `req.saveUploads(destDir)` — 파일명 살균(path traversal 차단) + 스트리밍 저장 + `mega.upload` span +
+ *      `mega_upload_*` 메트릭.
+ *
+ * # 보안 (12-performance-security / 02-architecture §1502·1625)
+ *   - **크기 제한**: `upload.maxFileSize`(디폴트 10 MB) → `limits.fileSize` + `throwFileSizeLimit` → 초과 시
+ *     플러그인이 413 throw(절단 후 silent 통과 없이 명시 실패).
+ *   - **개수 제한**: `upload.maxFiles` → `limits.files` → 초과 시 413.
+ *   - **MIME 화이트리스트**: `upload.allowedMimeTypes`(빈 배열=전부 허용). 정확 매치 + `type/*` 와일드카드.
+ *     플러그인 내장 기능이 아니라 본 모듈이 게이트로 강제 → 비허용 415(`MegaUnsupportedMediaTypeError`).
+ *   - **경로 탐색(path traversal) 차단**: 저장 시 `sanitizeFilename`(basename + 선행 점 제거)으로 파일명에서
+ *     디렉터리 성분을 제거하고, 최종 경로가 대상 디렉터리 내부인지 한 번 더 검증(이중 방어).
+ *   - **MIME 스푸핑 한계**: 게이트는 클라가 선언한 `Content-Type`(part header) 기준이다. 매직바이트 스니핑은
+ *     하지 않는다(스트림 1패스 비용 회피). 선언 MIME 위조 가능성은 문서화된 한계이며, 진짜 콘텐츠 검증이
+ *     필요하면 핸들러에서 `toBuffer()` 후 별도 검사한다.
+ *
+ * # 트레이싱·메트릭
+ *   - 트레이싱: `req.saveUploads` 가 `MegaTracing.span('mega.upload', …)` 로 감싸 `mega.upload.{files,bytes,dir}`
+ *     속성을 박는다. MIME 거부는 활성 span 에 `mega.upload.reason='rejected_mime'` 기록.
+ *   - 메트릭: `recordUpload({ result })` — accepted(MIME 통과)/rejected_mime/saved + 크기 히스토그램.
+ *
+ * # CSRF·ASP 통합
+ *   - **CSRF**: `security.js` 가 `multipart/form-data` 를 **폼**으로 분류해 CSRF 토큰을 검증한다(per ADR-051) —
+ *     별도 배선 없이 자동 적용. 업로드 폼은 `_csrf` 토큰을 함께 보내야 한다.
+ *   - **ASP**: ASP 활성 경로의 multipart body 는 복호화하지 않고 평문으로 파서에 넘긴다(02-architecture §1625,
+ *     `asp/plugin.js` preParsing). 인증(ts/drift/signal)·응답 암호화는 유지 → Content-Type 위조로 ASP 자체를
+ *     우회할 수 없다.
+ *
+ * @module core/multipart
+ * @see ADR-133
+ * @see https://github.com/fastify/fastify-multipart (@fastify/multipart v10)
+ */
+import { mkdir, unlink } from 'node:fs/promises'
+import { createWriteStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { pipeline } from 'node:stream/promises'
+import { basename, resolve, sep } from 'node:path'
+import fastifyMultipart from '@fastify/multipart'
+import { MegaUnsupportedMediaTypeError, MegaPayloadTooLargeError } from '../errors/http-errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import * as MegaMetrics from '../lib/mega-metrics.js'
+
+/** 업로드 파일 크기 디폴트 상한 (10 MB — 02-architecture §1502). */
+export const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024
+
+/**
+ * 업로드 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} MultipartSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {number} maxFileSize - 적용된 파일 크기 상한(bytes).
+ * @property {number|null} maxFiles - 파일 개수 상한(null=무제한).
+ * @property {string[]} allowedMimeTypes - 허용 MIME 목록(빈 배열=전부 허용).
+ */
+
+/**
+ * 파일명을 안전한 단일 파일명으로 살균한다 (path traversal 차단).
+ *
+ * `basename` 으로 디렉터리 성분(`../`, `/`, `\`)을 모두 제거하고, 남은 선행 점(`.`/`..`/`.bashrc` 류)과
+ * NUL·제어문자를 제거한다. 빈 문자열이 되면 `'upload'` 로 폴백한다 — 빈 파일명이 디렉터리로 해석되는 걸 막는다.
+ *
+ * @param {unknown} name - 클라가 보낸 원본 파일명(신뢰 불가).
+ * @returns {string} 디렉터리 성분 없는 안전한 파일명.
+ * @example sanitizeFilename('../../etc/passwd') // 'passwd'
+ * @example sanitizeFilename('..')               // 'upload'
+ */
+export function sanitizeFilename(name) {
+  // 백슬래시(Windows 구분자)를 '/' 로 정규화 — POSIX 의 path.basename 은 '\' 를 구분자로 안 보므로
+  // 'C:\\..\\evil.exe' 같은 윈도우식 경로가 통째로 남는 걸 막는다(클라가 보낸 파일명은 OS 무관 신뢰 불가).
+  const normalized = String(name ?? '').replace(/\\/g, '/')
+  // basename 이 '../../etc/passwd'→'passwd', 'a/b.png'→'b.png', '..'→'..' 로 디렉터리 성분을 떼낸다.
+  const base = basename(normalized)
+  // NUL·제어문자 제거(파일시스템 인젝션 방지) + 선행 점 제거('..'·'.'·숨김파일 → 일반 파일명화).
+  // eslint-disable-next-line no-control-regex -- NUL·제어문자(0x00~0x1f)를 의도적으로 제거한다.
+  const cleaned = base.replace(/[\x00-\x1f]/g, '').replace(/^\.+/, '')
+  return cleaned.length > 0 ? cleaned : 'upload'
+}
+
+/**
+ * MIME 타입이 화이트리스트에 허용되는지 (Boolean — `is*`). 빈 목록/미지정이면 **전부 허용**(게이트 비활성).
+ * 정확 매치 + `type/*` 와일드카드(예: `'image/*'` 는 `'image/png'` 허용)를 지원한다.
+ *
+ * @param {string} mimetype - 검사할 MIME(part header 선언값).
+ * @param {string[]} [allowedMimeTypes] - 허용 목록. 빈 배열/미지정 → 전부 허용.
+ * @returns {boolean}
+ */
+export function isMimeAllowed(mimetype, allowedMimeTypes) {
+  if (!Array.isArray(allowedMimeTypes) || allowedMimeTypes.length === 0) return true // 게이트 비활성.
+  const mime = String(mimetype ?? '').toLowerCase()
+  for (const entry of allowedMimeTypes) {
+    if (typeof entry !== 'string' || entry.length === 0) continue
+    const allow = entry.toLowerCase()
+    if (allow === mime) return true // 정확 매치.
+    if (allow.endsWith('/*') && mime.startsWith(allow.slice(0, -1))) return true // 'image/*' → 'image/'.
+  }
+  return false
+}
+
+/**
+ * `upload` config 를 정규화한다. `null` 이면 미옵트인(등록 안 함).
+ * @param {unknown} upload
+ * @returns {{ maxFileSize: number, maxFiles: number|null, allowedMimeTypes: string[] } | null}
+ */
+function normalizeUpload(upload) {
+  if (!upload || typeof upload !== 'object') return null
+  const u = /** @type {Record<string, any>} */ (upload)
+  const maxFileSize =
+    Number.isInteger(u.maxFileSize) && u.maxFileSize > 0 ? u.maxFileSize : DEFAULT_MAX_FILE_SIZE
+  const maxFiles = Number.isInteger(u.maxFiles) && u.maxFiles > 0 ? u.maxFiles : null
+  const allowedMimeTypes = Array.isArray(u.allowedMimeTypes)
+    ? u.allowedMimeTypes.filter((/** @type {unknown} */ t) => typeof t === 'string' && t.length > 0)
+    : []
+  return { maxFileSize, maxFiles, allowedMimeTypes }
+}
+
+/**
+ * Fastify 인스턴스에 `@fastify/multipart` 를 자동 등록하고 MIME 게이트·안전 저장·관측성을 배선한다.
+ *
+ * `upload` 가 없으면 **미등록**(옵트인) — multipart 요청은 Fastify 가 415(파서 없음)로 거부한다. session.js
+ * 패턴 정합. 호출 순서는 보안 플러그인 등록 이후·라우트 등록 이전 어디든 무방하다(글로벌 onRequest hook +
+ * request 데코레이터라 라우트 등록 순서와 무관).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.upload - `MegaUploadConfig`(maxFileSize/maxFiles/allowedMimeTypes). falsy 면 미등록.
+ * @param {string} [opts.appName] - 앱 이름(메트릭 라벨·로그용).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {MultipartSummary}
+ */
+export function registerMultipart(fastify, { upload, appName = '(unknown)', logger } = /** @type {any} */ ({})) {
+  const cfg = normalizeUpload(upload)
+  if (cfg === null) {
+    return { enabled: false, maxFileSize: DEFAULT_MAX_FILE_SIZE, maxFiles: null, allowedMimeTypes: [] }
+  }
+
+  // @fastify/multipart 등록 — limits 로 크기·개수 강제, throwFileSizeLimit 로 초과 시 throw(절단 silent 금지).
+  fastify.register(fastifyMultipart, /** @type {any} */ ({
+    throwFileSizeLimit: true,
+    limits: {
+      fileSize: cfg.maxFileSize,
+      ...(cfg.maxFiles !== null ? { files: cfg.maxFiles } : {}),
+    },
+  }))
+
+  /**
+   * MIME 화이트리스트 게이트 — 허용이면 'accepted' 메트릭, 비허용이면 활성 span 기록 + 415 throw.
+   * @param {{ mimetype: string, filename: string, fieldname: string }} file
+   * @returns {void}
+   */
+  const gateMime = (file) => {
+    if (isMimeAllowed(file.mimetype, cfg.allowedMimeTypes)) {
+      MegaMetrics.recordUpload({ app: appName, result: 'accepted' })
+      return
+    }
+    // 비허용 MIME — 활성 HTTP span 에 사유 기록(security.js annotateReject 정합) + 메트릭 + 415.
+    MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.upload.reason': 'rejected_mime' })
+    MegaMetrics.recordUpload({ app: appName, result: 'rejected_mime' })
+    logger?.debug?.({ app: appName, mimetype: file.mimetype, field: file.fieldname }, 'upload.rejected (mime)')
+    throw new MegaUnsupportedMediaTypeError('upload.unsupported_media_type', `Upload rejected: MIME '${file.mimetype}' is not allowed.`, {
+      details: { mimetype: file.mimetype, allowed: cfg.allowedMimeTypes },
+    })
+  }
+
+  // multipart 요청에 한해 req.file()/req.files() 를 MIME 게이트로 감싼다. onRequest 시점에 본 hook 이 돌고,
+  // 핸들러가 그 뒤에 req.file()/req.files() 를 부르므로 래퍼가 항상 먼저 설치된다. 비-multipart 요청은
+  // 래핑하지 않는다(불필요한 오버헤드 회피 — content-type 헤더로 판별).
+  fastify.addHook('onRequest', async (req) => {
+    const ct = String(req.headers['content-type'] ?? '')
+    if (!ct.includes('multipart/form-data')) return
+    const r = /** @type {any} */ (req)
+    const origFile = r.file // 플러그인 프로토타입 메서드(아직 미래핑).
+    const origFiles = r.files
+    if (typeof origFile !== 'function' || typeof origFiles !== 'function') return // 플러그인 미등록 방어.
+
+    // 단일 파일 — 게이트 후 반환.
+    r.file = async (/** @type {any} */ fileOpts) => {
+      const f = await origFile.call(req, fileOpts)
+      if (f) gateMime(f)
+      return f
+    }
+    // 다중 파일 — 각 파일 게이트 후 yield(비허용 만나면 throw 전파, 이미 통과한 파일은 핸들러가 소비).
+    r.files = async function* (/** @type {any} */ filesOpts) {
+      for await (const f of origFiles.call(req, filesOpts)) {
+        gateMime(f)
+        yield f
+      }
+    }
+    // 안전 저장 — 파일명 살균 + 디렉터리 내부 검증 + 스트리밍 저장 + span + 메트릭. 게이트는 위 r.files() 재사용.
+    r.saveUploads = (/** @type {string} */ destDir, /** @type {{ filesOptions?: object }} */ saveOpts = {}) =>
+      saveUploads({ req, destDir, appName, saveOpts })
+  })
+
+  logger?.debug?.(
+    { app: appName, maxFileSize: cfg.maxFileSize, maxFiles: cfg.maxFiles, allowedMimeTypes: cfg.allowedMimeTypes.length },
+    'multipart.registered',
+  )
+  return { enabled: true, maxFileSize: cfg.maxFileSize, maxFiles: cfg.maxFiles, allowedMimeTypes: cfg.allowedMimeTypes }
+}
+
+/**
+ * 업로드된 모든 파일을 `destDir` 에 안전하게 저장한다(`req.saveUploads` 구현부). 파일명을 살균하고 최종
+ * 경로가 대상 디렉터리 내부인지 검증한 뒤 스트리밍으로 디스크에 쓴다. `mega.upload` span + `mega_upload_*`
+ * 메트릭을 기록한다. MIME 게이트는 래핑된 `req.files()` 가 적용한다(비허용 415 전파).
+ *
+ * @param {object} args
+ * @param {any} args.req - Fastify 요청(래핑된 `files()` 보유).
+ * @param {string} args.destDir - 저장 디렉터리(없으면 생성).
+ * @param {string} args.appName
+ * @param {{ filesOptions?: object }} [args.saveOpts]
+ * @returns {Promise<Array<{ fieldname: string, filename: string, savedAs: string, mimetype: string, encoding: string, bytes: number }>>}
+ * @throws {MegaUnsupportedMediaTypeError} 비허용 MIME(게이트). @throws {Error} 저장 I/O·크기 초과(413).
+ */
+async function saveUploads({ req, destDir, appName, saveOpts = {} }) {
+  return MegaTracing.span(
+    'mega.upload',
+    async (/** @type {import('@opentelemetry/api').Span} */ span) => {
+      const root = resolve(destDir)
+      await mkdir(root, { recursive: true })
+      /** @type {Array<{ fieldname: string, filename: string, savedAs: string, mimetype: string, encoding: string, bytes: number }>} */
+      const saved = []
+      /** @type {string[]} 이번 호출에서 디스크에 쓴 절대경로 — 실패 시 일괄 롤백(원자성). */
+      const written = []
+      let totalBytes = 0
+      try {
+        for await (const part of req.files(saveOpts.filesOptions)) {
+          const safeName = sanitizeFilename(part.filename)
+          const abs = resolve(root, safeName)
+          // 이중 방어 — 살균했어도 최종 경로가 root 내부(root/<파일>)가 아니면 거부.
+          if (!abs.startsWith(root + sep)) {
+            throw new Error(`upload.unsafe_path: resolved path escapes destDir (name='${part.filename}')`)
+          }
+          await pipeline(part.file, createWriteStream(abs))
+          written.push(abs)
+          // 크기 초과 검증 — throwFileSizeLimit 의 busboy 'limit' 은 **다음 part 이터레이션**에서야 throw 하므로,
+          // 그 사이 잘린 파일이 디스크에 남는다. 여기서 즉시 truncated 를 잡아 잘린 파일을 저장 성공으로 오인하지
+          // 않게 한다(부분저장 후 성공 위장 방지). 잔존 파일은 아래 catch 의 일괄 롤백이 정리한다.
+          if (part.file?.truncated) {
+            throw new MegaPayloadTooLargeError('upload.too_large', `Upload rejected: file '${safeName}' exceeds the size limit.`, {
+              details: { filename: safeName },
+            })
+          }
+          const { size } = await stat(abs)
+          totalBytes += size
+          MegaMetrics.recordUpload({ app: appName, result: 'saved', bytes: size })
+          saved.push({
+            fieldname: part.fieldname,
+            filename: safeName,
+            savedAs: abs,
+            mimetype: part.mimetype,
+            encoding: part.encoding,
+            bytes: size,
+          })
+        }
+      } catch (err) {
+        // 실패 시 이번 호출에서 쓴 파일 전부 롤백(원자성 — 부분 업로드 잔존 방지). 크기·개수 초과·MIME
+        // 거부·I/O 실패 모두 여기로 온다. 정리 실패는 비치명적이라 원인 에러를 가리지 않게 warn 만 남기고 재전파.
+        await Promise.allSettled(
+          written.map((p) =>
+            unlink(p).catch((cleanupErr) => req.log?.warn?.({ err: cleanupErr, path: p }, 'upload.cleanup failed (partial file)')),
+          ),
+        )
+        throw err
+      }
+      span?.setAttributes({ 'mega.upload.files': saved.length, 'mega.upload.bytes': totalBytes, 'mega.app': appName })
+      req.log?.debug?.({ app: appName, files: saved.length, bytes: totalBytes, dir: destDir }, 'upload.saved')
+      return saved
+    },
+    { attributes: { 'mega.app': appName } },
+  )
+}

package/src/core/openapi.js

@@ -0,0 +1,114 @@
+// @ts-check
+/**
+ * MegaApp OpenAPI/Swagger 자동 등록 — `@fastify/swagger` + `@fastify/swagger-ui` 옵트인 통합.
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   "이 API 가 어떤 주소로 뭘 받고 뭘 주는지" 설명서를 자동으로 만들어 웹페이지(`/docs`)로 보여준다.
+ *   라우트에 적어둔 JSON Schema 를 코어가 긁어모아 OpenAPI 3.x 명세로 만든다 — 손으로 문서 쓰다 어긋나는 일이 없다.
+ *   `apps/<name>/app.config.js` 의 `openapi` 를 켰을 때만(`enabled:true`) 등록한다(디폴트 OFF — 프로덕션 노출 방지).
+ *
+ * # 동작 한눈에 (multipart.js / static-assets.js 형제 패턴)
+ *   1. `registerOpenapi(fastify, { openapi })` — `enabled:true` 일 때만 옵트인 등록.
+ *   2. `@fastify/swagger`(OpenAPI 3.x 모드, `info` 주입)를 등록 → 라우트 schema 자동 수집(onRoute).
+ *   3. `@fastify/swagger-ui` 를 `routePrefix=path`(디폴트 `/docs`)로 등록 → 브라우저 명세 뷰어.
+ *   4. `auth` 미들웨어 배열이 있으면 docs 경로에 preHandler 가드(빈 배열=공개).
+ *
+ * # 보안 (ADR-070)
+ *   - **디폴트 OFF**: 옵트인이 아니면 명세·UI 라우트가 없어 프로덕션 API surface 가 외부에 안 드러난다.
+ *   - **env 토글**: `enabled: process.env.NODE_ENV !== 'production'` 패턴으로 dev 만 노출 가능.
+ *   - **auth 가드**: `auth` 미들웨어 배열로 docs 접근 보호(예 `requireRole('admin')`). 핸들러와 동일 `(req, reply, ctx)` 시그니처.
+ *   - **App-only 스코프**: 앱마다 자기 명세(다른 Fastify 인스턴스). 라우트는 코어 envelope 와 무관하게 swagger 가 자체 서빙.
+ *
+ * # 라우트 메타
+ *   라우트 옵션 `openapi:{ tags, summary, description, deprecated }`(router.js)가 라우트 schema 의 메타 필드로
+ *   병합돼 명세에 반영된다. 신규 클래스 없음 — Fastify 플러그인 위임만(ADR-070).
+ *
+ * @module core/openapi
+ * @see ADR-070
+ * @see ADR-140
+ * @see https://github.com/fastify/fastify-swagger (@fastify/swagger v9) / fastify-swagger-ui (v5)
+ */
+import fastifySwagger from '@fastify/swagger'
+import fastifySwaggerUi from '@fastify/swagger-ui'
+
+/** swagger-ui 마운트 경로 디폴트 (04-data-models §2 정본). */
+export const DEFAULT_OPENAPI_PATH = '/docs'
+
+/**
+ * OpenAPI 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} OpenapiSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string|null} path - swagger-ui 경로(미등록 시 null).
+ */
+
+/**
+ * `openapi` config 를 정규화한다. `enabled !== true` 면 `null`(미옵트인).
+ *
+ * @param {unknown} openapi - `MegaOpenApiAppConfig`.
+ * @param {string} [appName] - info.title 디폴트용.
+ * @returns {{ path: string, info: { title: string, version: string, description?: string }, auth: Function[], theme: Object } | null}
+ */
+export function normalizeOpenapi(openapi, appName = 'Mega') {
+  if (!openapi || typeof openapi !== 'object') return null
+  const c = /** @type {Record<string, any>} */ (openapi)
+  if (c.enabled !== true) return null // 옵트인 — 명시적으로 켜야 등록.
+
+  const path = typeof c.path === 'string' && c.path.length > 0 ? c.path : DEFAULT_OPENAPI_PATH
+  // info — 정본 { title, version, description? }. 누락 필드는 안전 디폴트로 채운다(명세 생성 자체는 실패 안 하게).
+  const userInfo = c.info && typeof c.info === 'object' ? c.info : {}
+  const info = {
+    title: typeof userInfo.title === 'string' && userInfo.title.length > 0 ? userInfo.title : `${appName} API`,
+    version: typeof userInfo.version === 'string' && userInfo.version.length > 0 ? userInfo.version : '0.0.0',
+    ...(typeof userInfo.description === 'string' ? { description: userInfo.description } : {}),
+  }
+  const auth = Array.isArray(c.auth) ? c.auth.filter((/** @type {unknown} */ f) => typeof f === 'function') : []
+  const theme = c.theme && typeof c.theme === 'object' ? c.theme : {}
+  return { path, info, auth, theme }
+}
+
+/**
+ * Fastify 인스턴스에 OpenAPI 명세 수집기 + swagger-ui 를 옵트인 등록한다.
+ *
+ * `openapi.enabled !== true` 면 **미등록**. `@fastify/swagger` 는 **라우트 등록보다 먼저** 등록돼야 onRoute 로
+ * 스키마를 수집하므로 `MegaApp` 생성자(3g, 보안·정적 자산 뒤·`/health` 앞)에서 호출한다. 멀티앱은 각자 Fastify
+ * 인스턴스라 docs 경로 충돌 없음(같은 앱 안에서 `path` 가 사용자 라우트와 겹치면 Fastify 가 중복 라우트로 부팅 throw).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.openapi - `MegaOpenApiAppConfig`. `enabled:true` 일 때만 등록.
+ * @param {string} [opts.appName] - 앱 이름(info.title 디폴트·로그).
+ * @param {(req: any, reply: any) => any} [opts.buildCtx] - docs auth 미들웨어에 넘길 ctx 팩토리(요청당). 미지정 시 auth 는 `(req, reply)` 로만 호출.
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {OpenapiSummary}
+ */
+export function registerOpenapi(fastify, { openapi, appName = '(unknown)', buildCtx, logger } = /** @type {any} */ ({})) {
+  const cfg = normalizeOpenapi(openapi, appName)
+  if (cfg === null) return { enabled: false, path: null }
+
+  // 1) 명세 수집기 — OpenAPI 3.x 모드(`openapi` 키). 라우트 schema(summary/tags/description/deprecated + body/response)를 수집.
+  fastify.register(fastifySwagger, /** @type {any} */ ({
+    openapi: { info: cfg.info },
+  }))
+
+  // 2) docs auth 가드 — auth 미들웨어 배열을 swagger-ui preHandler 로. 핸들러와 동일 (req, reply, ctx) 시그니처
+  //    (ADR-074). buildCtx 가 있으면 요청당 ctx 를 만들어 넘긴다(globalMiddleware 패턴 정합). 빈 배열=공개.
+  const uiHooks =
+    cfg.auth.length > 0
+      ? {
+          preHandler: cfg.auth.map((/** @type {Function} */ mw) => async (/** @type {any} */ req, /** @type {any} */ reply) => {
+            const ctx = buildCtx ? buildCtx(req, reply) : undefined
+            return /** @type {any} */ (mw)(req, reply, ctx)
+          }),
+        }
+      : undefined
+
+  // 3) swagger-ui 뷰어 — routePrefix=path. theme 는 uiConfig 로 그대로 전달.
+  fastify.register(fastifySwaggerUi, /** @type {any} */ ({
+    routePrefix: cfg.path,
+    ...(Object.keys(cfg.theme).length > 0 ? { uiConfig: cfg.theme } : {}),
+    ...(uiHooks ? { uiHooks } : {}),
+  }))
+
+  logger?.debug?.({ app: appName, path: cfg.path, auth: cfg.auth.length, title: cfg.info.title }, 'openapi.registered')
+  return { enabled: true, path: cfg.path }
+}