mega-framework 0.1.0

package/src/lib/asp/plugin.js

@@ -0,0 +1,263 @@
+// @ts-check
+/**
+ * MegaAspPlugin — ASP HTTP terminator (서버측, Fastify hook 3종).
+ *
+ * ADR-053/054/057/058/076/090/092. 라우트·경로 옵트인(`enabledPaths` glob)으로만 활성.
+ * 요청은 `X-Mega-Encrypted: true` 시그널 + `X-Timestamp` 로 식별 (WASM 클라이언트
+ * `transport_http.rs` 와 byte 호환).
+ *
+ * # 훅 (ADR-076 stage 분리)
+ *   - onRequest:     ASP 스코프 판별 + ts/drift 검증 + per-request 키 유도 (signal_required fail-closed)
+ *   - preParsing:    body ciphertext 복호화 → 평문 stream 반환 (JSON 파서가 평문을 보게)
+ *   - preValidation: query `?q=` (URL-safe base64, ADR-092) 복호화 → req.query 치환
+ *   - onSend:        응답 envelope JSON 암호화 + 시그널/timestamp 헤더 (자동 envelope 이후)
+ *
+ * # fail-closed (ADR-057)
+ *   복호화·drift·replay·signal 실패는 {@link MegaAspDecryptError}(403) 로 throw —
+ *   평문 통과 절대 없음. 에러 응답은 ok 마커 미설정이라 onSend 가 암호화하지 않음(평문).
+ *
+ * @module lib/asp/plugin
+ */
+import { Readable } from 'node:stream'
+import {
+  deriveKey,
+  getUaSlice,
+  encryptTransport,
+  decryptTransport,
+  extractNonce,
+} from './crypto.js'
+import { normalizeAspConfig } from './config.js'
+import { MegaAspDecryptError, ASP_RULES } from './errors.js'
+
+/** per-request ASP 상태 보관용 symbol (키/ts/마커). */
+const ASP_STATE = Symbol('mega.asp.state')
+
+/**
+ * per-request ASP 상태. `req[ASP_STATE]` 에 보관 (Fastify 타입에 없는 symbol 키).
+ * `multipart` 는 body 평문 통과 마커(02-architecture §1625).
+ * @typedef {{ intent: boolean, ok: boolean, ts: number, key: Buffer, multipart?: boolean }} AspState
+ */
+
+/**
+ * Fastify 인스턴스에 ASP HTTP terminator 등록.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Object} aspConfigRaw - { masterSecret, enabledPaths, headerSignal?, timestampHeader?, driftMs?, failOpen?, nonceCache? }
+ * @param {{ logger?: { warn: Function, debug?: Function } }} [opts]
+ * @returns {import('./config.js').NormalizedAspConfig} 정규화된 config (테스트·디버그용)
+ */
+export function registerAspPlugin(fastify, aspConfigRaw, opts = {}) {
+  const cfg = normalizeAspConfig(aspConfigRaw, opts)
+  const matchers = cfg.enabledPaths.map(globToRegex)
+  const signalKey = cfg.headerSignal.toLowerCase()
+  const tsKey = cfg.timestampHeader.toLowerCase()
+
+  /**
+   * ASP 활성 경로인가 (skipAsp 라우트 제외 + glob 매칭).
+   * @param {import('fastify').FastifyRequest} req
+   * @returns {boolean}
+   */
+  function isAspPath(req) {
+    // skipAsp 는 라우트 config 의 우리 전용 플래그 — Fastify config 타입에 없어 cast.
+    const routeCfg = /** @type {{ skipAsp?: boolean } | undefined} */ (req.routeOptions?.config)
+    if (routeCfg?.skipAsp) return false
+    const pathOnly = String(req.url).split('?')[0]
+    return matchers.some((re) => re.test(pathOnly))
+  }
+
+  // ── onRequest: 스코프 판별 + ts/drift + 키 유도 ──
+  fastify.addHook('onRequest', async (req) => {
+    if (!isAspPath(req)) return
+
+    const signaled = String(req.headers[signalKey] ?? '') === 'true'
+    if (!signaled) {
+      // ASP 활성 경로인데 암호화 시그널 없음 → fail-closed (ADR-057). 평문 거부.
+      throw new MegaAspDecryptError(
+        ASP_RULES.SIGNAL_REQUIRED,
+        `ASP-enabled path requires '${cfg.headerSignal}: true' (fail-closed, ADR-057).`,
+        { field: 'headers' },
+      )
+    }
+
+    const tsRaw = req.headers[tsKey]
+    const ts = Number(tsRaw)
+    if (tsRaw === undefined || !Number.isFinite(ts) || ts <= 0) {
+      throw new MegaAspDecryptError(
+        ASP_RULES.MISSING_TIMESTAMP,
+        `ASP request missing valid '${cfg.timestampHeader}' header.`,
+        { field: 'headers' },
+      )
+    }
+    if (Math.abs(Date.now() - ts) > cfg.driftMs) {
+      throw new MegaAspDecryptError(
+        ASP_RULES.DRIFT,
+        `ASP timestamp drift exceeds ${cfg.driftMs}ms.`,
+        { field: cfg.timestampHeader },
+      )
+    }
+
+    // 키 유도 — body/query/응답 모두 동일 키 (같은 domain/path/ua/ts). 클라와 byte 호환.
+    const domain = String(req.headers.host ?? '').split(':')[0]
+    const ua = String(req.headers['user-agent'] ?? '')
+    const pathOnly = String(req.url).split('?')[0]
+    const uaSlice = getUaSlice(ua, ts)
+    const key = deriveKey(cfg.masterSecret, domain, pathOnly, uaSlice, ts)
+
+    // ASP_STATE 는 Fastify 타입에 없는 우리 전용 symbol 키 — 부착 시 cast.
+    ;(/** @type {Record<symbol, AspState>} */ (/** @type {unknown} */ (req)))[ASP_STATE] = {
+      intent: true,
+      ok: false,
+      ts,
+      key,
+    }
+  })
+
+  // ── preParsing: body ciphertext → 평문 stream ──
+  fastify.addHook('preParsing', async (req, _reply, payload) => {
+    const state = /** @type {AspState | undefined} */ (
+      (/** @type {Record<symbol, AspState>} */ (/** @type {unknown} */ (req)))[ASP_STATE]
+    )
+    if (!state?.intent) return payload
+
+    // multipart body 평문 통과 (02-architecture §1625). 파일 업로드는 body 를 ciphertext 로 받지 않으므로
+    // 복호화를 건너뛰고 multipart 파서에 평문 그대로 넘긴다. **ASP 인증(onRequest 의 signal/ts/drift)·응답
+    // 암호화(onSend)는 그대로 유지**되므로 Content-Type 위조로 ASP 자체를 우회할 수는 없다 — 위조 multipart 도
+    // 유효 ts·signal 이 필요하고 응답은 여전히 암호화돼 키 없이는 못 읽는다.
+    const contentType = String(req.headers['content-type'] ?? '')
+    if (contentType.includes('multipart/form-data')) {
+      state.multipart = true // 디버그/테스트 마커. 응답 암호화는 preValidation 의 state.ok=true 가 활성화.
+      return payload
+    }
+
+    const raw = await readStream(payload)
+    if (raw.length === 0) {
+      // body 없음 (GET 등). query/응답 ASP 는 계속. 빈 stream 그대로 반환.
+      return makeStream(raw)
+    }
+
+    const encB64 = raw.toString('utf8')
+    const plain = decryptOrThrow(state.key, encB64, 'body')
+    await checkReplay(cfg, encB64, 'body')
+
+    return makeStream(Buffer.from(plain, 'utf8'))
+  })
+
+  // ── preValidation: query ?q= 복호화 + 최종 ok 마커 ──
+  fastify.addHook('preValidation', async (req) => {
+    const state = /** @type {AspState | undefined} */ (
+      (/** @type {Record<symbol, AspState>} */ (/** @type {unknown} */ (req)))[ASP_STATE]
+    )
+    if (!state?.intent) return
+
+    const q = (/** @type {Record<string, any> | undefined} */ (req.query))?.q
+    if (typeof q === 'string' && q.length > 0) {
+      // URL-safe base64 → STANDARD (ADR-092). `-`→`+`, `_`→`/`. 패딩은 decrypt 가 자동 보정.
+      const stdB64 = q.replace(/-/g, '+').replace(/_/g, '/')
+      const plainQuery = decryptOrThrow(state.key, stdB64, 'query')
+      await checkReplay(cfg, stdB64, 'query')
+      // 복호화된 원본 query string → req.query 치환 (q 제거).
+      req.query = Object.fromEntries(new URLSearchParams(plainQuery))
+    }
+
+    // 여기 도달 = body/query 복호화 모두 통과 → 응답 암호화 허용.
+    state.ok = true
+  })
+
+  // ── onSend: 응답 envelope JSON 암호화 (ADR-076) ──
+  fastify.addHook('onSend', async (req, reply, payload) => {
+    const state = /** @type {AspState | undefined} */ (
+      (/** @type {Record<symbol, AspState>} */ (/** @type {unknown} */ (req)))[ASP_STATE]
+    )
+    if (!state?.ok) return payload // ASP 미통과(에러 등) → 평문 (클라가 키 못 만드는 상황 대비).
+
+    const plain = Buffer.isBuffer(payload) ? payload : String(payload ?? '')
+    const enc = encryptTransport(state.key, plain)
+    reply.header(cfg.headerSignal, 'true')
+    reply.header(cfg.timestampHeader, String(state.ts)) // 요청 ts 재사용 (클라가 동일 키로 복호)
+    reply.header('content-type', 'text/plain; charset=utf-8') // body 는 base64 ciphertext
+    return enc
+  })
+
+  return cfg
+}
+
+/**
+ * 복호화 시도 → 실패 시 MegaAspDecryptError. rule 분류:
+ *   blob 길이/포맷 깨짐 → invalid_payload, auth tag 불일치(잘못된 키) → key_mismatch.
+ * @param {Buffer} key
+ * @param {string} encB64
+ * @param {string} field
+ * @returns {string} 평문
+ */
+function decryptOrThrow(key, encB64, field) {
+  try {
+    return decryptTransport(key, encB64).toString('utf8')
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    const rule = /too short|base64|invalid/i.test(msg)
+      ? ASP_RULES.INVALID_PAYLOAD
+      : ASP_RULES.KEY_MISMATCH
+    throw new MegaAspDecryptError(rule, `ASP ${field} decrypt failed.`, { field, cause: err })
+  }
+}
+
+/**
+ * nonce 기반 replay 검사 (ADR-058). nonceCache 미설정이면 no-op.
+ * **복호화 성공 후** 호출 — 위조 ciphertext 가 nonce 를 소모하지 않게.
+ * @param {import('./config.js').NormalizedAspConfig} cfg
+ * @param {string} encB64
+ * @param {string} field
+ */
+async function checkReplay(cfg, encB64, field) {
+  if (!cfg.nonceCache) return
+  let nonceHex
+  try {
+    nonceHex = extractNonce(encB64).toString('hex')
+  } catch (err) {
+    throw new MegaAspDecryptError(ASP_RULES.INVALID_PAYLOAD, `ASP ${field} malformed (nonce).`, {
+      field,
+      cause: err,
+    })
+  }
+  const fresh = await cfg.nonceCache.isFresh(nonceHex)
+  if (!fresh) {
+    throw new MegaAspDecryptError(ASP_RULES.REPLAY, `ASP ${field} replay detected.`, { field })
+  }
+}
+
+/**
+ * Readable stream 전체를 Buffer 로 수집.
+ * @param {import('node:stream').Readable} stream
+ * @returns {Promise<Buffer>}
+ */
+async function readStream(stream) {
+  const chunks = []
+  for await (const chunk of stream) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+/**
+ * Buffer → Readable. Fastify preParsing 계약: content-length 매칭용
+ * `receivedEncodedLength` 부착 (docs/Hooks preParsing 노트).
+ * @param {Buffer} buf
+ * @returns {import('node:stream').Readable & { receivedEncodedLength: number }}
+ */
+function makeStream(buf) {
+  const stream = Readable.from(buf)
+  // @ts-expect-error — Fastify 가 읽는 비표준 프로퍼티.
+  stream.receivedEncodedLength = buf.length
+  // @ts-expect-error
+  return stream
+}
+
+/**
+ * glob('/api/*') → RegExp. `*` 는 임의 문자열. 그 외 정규식 특수문자는 이스케이프.
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegex(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}

package/src/lib/asp/ws-terminator.js

@@ -0,0 +1,101 @@
+// @ts-check
+/**
+ * MegaAspTerminator — WS bridge-side ASP terminator (ADR-053/083/084).
+ *
+ * WS 프레임의 평문/암호 명시 신호(`P:` / `E:` prefix, ADR-083) 를 인코드·디코드한다.
+ * WASM 클라이언트(`MegaSocket`, `transport_ws.rs`) 와 **byte 호환** — 같은 알고리즘
+ * (`crypto.js` 의 `wsEncrypt`/`wsDecrypt`) 을 재사용하므로 wire 가 byte-for-byte 일치.
+ *
+ * # 프레임 규약 (ADR-083)
+ *   - 송신: `encrypt && !plain` → `E:<ts>:<base64>`. 그 외 → `P:<json>`.
+ *   - 수신: prefix 가 권위. `E:` 는 항상 복호화 시도, `P:` 는 평문, prefix 없으면
+ *     `invalid_payload`. decrypt 실패는 silent fallback 없이 throw (ADR-084).
+ *
+ * @module lib/asp/ws-terminator
+ */
+import { wsEncrypt, wsDecrypt } from './crypto.js'
+import { MegaAspDecryptError, ASP_RULES } from './errors.js'
+
+const PREFIX_ENCRYPTED = 'E:'
+const PREFIX_PLAIN = 'P:'
+
+export class MegaAspTerminator {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.masterSecret
+   * @param {string} opts.domain - Host (키 유도, 클라 location.hostname 과 일치)
+   * @param {string} opts.wsPath - WS 경로 (키 유도, 클라 URL path 와 일치)
+   * @param {string} opts.ua - User-Agent (키 유도)
+   * @param {boolean} [opts.encrypt=true] - 송신 기본 암호화 (ADR-086)
+   */
+  constructor({ masterSecret, domain, wsPath, ua, encrypt = true }) {
+    if (typeof masterSecret !== 'string' || masterSecret.length === 0) {
+      throw new Error('MegaAspTerminator: masterSecret is required (ADR-056).')
+    }
+    this._secret = masterSecret
+    this._domain = domain ?? ''
+    this._wsPath = wsPath ?? '/'
+    this._ua = ua ?? ''
+    this._encrypt = encrypt !== false
+  }
+
+  /** 이 terminator 가 기본 암호화 송신인지. */
+  get isEncrypted() {
+    return this._encrypt
+  }
+
+  /**
+   * 송신 프레임 생성. `plain=true` 또는 `encrypt=false` 면 `P:` 평문, 아니면 `E:` 암호화.
+   *
+   * @param {Object|string} message - 객체면 JSON.stringify, 문자열이면 그대로 (이미 JSON 가정).
+   * @param {{ plain?: boolean }} [opts]
+   * @returns {string} wire 프레임 (`E:` 또는 `P:` prefix 포함)
+   */
+  encodeFrame(message, { plain = false } = {}) {
+    const json = typeof message === 'string' ? message : JSON.stringify(message)
+    if (!this._encrypt || plain) return `${PREFIX_PLAIN}${json}`
+    const body = wsEncrypt(this._secret, this._domain, this._wsPath, this._ua, json)
+    return `${PREFIX_ENCRYPTED}${body}`
+  }
+
+  /**
+   * 수신 프레임 디코드. prefix 권위 (ADR-083). `E:` 복호화 실패 → throw (ADR-084).
+   *
+   * @param {string} frame - wire 프레임.
+   * @returns {{ encrypted: boolean, plain: string }} plain = 평문 JSON 문자열.
+   * @throws {MegaAspDecryptError} prefix 누락 / 복호화 실패.
+   */
+  decodeFrame(frame) {
+    if (typeof frame !== 'string') {
+      throw new MegaAspDecryptError(ASP_RULES.INVALID_PAYLOAD, 'WS frame must be a string.', {
+        field: 'frame',
+      })
+    }
+    if (frame.startsWith(PREFIX_PLAIN)) {
+      return { encrypted: false, plain: frame.slice(PREFIX_PLAIN.length) }
+    }
+    if (frame.startsWith(PREFIX_ENCRYPTED)) {
+      const body = frame.slice(PREFIX_ENCRYPTED.length)
+      try {
+        const plain = wsDecrypt(this._secret, this._domain, this._wsPath, this._ua, body)
+        return { encrypted: true, plain }
+      } catch (err) {
+        // ADR-084: 원문 fallback 금지 — 명시 에러. ts 파싱 실패 vs 복호화 실패 분류.
+        const msg = err instanceof Error ? err.message : String(err)
+        const rule = /missing ':'|invalid timestamp/.test(msg)
+          ? ASP_RULES.INVALID_PAYLOAD
+          : ASP_RULES.KEY_MISMATCH
+        throw new MegaAspDecryptError(rule, `WS frame decrypt failed: ${msg}`, {
+          field: 'frame',
+          cause: err,
+        })
+      }
+    }
+    // prefix 없음 → fuzionx 원본 포맷 wire 호환 X (ADR-083).
+    throw new MegaAspDecryptError(
+      ASP_RULES.INVALID_PAYLOAD,
+      'WS frame missing E:/P: prefix (ADR-083).',
+      { field: 'frame' },
+    )
+  }
+}

package/src/lib/env-mapper.js

@@ -0,0 +1,222 @@
+// @ts-check
+/**
+ * `.env` → 어댑터 옵션 자동 매핑 (ADR-109 / 12-factor).
+ *
+ * 모든 어댑터 옵션이 `.env` 로 외부 주입 가능해야 한다는 결정(12-factor)에 따라, `MEGA_<SERVICE>_<KEY>`
+ * 환경변수를 표준 어댑터 옵션 객체(`adapter-options.js` 의 통합 시그니처)로 변환한다.
+ *
+ * # 매핑 규칙 (prefix `MEGA_<SERVICE>_` 제거 후 남은 suffix 기준)
+ *   | suffix              | 결과                       | 예                                            |
+ *   |---------------------|----------------------------|-----------------------------------------------|
+ *   | URL                 | `{ url }`                  | MEGA_PG_URL=postgres://…  → `{ url: '…' }`     |
+ *   | HOST/PORT/USER/PASSWORD | `{ host/port/user/password }` | MEGA_PG_HOST=localhost → `{ host:'localhost' }` |
+ *   | DATABASE \| DB      | `{ database }`             | MEGA_PG_DB=app → `{ database: 'app' }`         |
+ *   | DBNAME              | `{ dbName }` (Mongo)       | MEGA_MONGO_DBNAME=app → `{ dbName: 'app' }`    |
+ *   | POOL_<X>            | `{ pool: { camelCase(X) } }` | MEGA_PG_POOL_MAX=10 → `{ pool:{ max:10 } }`  |
+ *   | OPTIONS_<X>         | `{ options: { driverKey(X) } }` | **driver 별 변환** — 아래 "driver-aware OPTIONS_*" 참조 |
+ *
+ * # driver-aware OPTIONS_* 변환 (ADR-109 보강)
+ *   `.env` 는 관례상 `UPPER_SNAKE_CASE` 로 쓰지만, 드라이버가 인식하는 옵션 키 표기는 제각각이다:
+ *   ioredis/nats/mongodb/mariadb 는 **camelCase**(`keyPrefix`, `maxReconnectAttempts`,
+ *   `serverSelectionTimeoutMS`), pg/sqlite 는 **snake_case**(`statement_timeout`). 그래서 OPTIONS_*
+ *   의 suffix 를 **driver 별 표기로 변환**한다(`{@link DRIVER_KEY_STYLE}`). driver 를 모르면(미지정/미상)
+ *   snake 로 두고, 미상 driver 면 1회 warn 한다(fail-safe — 추측 변환 X).
+ *     - camel: `KEY_PREFIX`→`keyPrefix`, `MAX_RECONNECT_ATTEMPTS`→`maxReconnectAttempts`,
+ *              `SERVER_SELECTION_TIMEOUT_MS`→`serverSelectionTimeoutMS`(`MS` 접미사 대문자 보존).
+ *     - snake: `STATEMENT_TIMEOUT`→`statement_timeout`(그대로 lowercase).
+ *   POOL_* 는 driver 무관 **공통 풀 인터페이스**(이미 camelCase 표준)라 변환 정책에서 제외 — 항상 camelCase.
+ *
+ * # Redis `db` 특례
+ *   Redis 의 `DB`/`DATABASE` 는 connection(host/url)이 아니라 **논리 DB 번호(정수 별개 축)**다.
+ *   driver=='redis' 면 `MEGA_REDIS_DB=1` → `{ db: 1 }`(정수, `database` 가 아님 — redis-adapter 가
+ *   `database` 는 무시하므로 db 축 설정이 불가능했던 버그를 교정). 범위(0~15) 검증은 어댑터 생성자 책임.
+ *
+ * # 값 타입 자동 변환 (POOL_*·OPTIONS_* 만)
+ *   `'true'/'false'/'null'` → boolean/null, 정수/소수 → Number, `{`·`[` 로 시작하면 JSON.parse.
+ *   단 **2^53(MAX_SAFE_INTEGER) 초과 정수는 문자열로 유지**(IEEE-754 정밀도 손실 방지, L-3 — warn 1회).
+ *   **연결 필드(url/host/user/password/database/dbName)는 항상 문자열** — 비밀번호가 `12345` 같이 숫자
+ *   처럼 보여도 문자열로 보존(숫자 강제 시 자격증명 깨짐). port·redis db 만 정수.
+ *
+ * # 알 수 없는 키 처리
+ *   `MEGA_<SERVICE>_` namespace 는 docker-compose 인프라 제어 변수(예: `MEGA_MARIA_ROOT_PASSWORD`,
+ *   ADR-103)와 **공유**되므로, 위 grammar 에 안 맞는 suffix 는 **어댑터 옵션이 아닌 것으로 간주해 무시**한다
+ *   (throw 하면 인프라 변수에서 깨짐). 단, POOL_*·OPTIONS_* 하위 키의 오타는 무시되지 않고 어댑터의
+ *   `normalizePool`/드라이버가 fail-fast 로 잡는다(예: MEGA_PG_POOL_MAXX → pool.maxx → `adapter.invalid_option`).
+ *   즉 "조용한 실패" 가 위험한 풀/옵션 키는 downstream 에서 검출되고, 무시되는 건 인프라 전용 변수뿐이다.
+ *
+ * @module lib/env-mapper
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+
+/** 연결 필드 suffix → 표준 키 (값은 항상 문자열, port 제외). */
+const CONNECTION_KEYS = /** @type {const} */ ({
+  URL: 'url',
+  HOST: 'host',
+  PORT: 'port',
+  USER: 'user',
+  PASSWORD: 'password',
+  DATABASE: 'database',
+  DB: 'database',
+  DBNAME: 'dbName',
+})
+
+/**
+ * driver → OPTIONS_* 키 표기 스타일. 드라이버가 실제로 인식하는 옵션 키 표기에
+ * 맞춘다 — camelCase 드라이버에 snake 키를 넘기면 **조용히 무시**되던 버그를 교정한다.
+ *   - 'camel': ioredis/nats 공식 옵션은 camelCase(`keyPrefix`, `maxReconnectAttempts`). mongodb 드라이버
+ *     옵션도 camelCase(+`MS` 접미사), mariadb `createPool` 옵션도 camelCase(`multipleStatements` 등).
+ *   - 'snake': pg(`statement_timeout`)·better-sqlite3 는 snake_case 가 자연스럽다.
+ * @type {Record<string, 'camel' | 'snake'>}
+ */
+const DRIVER_KEY_STYLE = {
+  postgres: 'snake',
+  mariadb: 'camel',
+  mongodb: 'camel',
+  sqlite: 'snake',
+  redis: 'camel',
+  nats: 'camel',
+  redlock: 'camel', // redlock Settings(driftFactor/retryCount/retryDelay/retryJitter/automaticExtensionThreshold)는 camelCase.
+  file: 'snake', // File 자체 옵션(serializer/extension)은 단일 단어라 snake/camel 무관.
+}
+
+/**
+ * camelCase 변환 시 **그대로 대문자로 보존**할 토큰(드라이버 관례). mongodb 의 `*MS` 접미사
+ * (`serverSelectionTimeoutMS`, `connectTimeoutMS`, `maxIdleTimeMS` …)가 대표 — 일반 camelCase 로는
+ * `Ms` 가 되어 드라이버가 인식 못 한다. 추측이 아니라 mongodb 드라이버 옵션 표기를 직접 따른다.
+ */
+const PRESERVED_UPPER = new Set(['MS'])
+
+/**
+ * `MEGA_<SERVICE>_*` 환경변수를 표준 어댑터 옵션 객체로 변환한다. OPTIONS_* 의 키 표기는 `driver`
+ * 별로 변환된다(camel/snake, {@link DRIVER_KEY_STYLE}).
+ *
+ * @param {string} service - 서비스 prefix(대소문자 무관, 예: 'pg' / 'PG' / 'maria' / 'mongo').
+ * @param {Record<string, string | undefined>} [env] - 환경변수 맵(기본 `process.env`).
+ * @param {{ driver?: string }} [opts] - `driver`(예 'redis'/'postgres') — OPTIONS_* 키 표기 변환 + redis db 특례에 사용.
+ *   미지정이면 snake(레거시 디폴트), 미상 driver 면 snake + warn 1회(fail-safe).
+ * @returns {Record<string, any>} 어댑터 옵션 partial (`{ url?, host?, …, db?, pool?, options? }`). 매칭 없으면 빈 객체.
+ * @throws {MegaValidationError} `adapter.env_invalid_value` - PORT/redis DB 가 정수가 아님.
+ */
+export function buildAdapterEnvConfig(service, env = process.env, { driver } = {}) {
+  if (typeof service !== 'string' || service.length === 0) {
+    throw new MegaValidationError('adapter.env_invalid_prefix', 'buildAdapterEnvConfig(service): service prefix must be a non-empty string.', {
+      details: { service },
+    })
+  }
+  const prefix = `MEGA_${service.toUpperCase()}_`
+  // OPTIONS_* 키 표기 스타일 결정: driver 미지정 → snake(레거시). driver 지정+미상 → snake + lazy warn.
+  const normalizedDriver = typeof driver === 'string' ? driver.toLowerCase() : undefined
+  const mappedStyle = normalizedDriver !== undefined ? DRIVER_KEY_STYLE[normalizedDriver] : undefined
+  const optionStyle = mappedStyle ?? 'snake'
+  let didWarnUnknownDriver = false
+  /** @type {Record<string, any>} */
+  const config = {}
+
+  for (const [envKey, rawValue] of Object.entries(env)) {
+    if (rawValue === undefined) continue
+    if (!envKey.startsWith(prefix)) continue
+    const suffix = envKey.slice(prefix.length)
+
+    if (suffix.startsWith('POOL_')) {
+      const rest = suffix.slice('POOL_'.length)
+      if (rest.length === 0) continue
+      // POOL_* 은 driver 무관 공통 풀 인터페이스(camelCase 표준) — driver-aware 변환에서 제외.
+      ;(config.pool ??= {})[toCamelCase(rest)] = coerceValue(rawValue)
+    } else if (suffix.startsWith('OPTIONS_')) {
+      const rest = suffix.slice('OPTIONS_'.length)
+      if (rest.length === 0) continue
+      // driver 가 지정됐는데 표를 모르면(미상) 1회 warn 후 snake 폴백 — 추측 변환 X.
+      if (normalizedDriver !== undefined && mappedStyle === undefined && !didWarnUnknownDriver) {
+        console.warn(
+          `[env-mapper] unknown driver "${driver}" — OPTIONS_* keys kept as snake_case (no driver-aware conversion). Known: ${Object.keys(DRIVER_KEY_STYLE).join(', ')}.`,
+        )
+        didWarnUnknownDriver = true
+      }
+      ;(config.options ??= {})[toOptionKey(rest, optionStyle)] = coerceValue(rawValue)
+    } else if (normalizedDriver === 'redis' && (suffix === 'DB' || suffix === 'DATABASE')) {
+      // Redis 특례 — DB/DATABASE 는 connection 이 아니라 논리 DB 번호(정수 별개 축, M-1).
+      config.db = coerceInt(rawValue, envKey)
+    } else if (Object.prototype.hasOwnProperty.call(CONNECTION_KEYS, suffix)) {
+      const key = CONNECTION_KEYS[/** @type {keyof typeof CONNECTION_KEYS} */ (suffix)]
+      config[key] = key === 'port' ? coerceInt(rawValue, envKey) : rawValue
+    }
+    // else: grammar 불일치 — docker-infra 전용 변수로 보고 무시(위 docstring 참조).
+  }
+  return config
+}
+
+/**
+ * `IDLE_TIMEOUT_MS` → `idleTimeoutMs` (UPPER_SNAKE → camelCase). POOL_* 공통 인터페이스 전용.
+ * @param {string} upperSnake @returns {string}
+ */
+function toCamelCase(upperSnake) {
+  return upperSnake
+    .toLowerCase()
+    .split('_')
+    .map((w, i) => (i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join('')
+}
+
+/**
+ * OPTIONS_* suffix 를 driver 표기로 변환.
+ *   - 'snake': 그대로 lowercase (`STATEMENT_TIMEOUT` → `statement_timeout`).
+ *   - 'camel': UPPER_SNAKE → camelCase, 단 `MS` 등 {@link PRESERVED_UPPER} 토큰은 대문자 보존
+ *     (`SERVER_SELECTION_TIMEOUT_MS` → `serverSelectionTimeoutMS`).
+ * @param {string} upperSnake @param {'camel' | 'snake'} style @returns {string}
+ */
+function toOptionKey(upperSnake, style) {
+  if (style === 'snake') return upperSnake.toLowerCase()
+  return upperSnake
+    .split('_')
+    .map((w, i) => {
+      if (PRESERVED_UPPER.has(w)) return w // 예: MS → MS (대문자 보존).
+      const lower = w.toLowerCase()
+      return i === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1)
+    })
+    .join('')
+}
+
+/**
+ * POOL_*·OPTIONS_* 값 타입 자동 변환. 변환 불가하면 원본 문자열.
+ * @param {string} v @returns {string | number | boolean | null | object}
+ */
+function coerceValue(v) {
+  if (v === 'true') return true
+  if (v === 'false') return false
+  if (v === 'null') return null
+  if (/^-?\d+$/.test(v)) {
+    const n = Number(v)
+    // 2^53(MAX_SAFE_INTEGER) 초과 정수는 IEEE-754 double 로 변환 시 정밀도 손실(예 9007199254740993→…992).
+    // BigInt 변환은 JSON 직렬화 비호환이라 채택하지 않고, 원본 문자열을 그대로 보존한다(L-3).
+    // 큰 ID/카운터를 옵션으로 넘기는 경우 문자열이 안전 — downstream 드라이버가 필요 시 해석한다.
+    if (!Number.isSafeInteger(n)) {
+      console.warn(`[env-mapper] integer value exceeds Number.MAX_SAFE_INTEGER, keeping as string to avoid precision loss: "${v}"`)
+      return v
+    }
+    return n
+  }
+  if (/^-?\d*\.\d+$/.test(v)) return Number(v)
+  const t = v.trim()
+  if (t.startsWith('{') || t.startsWith('[')) {
+    try {
+      return JSON.parse(t)
+    } catch {
+      // JSON 처럼 보였으나 파싱 실패 — 원본 문자열 보존(추측 변환 X). 의도적 폴백.
+      return v
+    }
+  }
+  return v
+}
+
+/**
+ * 정수 강제 변환(PORT 전용). 정수가 아니면 throw(silent 0 변환 금지).
+ * @param {string} v @param {string} envKey @returns {number}
+ */
+function coerceInt(v, envKey) {
+  if (!/^-?\d+$/.test(v)) {
+    throw new MegaValidationError('adapter.env_invalid_value', `${envKey} must be an integer, got "${v}".`, {
+      details: { envKey, value: v },
+    })
+  }
+  return Number(v)
+}