mega-framework 0.1.0

package/src/core/session.js

@@ -0,0 +1,414 @@
+// @ts-check
+/**
+ * 세션 미들웨어 자동 등록 — 쿠키 ↔ sid ↔ 세션 레코드 배선 (ADR-129/046).
+ *
+ * 보안 플러그인(`registerSecurityPlugins`)과 같은 패턴으로, 앱 생성 시점에 세션 미들웨어를
+ * Fastify 인스턴스에 등록한다. 스토어는 `MegaSessionAdapter`(file/redis, `createSessionStore`)이고,
+ * 본 모듈은 그 위에 **쿠키 서명 + sid 발급 + 요청별 세션 객체(`req.session`/`ctx.session`)** 를 얹는다.
+ *
+ * # 정책 (ADR-046 정본)
+ *   - **sid = ULID** (시간순 정렬 + 추측 어려움). `crypto.randomBytes` 기반 zero-dep 생성.
+ *   - **쿠키 HMAC sign 기본 ON** — `value = sid.base64url(hmac_sha256(secret, sid))`. 변조 시 무효 처리.
+ *     서명 비교는 `crypto.timingSafeEqual`(타이밍 공격 회피).
+ *   - **rolling TTL** — 로드된(기존) 세션은 매 요청 응답 시 `store.touch(sid, ttlMs)` 로 만료 연장.
+ *   - cleanup 은 스토어 책임(file=스캔, redis=TTL 자동, ADR-046).
+ *
+ * # 세션 객체 계약 (03-api-spec §7/§9)
+ *   `req.session`/`ctx.session` 은 데이터 필드를 직접 읽고 쓰는 객체다. **변경된 세션은 응답 시
+ *   자동 영속화**된다(express-session 관례 — 로드 시점 스냅샷과 응답 시점을 비교해 변경분만 저장).
+ *   명시 `await ctx.session.save()` 도 지원(즉시 영속 + await 가능). 로그아웃은
+ *   `await ctx.session.destroy()`. 예약 메서드/게터: `id`·`isNew`·`save`·`destroy`·`regenerate`·`secret`
+ *   (이 이름은 세션 데이터 키로 쓰지 말 것). `secret` 은 CSRF 세션 모드용 세션 바인딩 시크릿
+ *   (ADR-051)이며, `@fastify/csrf-protection`(sessionPlugin 모드)이 쓰는 `_csrf` 데이터 키와 동일하다.
+ *
+ * # 신규 visitor lazy 생성
+ *   쿠키 없는 첫 방문은 새 sid 로 세션 객체만 만들고 **`save()` 호출 전까지 영속화·쿠키 발급을 하지
+ *   않는다** — 봇/헬스체크가 빈 세션을 양산하지 않게.
+ *
+ * # 트레이싱 (ADR-126 인프라 재사용)
+ *   응답 커밋 시 활성 HTTP span 에 `mega.session.event`(save/touch/destroy/none)·`mega.session.driver`·
+ *   `mega.session.id`(sid 해시 — 원본 sid 비노출) attribute. 옵트인 OFF 면 0 비용 no-op.
+ *
+ * @module core/session
+ */
+import { createHmac, timingSafeEqual, randomBytes, createHash } from 'node:crypto'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import { recordSession } from './../lib/mega-metrics.js'
+
+/** Crockford base32 알파벳 (ULID 표준). 혼동 문자(I,L,O,U) 제외. */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+/** 쿠키 기본값 (httpOnly ON / secure auto / sameSite lax / 24h). */
+const DEFAULT_COOKIE = Object.freeze({ name: 'mega.sid', path: '/', httpOnly: true, secure: 'auto', sameSite: 'lax' })
+
+/** 세션 데이터로 쓰면 안 되는 예약 키(메서드/게터와 충돌). */
+const RESERVED_KEYS = Object.freeze(['id', 'isNew', 'save', 'destroy', 'regenerate', 'secret'])
+
+/** CSRF 세션 시크릿을 보관하는 데이터 키(세션 모드, ADR-051). `@fastify/csrf-protection` 의 sessionKey 기본값과 동일. */
+const CSRF_SECRET_KEY = '_csrf'
+
+/**
+ * ULID sid 생성 — 48-bit timestamp + 80-bit randomness = 26자 Crockford base32 (ADR-046).
+ * (ws-message 의 generateMessageId 는 "envelope 전용"이라 세션용 독립 helper 를 둔다. 정식 MegaIdGen 은 OQ-014.)
+ *
+ * @param {number} [timestamp] - epoch ms(테스트 주입용).
+ * @returns {string} 26자 ULID.
+ */
+export function generateSid(timestamp = Date.now()) {
+  let time = timestamp
+  let timeChars = ''
+  for (let i = 0; i < 10; i++) {
+    timeChars = CROCKFORD[time % 32] + timeChars
+    time = Math.floor(time / 32)
+  }
+  const rand = randomBytes(16)
+  let randChars = ''
+  for (let i = 0; i < 16; i++) randChars += CROCKFORD[rand[i] % 32]
+  return timeChars + randChars
+}
+
+/**
+ * sid 를 HMAC 서명한 쿠키 값으로 만든다 — `sid.base64url(hmac)`.
+ * @param {string} sid @param {string} secret @returns {string}
+ */
+function signSid(sid, secret) {
+  const mac = createHmac('sha256', secret).update(sid).digest('base64url')
+  return `${sid}.${mac}`
+}
+
+/**
+ * 서명된 쿠키 값을 검증해 sid 를 복원한다. 변조/형식오류면 `null`(timingSafeEqual 로 비교).
+ * @param {string} signed @param {string} secret @returns {string | null}
+ */
+function unsignSid(signed, secret) {
+  const dot = signed.lastIndexOf('.')
+  if (dot <= 0) return null
+  const sid = signed.slice(0, dot)
+  const mac = signed.slice(dot + 1)
+  const expected = createHmac('sha256', secret).update(sid).digest('base64url')
+  const a = Buffer.from(mac)
+  const b = Buffer.from(expected)
+  // 길이 다르면 timingSafeEqual 이 throw 하므로 먼저 길이 비교(불일치 = 위조).
+  if (a.length !== b.length) return null
+  return timingSafeEqual(a, b) ? sid : null
+}
+
+/**
+ * 요청 Cookie 헤더에서 특정 이름의 쿠키 값을 꺼낸다(@fastify/cookie 의존 회피 — 우리 쿠키 1종만 파싱).
+ * @param {string | undefined} header - `req.headers.cookie`.
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function readCookie(header, name) {
+  if (!header) return undefined
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return undefined
+}
+
+/**
+ * Set-Cookie 헤더 문자열을 만든다.
+ * @param {string} name @param {string} value
+ * @param {{ path?: string, httpOnly?: boolean, secure?: boolean, sameSite?: string, maxAgeSec?: number }} opts
+ * @returns {string}
+ */
+function serializeCookie(name, value, opts) {
+  let str = `${name}=${encodeURIComponent(value)}`
+  if (opts.path) str += `; Path=${opts.path}`
+  if (typeof opts.maxAgeSec === 'number') str += `; Max-Age=${opts.maxAgeSec}`
+  if (opts.httpOnly) str += '; HttpOnly'
+  if (opts.secure) str += '; Secure'
+  if (opts.sameSite) str += `; SameSite=${opts.sameSite[0].toUpperCase()}${opts.sameSite.slice(1)}`
+  return str
+}
+
+/** sid 를 로그/span 에 노출할 때 쓰는 해시(원본 비노출). @param {string} sid @returns {string} */
+function hashSid(sid) {
+  return createHash('sha256').update(sid).digest('hex').slice(0, 16)
+}
+
+/** 미들웨어 내부 상태를 세션 객체에 숨겨 붙이는 심볼 키(데이터와 분리). */
+const STATE = Symbol('mega.session.state')
+
+/**
+ * 요청별 세션 객체를 만든다. 데이터 필드는 객체에 직접(enumerable), 메서드/게터는 non-enumerable
+ * (`JSON.stringify` 가 데이터만 직렬화하도록).
+ *
+ * @param {object} args
+ * @param {string} args.sid
+ * @param {object} args.data - 로드된 데이터(신규면 `{}`).
+ * @param {boolean} args.isNew - 스토어에서 로드 안 됐으면 true.
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} args.store
+ * @param {number} args.ttlMs
+ * @param {{ debug?: Function, warn?: Function }} [args.logger] - regenerate 의 best-effort 정리 실패 로깅용(onSend touch 와 동일 패턴).
+ * @returns {Record<string, any>}
+ */
+function makeSession({ sid, data, isNew, store, ttlMs, logger }) {
+  /** @type {Record<string, any>} */
+  const session = {}
+  // 데이터 필드를 객체에 직접 복사(예약 키는 건너뜀 — 메서드와 충돌 방지).
+  for (const [k, v] of Object.entries(data ?? {})) {
+    if (!RESERVED_KEYS.includes(k)) session[k] = v
+  }
+
+  const state = {
+    sid,
+    isNew,
+    store,
+    ttlMs,
+    /** @type {'set'|'clear'|null} 응답 시 쿠키 동작(null=무동작). */
+    cookieAction: /** @type {'set'|'clear'|null} */ (null),
+    /** save()/regenerate() 가 명시 호출돼 이미 영속화됐는지. */
+    saved: false,
+    /** destroy() 됐는지. */
+    destroyed: false,
+    /** 로드된(기존) 세션인지 — rolling touch 대상. */
+    loaded: !isNew,
+    /** 로드 시점 데이터 스냅샷(JSON) — 응답 시 변경 감지 자동 저장 기준. */
+    snapshot: '',
+  }
+
+  Object.defineProperties(session, {
+    [STATE]: { value: state, enumerable: false },
+    id: { get: () => state.sid, enumerable: false, configurable: true },
+    isNew: { get: () => state.isNew, enumerable: false, configurable: true },
+
+    /**
+     * 세션 바인딩 시크릿(ADR-051) — 데이터 키 `_csrf` 의 게터/lazy 생성기. 없으면 `randomBytes(18)` 로
+     * 생성하고 `_csrf` 에 저장(다음 응답에서 변경 감지 자동 저장).
+     *
+     * ⚠️ CSRF 세션 모드의 실제 동작은 이 게터를 거치지 않는다 — `@fastify/csrf-protection`(sessionPlugin
+     * 모드)은 `req.session._csrf` 를 **직접** 읽고 쓴다(sessionKey 기본값 = `_csrf`). 따라서 이 게터는
+     * **사용자 코드 전용**(예: 직접 토큰 생성 등 `_csrf` 를 편하게 다룰 때)이며 향후 활용 위해 보존한다.
+     */
+    secret: {
+      get() {
+        let s = /** @type {any} */ (session)[CSRF_SECRET_KEY]
+        if (typeof s !== 'string') {
+          s = randomBytes(18).toString('base64url')
+          ;/** @type {any} */ (session)[CSRF_SECRET_KEY] = s
+        }
+        return s
+      },
+      enumerable: false,
+      configurable: true,
+    },
+
+    /** 데이터 변경을 스토어에 영속화. 신규 세션이면 응답에서 쿠키 발급. */
+    save: {
+      value: async () => {
+        if (state.destroyed) throw new Error('MegaSession: cannot save() a destroyed session.')
+        await state.store.save(state.sid, serializeData(session))
+        state.saved = true
+        state.loaded = true
+        state.cookieAction = 'set'
+      },
+      enumerable: false,
+      configurable: true,
+    },
+
+    /** 세션 폐기(로그아웃). 스토어에서 삭제하고 응답에서 쿠키 제거. */
+    destroy: {
+      value: async () => {
+        await state.store.destroy(state.sid)
+        state.destroyed = true
+        state.cookieAction = 'clear'
+      },
+      enumerable: false,
+      configurable: true,
+    },
+
+    /**
+     * 세션 고정(fixation) 방지 — 기존 sid 를 폐기하고 새 sid 로 재발급한다(로그인 직후 권장).
+     * 데이터는 유지된다.
+     */
+    regenerate: {
+      value: async () => {
+        if (state.destroyed) throw new Error('MegaSession: cannot regenerate() a destroyed session.')
+        const oldSid = state.sid
+        const newSid = generateSid()
+        state.sid = newSid
+        await state.store.save(newSid, serializeData(session))
+        // 기존 sid 정리는 best-effort — 새 sid 저장은 이미 성공했고 옛 키는 TTL 만료/cleanup 이 회수한다.
+        // 실패해도 새 세션은 유효하므로 응답을 막지 않되, silent 묵살은 금지(P4) — warn 으로 가시화한다
+        // (onSend 의 rolling touch 실패와 동일 패턴).
+        try {
+          await state.store.destroy(oldSid)
+        } catch (err) {
+          logger?.warn?.({ sid: hashSid(oldSid), err }, 'session.regenerate: old sid destroy failed (non-fatal, TTL/cleanup will reclaim)')
+        }
+        state.saved = true
+        state.loaded = true
+        state.cookieAction = 'set'
+      },
+      enumerable: false,
+      configurable: true,
+    },
+  })
+
+  // 로드 시점 데이터 스냅샷 — 응답 시 이 값과 다르면 자동 저장(변경 감지).
+  state.snapshot = JSON.stringify(serializeData(session))
+  return session
+}
+
+/**
+ * 세션 객체의 데이터 부분만 추출(enumerable own 키 — 메서드/게터 제외).
+ * @param {Record<string, any>} session @returns {object}
+ */
+function serializeData(session) {
+  /** @type {Record<string, any>} */
+  const out = {}
+  for (const k of Object.keys(session)) out[k] = session[k]
+  return out
+}
+
+/**
+ * Fastify 인스턴스에 세션 미들웨어를 등록한다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} opts
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} opts.store - 연결된 세션 스토어.
+ * @param {string} opts.secret - 쿠키 HMAC 서명 시크릿(global `server.sessionSecret`).
+ * @param {number} [opts.ttlMs] - 세션 TTL(ms). 기본 24시간.
+ * @param {boolean} [opts.rolling] - rolling TTL(기본 true, ADR-046).
+ * @param {{ name?: string, path?: string, httpOnly?: boolean, secure?: boolean|'auto', sameSite?: string }} [opts.cookie]
+ * @param {string} [opts.driver] - 스토어 driver 명(트레이싱용; 미지정 시 store.getStats().driver).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger]
+ * @returns {void}
+ * @throws {Error} secret 누락 — 서명 불가(부팅 abort).
+ */
+export function registerSession(fastify, opts) {
+  const { store, secret, logger } = opts
+  if (typeof secret !== 'string' || secret.length === 0) {
+    // 시크릿 없는 세션은 변조 방지 불가 — fail-fast(silent 진행 금지).
+    throw new Error('registerSession: opts.secret is required (set global server.sessionSecret) — cookie signing is mandatory (ADR-046).')
+  }
+  const ttlMs = opts.ttlMs ?? 86_400_000
+  const rolling = opts.rolling !== false
+  const cookieCfg = { ...DEFAULT_COOKIE, ...(opts.cookie ?? {}) }
+  const driver = opts.driver ?? /** @type {any} */ (store.getStats?.())?.driver ?? 'unknown'
+
+  // 요청 진입 — 쿠키 검증 → sid → 세션 로드 → req.session 부착(길목 로그).
+  fastify.addHook('onRequest', async (req) => {
+    const signed = readCookie(req.headers.cookie, cookieCfg.name)
+    let sid = signed ? unsignSid(signed, secret) : null
+    /** @type {object} */
+    let data = {}
+    let isNew = true
+    if (sid) {
+      const loaded = await store.load(sid)
+      if (loaded !== null && typeof loaded === 'object') {
+        data = loaded
+        isNew = false
+      } else {
+        // 쿠키 sid 는 유효 서명이나 스토어에 없음(만료/삭제) → 새 sid 로 신규 취급.
+        sid = null
+      }
+    }
+    if (!sid) sid = generateSid()
+    const session = makeSession({ sid, data, isNew, store, ttlMs, logger })
+    ;/** @type {any} */ (req).session = session
+    logger?.debug?.({ route: req.routeOptions?.url, sid: hashSid(sid), isNew }, 'session.load')
+  })
+
+  // 응답 직전 — 쿠키 발급/제거 + rolling touch + 트레이싱(onSend: 헤더 수정 가능 시점).
+  fastify.addHook('onSend', async (req, reply, payload) => {
+    const session = /** @type {any} */ (req).session
+    if (!session) return payload
+    const state = session[STATE]
+    const secureFlag = cookieCfg.secure === 'auto' ? req.protocol === 'https' : cookieCfg.secure === true
+
+    /** 쿠키 발급 헬퍼(set/clear). @param {string} value @param {number} maxAgeSec */
+    const emitCookie = (value, maxAgeSec) =>
+      reply.header('set-cookie', serializeCookie(cookieCfg.name, value, { path: cookieCfg.path, httpOnly: cookieCfg.httpOnly, secure: secureFlag, sameSite: cookieCfg.sameSite, maxAgeSec }))
+    const maxAgeSec = Math.floor(ttlMs / 1000)
+
+    /** @type {'save'|'touch'|'destroy'|'none'} */
+    let event = 'none'
+    if (state.destroyed) {
+      event = 'destroy'
+      emitCookie('', 0)
+    } else if (state.cookieAction === 'set') {
+      // save()/regenerate() 명시 호출 — 이미 store 에 영속됨. 쿠키만 발급(maxAge=ttl).
+      event = 'save'
+      emitCookie(signSid(state.sid, secret), maxAgeSec)
+    } else if (JSON.stringify(serializeData(session)) !== state.snapshot) {
+      // 변경 감지 자동 저장(express-session 관례) — 데이터가 로드 시점과 다르면 영속화.
+      // CSRF 세션 모드(_csrf 시크릿 생성)·핸들러 mutation 둘 다 여기서 잡힌다.
+      await store.save(state.sid, serializeData(session))
+      event = 'save'
+      emitCookie(signSid(state.sid, secret), maxAgeSec)
+    } else if (rolling && state.loaded) {
+      // 로드된 기존 세션 — 변경 없어도 rolling TTL 연장 + 쿠키 maxAge 갱신.
+      // touch 실패는 비치명적(다음 요청 재시도) — 응답을 막지 않는다.
+      try {
+        await store.touch(state.sid, ttlMs)
+        event = 'touch'
+        emitCookie(signSid(state.sid, secret), maxAgeSec)
+      } catch (err) {
+        logger?.warn?.({ sid: hashSid(state.sid), err }, 'session.touch failed (continuing)')
+      }
+    }
+
+    if (event !== 'none') {
+      // 활성 HTTP span 에 세션 이벤트 기록(ADR-126). 옵트인 OFF 면 activeSpan undefined → no-op.
+      MegaTracing.tracer.activeSpan()?.setAttributes({
+        'mega.session.event': event,
+        'mega.session.driver': driver,
+        'mega.session.id': hashSid(state.sid),
+      })
+      logger?.debug?.({ route: req.routeOptions?.url, event, sid: hashSid(state.sid) }, 'session.commit')
+      // 메트릭 집계(ADR-131) — 새 세션 영속=created, 파기=destroyed 만 카운트(touch/기존-save 제외).
+      // sid 는 PII 라 라벨 미노출. 옵트인 OFF 면 0 비용.
+      if (event === 'destroy') recordSession({ driver, event: 'destroyed' })
+      else if (event === 'save' && state.isNew) recordSession({ driver, event: 'created' })
+    }
+    return payload
+  })
+}
+
+/**
+ * Fastify 요청 파이프라인 밖(raw `IncomingMessage`)에서 세션을 **읽기 전용**으로 복원한다.
+ *
+ * HTTP `'upgrade'` 핸드셰이크는 Fastify 의 onRequest 훅을 타지 않아 `req.session` 이 없다. 그래서
+ * WS 라우트의 `before(req)` 인증은 이 helper 로 세션 신원을 확인한다 — {@link registerSession} 의
+ * onRequest 가 하는 경로(쿠키 → unsign → `store.load`)를 그대로 재사용하되, rolling touch·쿠키 발급·
+ * 변경 저장은 하지 않는다(upgrade 응답엔 set-cookie 를 실을 수 없고, 읽기만 필요하므로).
+ *
+ * 보안상 동일 규칙을 따른다: 쿠키가 없거나 서명 위조면 `null`(익명), 스토어에 없으면(만료/삭제) `null`.
+ * 절대 silent 하게 통과시키지 않는다(fail-closed) — 신원이 없으면 `before` 가 401 로 거부한다.
+ *
+ * @param {{ headers?: Record<string, any> }} req - raw `IncomingMessage`(또는 `headers.cookie` 를 가진 객체).
+ * @param {object} opts
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} opts.store - 연결된 세션 스토어(`app.sessionStore`).
+ * @param {string} opts.secret - 쿠키 HMAC 서명 시크릿(global `server.sessionSecret`).
+ * @param {string} [opts.cookieName] - 세션 쿠키 이름(기본 `'mega.sid'` — {@link registerSession} 디폴트와 일치).
+ * @returns {Promise<{ sid: string, data: Record<string, any> } | null>} 유효 세션이면 `{ sid, data }`, 아니면 `null`.
+ * @throws {Error} `secret`/`store` 누락 — 서명 검증·로드가 불가하므로 fail-fast(silent 진행 금지).
+ * @example
+ *   // WS before 인증 — 로그인한 세션만 upgrade 허용
+ *   async function wsRequireAuth(req) {
+ *     const sess = await readSession(req, { store: app.sessionStore, secret })
+ *     if (sess?.data.userId == null) return false // 401
+ *     return { userId: String(sess.data.userId), sessionId: sess.sid } // ctx.auth
+ *   }
+ */
+export async function readSession(req, { store, secret, cookieName } = /** @type {any} */ ({})) {
+  if (typeof secret !== 'string' || secret.length === 0) {
+    throw new Error('readSession: opts.secret is required (cookie signature cannot be verified).')
+  }
+  if (!store || typeof store.load !== 'function') {
+    throw new Error('readSession: opts.store with load(sid) is required.')
+  }
+  const name = typeof cookieName === 'string' && cookieName.length > 0 ? cookieName : DEFAULT_COOKIE.name
+  const signed = readCookie(req?.headers?.cookie, name)
+  if (!signed) return null // 쿠키 없음 = 비로그인.
+  const sid = unsignSid(signed, secret)
+  if (!sid) return null // 서명 위조/형식오류 = 익명 취급(fail-closed).
+  const loaded = await store.load(sid)
+  if (loaded === null || typeof loaded !== 'object') return null // 만료/삭제된 세션.
+  return { sid, data: /** @type {Record<string, any>} */ (loaded) }
+}

package/src/core/static-assets.js

@@ -0,0 +1,126 @@
+// @ts-check
+/**
+ * MegaApp 정적 자산 자동 등록 — `@fastify/static` 옵트인 통합.
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   웹페이지에 쓰는 이미지·CSS·JS 같은 "그냥 파일"을 노드가 직접 내려주게 하는 기능이다.
+ *   `apps/<name>/app.config.js` 의 `staticAssets` 를 켰을 때만(`enabled:true`) 등록한다(디폴트 OFF).
+ *   프로덕션에서는 보통 nginx/CDN 이 정적 트래픽을 받으므로, 코어가 멋대로 켜지 않고 옵트인으로 둔다.
+ *
+ * # 동작 한눈에 (multipart.js / template.js 형제 패턴)
+ *   1. `registerStaticAssets(fastify, { staticAssets })` — `enabled:true` + `dir`(실존 디렉터리)일 때만 옵트인 등록.
+ *   2. 검증된 공개 플러그인 `@fastify/static` 을 `{ root, prefix, cacheControl/setHeaders, dotfiles }` 로 등록 →
+ *      `${prefix}/<파일>`(prefix 디폴트 `/static`)로 디스크 파일을 스트리밍 서빙.
+ *   3. `enabled:true` 인데 `dir` 누락/미존재 — 프로덕션 **부팅 throw**(fail-fast), dev **warn + skip**(ADR-071).
+ *
+ * # 보안 (ADR-071 / 12-performance-security / 04-data-models §2)
+ *   - **path traversal**: `@fastify/static@9.1.3+` 가 인코딩된 경로 구분자·디렉터리 listing 우회를 내부 차단
+ *     (GHSA-pr96-94w5-mx2h / GHSA-x428-ghpx-8j92 해소 버전). dir 루트 밖 접근 불가.
+ *   - **dotfiles 차단(디폴트)**: `.git`·`.env` 같은 점파일은 디폴트로 404 차단(`dotfiles:'ignore'`, 존재까지 은닉).
+ *     `dotfiles:true` 옵트인 시만 서빙. ('deny'(403)는 @fastify/send throw → 인코딩 경로 hang 유발이라 미채택, ADR-139.)
+ *   - **디폴트 OFF**: 옵트인이 아니면 정적 라우트가 아예 없어 의도치 않은 노출이 없다.
+ *   - **App-only 스코프**: 앱마다 자기 `dir`·`prefix` 라 멀티앱이 같은 prefix 로 충돌하지 않는다(다른 Fastify 인스턴스).
+ *   - **메트릭 경로 충돌**: `prefix` 가 `health.metricsPath` 와 정확히 같으면 부팅 throw(config-validator, ADR-072).
+ *
+ * @module core/static-assets
+ * @see ADR-071
+ * @see ADR-139
+ * @see https://github.com/fastify/fastify-static (@fastify/static v9)
+ */
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import fastifyStatic from '@fastify/static'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** 정적 자산 prefix 디폴트 (04-data-models §2 정본). */
+export const DEFAULT_STATIC_PREFIX = '/static'
+
+/**
+ * 정적 자산 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} StaticAssetsSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string|null} root - 서빙 루트 절대경로(미등록 시 null).
+ * @property {string} prefix - URL prefix.
+ */
+
+/**
+ * `staticAssets` config 를 **순수 정규화**한다(파일시스템 접근 없음 — dir 실존 검사는 register 가 담당).
+ *
+ * - falsy / `enabled !== true` → `null`(미옵트인).
+ * - 그 외 → `{ dir, prefix, cacheControlHeader, dotfiles }`(prefix 디폴트 `/static`).
+ *
+ * `cacheControl`(정본: 문자열 = `Cache-Control` 헤더값, 예 `'public, max-age=3600'`)은 `cacheControlHeader`
+ * 로 전달. `dotfiles`(디폴트 false=차단)는 `'allow'`/`'deny'` 로 변환.
+ *
+ * @param {unknown} staticAssets - `MegaStaticAssetsAppConfig`.
+ * @returns {{ dir: string, prefix: string, cacheControlHeader: string|null, dotfiles: 'allow'|'ignore' } | null}
+ */
+export function normalizeStaticAssets(staticAssets) {
+  if (!staticAssets || typeof staticAssets !== 'object') return null
+  const c = /** @type {Record<string, any>} */ (staticAssets)
+  if (c.enabled !== true) return null // 옵트인 — 명시적으로 켜야 등록.
+
+  const dir = typeof c.dir === 'string' ? c.dir : ''
+  const prefix = typeof c.prefix === 'string' && c.prefix.length > 0 ? c.prefix : DEFAULT_STATIC_PREFIX
+  const cacheControlHeader = typeof c.cacheControl === 'string' && c.cacheControl.length > 0 ? c.cacheControl : null
+  // 디폴트 false = 점파일 차단(.git/.env 노출 방지). 'ignore'(404, 존재까지 은닉)를 쓴다 — 'deny'(403)는
+  // @fastify/send 가 **에러를 throw** 해 인코딩 경로 구분자 요청에서 응답 미완결(hang/DoS, ADR-139 검증) 유발.
+  // 'ignore' 는 404 로 조용히 차단(throw 없음). true 옵트인 시만 'allow'(서빙).
+  const dotfiles = c.dotfiles === true ? 'allow' : 'ignore'
+  return { dir, prefix, cacheControlHeader, dotfiles }
+}
+
+/**
+ * Fastify 인스턴스에 `@fastify/static` 을 옵트인 등록한다.
+ *
+ * `staticAssets.enabled !== true` 면 **미등록**(정적 라우트 없음). 보안 플러그인·템플릿 등록 이후·`/health`
+ * 등록 이전에 호출한다(라우트 등록이므로 보안 onRoute hook 뒤여야 면제/제한이 일관). 멀티앱은 각자 Fastify
+ * 인스턴스라 prefix 충돌 없음.
+ *
+ * `enabled:true` 인데 `dir` 누락/미존재면 — 프로덕션 부팅 throw(`config.static_dir_not_found`), dev warn+skip
+ * (ADR-071, 04-data-models §3 검증표). `@fastify/static` 자체도 root 미존재 시 throw 하지만, dev 에선 warn 후
+ * 건너뛰어 잘못된 dir 하나로 앱 전체가 죽지 않게 한다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.staticAssets - `MegaStaticAssetsAppConfig`. `enabled:true` + 실존 `dir` 일 때만 등록.
+ * @param {string} [opts.appName] - 앱 이름(로그용).
+ * @param {boolean} [opts.isProduction] - 프로덕션 여부. 미지정 시 `NODE_ENV==='production'`.
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug/warn 로그(선택).
+ * @returns {StaticAssetsSummary}
+ * @throws {MegaConfigError} 프로덕션에서 `enabled:true` + `dir` 누락/미존재.
+ */
+export function registerStaticAssets(
+  fastify,
+  { staticAssets, appName = '(unknown)', isProduction = process.env.NODE_ENV === 'production', logger } = /** @type {any} */ ({}),
+) {
+  const cfg = normalizeStaticAssets(staticAssets)
+  if (cfg === null) return { enabled: false, root: null, prefix: DEFAULT_STATIC_PREFIX }
+
+  const root = cfg.dir.length > 0 ? resolve(cfg.dir) : ''
+  if (root.length === 0 || !existsSync(root)) {
+    // ADR-071 — 켰는데 디렉터리가 없다: 운영은 잘못된 배포라 즉시 멈추고, dev 는 경고만 하고 건너뛴다.
+    if (isProduction) {
+      throw new MegaConfigError(
+        'config.static_dir_not_found',
+        `App '${appName}' staticAssets.dir='${cfg.dir}' not found (enabled but directory missing).`,
+        { details: { app: appName, dir: cfg.dir, scope: 'staticAssets.dir' } },
+      )
+    }
+    logger?.warn?.({ app: appName, dir: cfg.dir }, 'static.skipped (enabled but dir missing — dev)')
+    return { enabled: false, root: null, prefix: cfg.prefix }
+  }
+
+  fastify.register(fastifyStatic, /** @type {any} */ ({
+    root,
+    prefix: cfg.prefix,
+    dotfiles: cfg.dotfiles,
+    // 정본 cacheControl 은 raw 헤더 문자열 — @fastify/static 자체 cacheControl 은 끄고 setHeaders 로 직접 박는다.
+    ...(cfg.cacheControlHeader
+      ? { cacheControl: false, setHeaders: (/** @type {any} */ res) => res.setHeader('cache-control', cfg.cacheControlHeader) }
+      : {}),
+  }))
+
+  logger?.debug?.({ app: appName, root, prefix: cfg.prefix, dotfiles: cfg.dotfiles }, 'static.registered')
+  return { enabled: true, root, prefix: cfg.prefix }
+}