mega-framework 0.1.0

package/src/lib/mega-brute-force.js

@@ -0,0 +1,225 @@
+// @ts-check
+/**
+ * MegaBruteForce — 동일 키 반복 시도 차단 (ADR-049 / ADR-130).
+ *
+ * # 무엇을 막나 (중학생용 설명)
+ *   공격자는 한 계정에 비밀번호를 수천 번 찍어보며 뚫으려 한다(brute force). MegaBruteForce 는 "같은
+ *   대상(이메일·IP 등)이 정해진 횟수 이상 **실패**하면 일정 시간 잠근다". 잠긴 동안에는 맞는 비밀번호를
+ *   넣어도 일단 거부 — 공격 비용을 폭증시킨다. 로그인뿐 아니라 비밀번호 리셋·인증코드 확인 등 "반복
+ *   시도가 위험한 모든 길목" 에 쓴다.
+ *
+ * # 동작 (fixed window + lockout)
+ *   - `fail(subject)` 한 번마다 시도 카운터를 **원자적으로 +1**(Redis `INCR`). 첫 실패에 윈도우 TTL
+ *     (`windowMs`)을 건다 — 윈도우가 지나면 카운터가 자연 소멸(고정 윈도우).
+ *   - 카운터가 `maxAttempts` 에 도달하면 **잠금 키**를 `lockMs` 동안 세우고 카운터는 비운다.
+ *   - `check(subject)` 는 시도 **전에** 호출해 현재 잠금/남은 횟수를 본다(부수효과 없음).
+ *   - `reset(subject)` 는 로그인 **성공** 시 호출해 카운터·잠금을 즉시 지운다.
+ *
+ * # subject 선택 가이드 (계정 잠금 DoS 방어, I-1)
+ *   subject 는 **IP 또는 IP+email 조합을 권장**한다. email 단독으로 잠그면, 공격자가 피해자 email 로
+ *   일부러 반복 실패시켜 **정상 사용자를 잠가버리는** 계정 잠금 DoS(account-lockout DoS)가 가능하다.
+ *   IP 를 섞으면(예: `${ip}:${email}`) 공격자는 자기 IP 만 잠그게 돼 피해자 로그인은 막히지 않는다.
+ *   (프록시·NAT 뒤 다중 사용자, IPv6 prefix 등 환경에 따라 IP 단독/조합을 호출부가 선택한다.)
+ *
+ * # 저장소 = Redis (ADR-049)
+ *   원자적 카운팅이 핵심이라 백엔드는 Redis 다(`INCR`/`PEXPIRE`/`PTTL`/`SET PX`). 생성자에 **연결된
+ *   `MegaCacheAdapter`(redis driver)** 를 주입하면 그 `.native`(ioredis)로 직접 명령한다. 03-api-spec §786
+ *   의 `cache: string`(별명)은 프레임워크 배선층(`ctx.bruteForce`)이 별명→어댑터로 해석해 주입한다 —
+ *   순수 lib 은 별명을 모르므로 어댑터 인스턴스를 받는다(ADR-130 명시).
+ *
+ * # 에러를 묵지 않는다
+ *   Redis 명령 실패는 throw 한다(삼키지 않음). 잠금 판단을 "에러나서 통과" 시키면 보호가 무력화되므로,
+ *   호출부가 장애를 인지하고 정책(예: 5xx 또는 보수적 거부)을 **명시적으로** 정하게 한다.
+ *
+ * # 관측은 하되 PII 는 가린다
+ *   subject(이메일·IP)는 원본을 span/로그에 절대 안 박는다 — SHA-256 앞 16자 해시만 노출.
+ *   활성 트레이싱 span 에 `mega.bruteforce.{event,locked,attempts_left,namespace,subject(hash)}` attribute
+ *   (ADR-126 재사용, 옵트인 OFF 면 no-op).
+ *
+ * @module lib/mega-brute-force
+ * @see ADR-049 (MegaBruteForce 1차 포함), ADR-130 (scrypt/배선/정책)
+ */
+import { createHash } from 'node:crypto'
+import { MegaValidationError, MegaInternalError } from '../errors/http-errors.js'
+import { tracer as megaTracer } from './mega-tracing.js'
+import { recordBruteForce } from './mega-metrics.js'
+
+/** 기본 정책값 (ADR-049 — docs/12 T8 정합). 생성자 opts 로 오버라이드. */
+const DEFAULTS = Object.freeze({ maxAttempts: 5, windowMs: 15 * 60_000, lockMs: 15 * 60_000 })
+
+/** Redis 키 prefix(cache 어댑터의 `mega:cache:*` 와 분리된 brute-force 전용 네임스페이스). */
+const KEY_ROOT = 'mega:bf'
+
+/**
+ * @typedef {object} BruteForceResult - check/fail 반환 형태 (03-api-spec §786).
+ * @property {boolean} locked - 현재 잠김 여부.
+ * @property {boolean} isLocked - `locked` 별칭(Boolean 컨벤션 — 둘 다 노출).
+ * @property {number} attemptsLeft - 잠기기까지 남은 실패 허용 횟수(잠겼으면 0).
+ * @property {number} retryAfterMs - 잠금 해제까지 남은 ms(안 잠겼으면 0).
+ */
+
+export class MegaBruteForce {
+  /** @type {import('../adapters/mega-cache-adapter.js').MegaCacheAdapter} */
+  #cache
+  /** @type {string} 네임스페이스(도메인 구분 — 예: 'login', 'password-reset'). */
+  #namespace
+  #maxAttempts
+  #windowMs
+  #lockMs
+
+  /**
+   * @param {object} opts
+   * @param {import('../adapters/mega-cache-adapter.js').MegaCacheAdapter} opts.cache - 연결된 redis 캐시 어댑터(`.native`=ioredis).
+   * @param {string} opts.key - 네임스페이스(도메인 구분). 03-api-spec 의 생성자 `key`.
+   * @param {number} [opts.maxAttempts=5] - 잠금까지 허용 실패 횟수.
+   * @param {number} [opts.windowMs=900000] - 시도 카운트 윈도우(ms). 첫 실패부터 이 시간 뒤 카운터 소멸.
+   * @param {number} [opts.lockMs=900000] - 잠금 지속 시간(ms).
+   * @throws {MegaValidationError} `bruteforce.invalid_option` - cache/key 누락 또는 수치 옵션 비-양의정수.
+   */
+  constructor(opts = /** @type {any} */ ({})) {
+    if (!opts.cache || typeof opts.cache !== 'object') {
+      throw new MegaValidationError('bruteforce.invalid_option', 'MegaBruteForce: opts.cache (connected redis MegaCacheAdapter) is required.')
+    }
+    if (typeof opts.key !== 'string' || opts.key.length === 0) {
+      throw new MegaValidationError('bruteforce.invalid_option', 'MegaBruteForce: opts.key (namespace string) is required.')
+    }
+    this.#cache = opts.cache
+    this.#namespace = opts.key
+    this.#maxAttempts = assertPositiveInt(opts.maxAttempts ?? DEFAULTS.maxAttempts, 'maxAttempts')
+    this.#windowMs = assertPositiveInt(opts.windowMs ?? DEFAULTS.windowMs, 'windowMs')
+    this.#lockMs = assertPositiveInt(opts.lockMs ?? DEFAULTS.lockMs, 'lockMs')
+  }
+
+  /**
+   * 연결된 ioredis 클라이언트. cache 어댑터가 redis 가 아니면(=`.native` 가 ioredis 명령 미보유) fail-fast.
+   * @returns {import('ioredis').Redis}
+   */
+  #client() {
+    const client = /** @type {any} */ (this.#cache).native // 미연결이면 베이스 getter 가 throw(fail-fast).
+    if (!client || typeof client.incr !== 'function') {
+      throw new MegaInternalError('bruteforce.redis_required', 'MegaBruteForce requires a Redis cache adapter (atomic INCR/PEXPIRE). The provided cache is not Redis.')
+    }
+    return client
+  }
+
+  /** @param {string} subject @returns {string} 시도 카운터 Redis 키. */
+  #attemptsKey(subject) {
+    return `${KEY_ROOT}:${this.#namespace}:a:${subject}`
+  }
+
+  /** @param {string} subject @returns {string} 잠금 Redis 키. */
+  #lockKey(subject) {
+    return `${KEY_ROOT}:${this.#namespace}:l:${subject}`
+  }
+
+  /**
+   * 시도 **전** 현재 상태 조회(부수효과 없음). 잠겨 있으면 호출부가 즉시 거부할 수 있다.
+   * @param {string} subject - 대상 식별자(이메일·IP 등).
+   * @returns {Promise<BruteForceResult>}
+   */
+  async check(subject) {
+    assertSubject(subject)
+    const client = this.#client()
+    const lockTtl = await client.pttl(this.#lockKey(subject)) // -2=키없음, -1=무한, >0=남은 ms.
+    if (lockTtl > 0) {
+      return this.#emit('check', subject, { locked: true, isLocked: true, attemptsLeft: 0, retryAfterMs: lockTtl })
+    }
+    const raw = await client.get(this.#attemptsKey(subject))
+    const n = raw === null ? 0 : Number(raw)
+    return this.#emit('check', subject, {
+      locked: false,
+      isLocked: false,
+      attemptsLeft: Math.max(0, this.#maxAttempts - n),
+      retryAfterMs: 0,
+    })
+  }
+
+  /**
+   * 실패 1건 기록. 카운터를 원자적으로 +1 하고, `maxAttempts` 도달 시 잠금을 건다.
+   * 이미 잠긴 상태면 카운터를 더 늘리지 않고 잠금 정보를 그대로 반환한다.
+   * @param {string} subject - 대상 식별자.
+   * @returns {Promise<BruteForceResult>}
+   */
+  async fail(subject) {
+    assertSubject(subject)
+    const client = this.#client()
+    const lockKey = this.#lockKey(subject)
+    const lockTtl = await client.pttl(lockKey)
+    if (lockTtl > 0) {
+      // 이미 잠김 — 추가 증가 없이 현 상태 반환.
+      return this.#emit('fail', subject, { locked: true, isLocked: true, attemptsLeft: 0, retryAfterMs: lockTtl })
+    }
+    const attemptsKey = this.#attemptsKey(subject)
+    const n = await client.incr(attemptsKey) // 원자적 +1(없으면 1로 생성).
+    if (n === 1) {
+      // 첫 실패에만 윈도우 TTL — 고정 윈도우(이후 실패는 같은 윈도우 안에서 누적).
+      // (incr→pexpire 사이 크래시 시 키가 TTL 없이 잔존할 수 있으나, 이는 "더 오래 카운트"=fail-closed
+      //  방향이라 보안상 안전. 다음 reset/lockout 이 정리한다.)
+      await client.pexpire(attemptsKey, this.#windowMs)
+    }
+    if (n >= this.#maxAttempts) {
+      // 임계 도달 — 잠금 세우고(PX=lockMs) 카운터는 비운다(잠금 해제 후 새 윈도우로 시작).
+      await client.set(lockKey, '1', 'PX', this.#lockMs)
+      await client.del(attemptsKey)
+      return this.#emit('lockout', subject, { locked: true, isLocked: true, attemptsLeft: 0, retryAfterMs: this.#lockMs })
+    }
+    return this.#emit('fail', subject, {
+      locked: false,
+      isLocked: false,
+      attemptsLeft: this.#maxAttempts - n,
+      retryAfterMs: 0,
+    })
+  }
+
+  /**
+   * 카운터·잠금 즉시 제거(로그인 성공 등 정상 시도 후).
+   * @param {string} subject - 대상 식별자.
+   * @returns {Promise<void>}
+   */
+  async reset(subject) {
+    assertSubject(subject)
+    const client = this.#client()
+    await client.del(this.#attemptsKey(subject), this.#lockKey(subject))
+    this.#emit('reset', subject, { locked: false, isLocked: false, attemptsLeft: this.#maxAttempts, retryAfterMs: 0 })
+  }
+
+  /**
+   * 활성 트레이싱 span 에 brute-force 이벤트 attribute 를 박고 결과를 그대로 반환한다(ADR-126).
+   * 옵트인 OFF 면 activeSpan()===undefined → no-op. subject 는 해시만 노출.
+   * @template {object} T
+   * @param {'check'|'fail'|'lockout'|'reset'} event @param {string} subject @param {T} result
+   * @returns {T}
+   */
+  #emit(event, subject, result) {
+    megaTracer.activeSpan()?.setAttributes({
+      'mega.bruteforce.event': event,
+      'mega.bruteforce.namespace': this.#namespace,
+      'mega.bruteforce.subject': hashSubject(subject),
+      'mega.bruteforce.locked': /** @type {any} */ (result).isLocked === true,
+      'mega.bruteforce.attempts_left': /** @type {any} */ (result).attemptsLeft,
+    })
+    // 메트릭 집계(ADR-131) — namespace+event 만(subject 는 PII·카디널리티 폭증이라 미노출). 옵트인 OFF 면 0 비용.
+    recordBruteForce({ namespace: this.#namespace, event })
+    return result
+  }
+}
+
+/** subject 를 span/로그용으로 해시(원본 비노출). @param {string} subject @returns {string} */
+function hashSubject(subject) {
+  return createHash('sha256').update(subject).digest('hex').slice(0, 16)
+}
+
+/** @param {unknown} subject @throws {MegaValidationError} 비-문자열/빈 문자열. */
+function assertSubject(subject) {
+  if (typeof subject !== 'string' || subject.length === 0) {
+    throw new MegaValidationError('bruteforce.invalid_subject', 'MegaBruteForce: subject must be a non-empty string (e.g. email or IP).')
+  }
+}
+
+/** @param {unknown} v @param {string} name @returns {number} 양의 정수면 반환, 아니면 throw. */
+function assertPositiveInt(v, name) {
+  if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
+    throw new MegaValidationError('bruteforce.invalid_option', `MegaBruteForce: ${name} must be a positive integer. Got ${v}`)
+  }
+  return v
+}

package/src/lib/mega-circuit-breaker.js

@@ -0,0 +1,412 @@
+// @ts-check
+/**
+ * MegaCircuitBreaker — 외부 호출 보호용 서킷 브레이커 (ADR-117).
+ *
+ * 검증된 공개 라이브러리 `opossum`(v9) 을 우리 컨벤션으로 얇게 래핑한다(ADR-029: "내부 구현은
+ * 검증된 공개 npm 라이브러리를 래핑한다" — MegaRetry=p-retry 선례와 동일 원칙). 롤링 윈도우 집계,
+ * half-open 복구 프로빙, 타임아웃, semaphore(capacity) 같은 경계 케이스를 직접 짜면 추론 최소화 원칙
+ * 위반이 되기 쉽다. opossum 은 이를 검증된 형태로 제공한다.
+ *
+ * # 서킷 브레이커란 (중학생용 설명)
+ *   외부 서비스(결제 API·DB 등)가 자꾸 실패하면, 매번 똑같이 호출해 봐야 또 실패하고 시간만 낭비된다.
+ *   서킷 브레이커는 "최근 실패율이 너무 높다" 싶으면 회로를 **열어**(open) 한동안 아예 호출을 막고
+ *   즉시 실패시킨다(빠른 실패). 일정 시간 뒤 **half-open** 상태로 딱 한 번 살짝 찔러보고, 성공하면
+ *   다시 **닫아**(closed=정상) 호출을 흘려보낸다. 장애 서비스에 부하를 안 주고, 우리 쪽도 빨리 회복.
+ *
+ *   상태 3종:
+ *     - closed   : 정상. 호출이 그대로 통과. 실패율을 롤링 윈도우로 집계.
+ *     - open     : 차단. errorThresholdPercentage 초과 → 즉시 거부(`EOPENBREAKER`). 원함수 호출 안 함.
+ *     - halfOpen : 복구 프로빙. resetTimeout 경과 후 1회 시도 — 성공 시 closed, 실패 시 다시 open.
+ *
+ * # stateful — `wrap()` 는 재사용 인스턴스를 반환 (MegaRetry 와 다른 점)
+ *   MegaRetry.withRetry 는 호출 1회를 즉시 실행하는 one-shot 헬퍼다. 서킷 브레이커는 **실패 통계를
+ *   누적**해야 동작하므로 그럴 수 없다 — 호출마다 새로 만들면 카운터가 늘 0 이라 절대 trip(open)
+ *   되지 않는다. 그래서 `wrap(fn, opts)` 는 보호할 함수 1개당 **하나의 장수(long-lived) 브레이커**를
+ *   만들어 반환하고, 이후 모든 호출은 `breaker.fire(...args)` 로 같은 인스턴스를 거친다.
+ *
+ * # 에러를 묵지 않는다
+ *   회로가 열려 거부될 때 `fire()` 는 `code: 'EOPENBREAKER'` 에러로 **reject** 한다(삼키지 않음).
+ *   타임아웃은 `ETIMEDOUT`, capacity 초과는 `ESEMLOCKED`. 호출부는 이 코드로 분기해 폴백/재시도 등을
+ *   **명시적으로** 처리한다. 빠른 폴백이 필요하면 {@link MegaCircuitBreaker#fallback}.
+ *
+ * # 상태 전이는 관측 가능하게
+ *   브레이커는 logger 를 모르는 순수 유틸이라(MegaRetry 와 동일) 직접 로그를 박지 않는다. 대신 상태
+ *   전이(`open`/`halfOpen`/`close`)와 호출 결과(`success`/`failure`/`timeout`/`reject`) 이벤트를
+ *   {@link MegaCircuitBreaker#on} 으로 노출한다 — 소비자(스케줄러·잡·라우트 등)가 이 분기점에
+ *   `logger.debug/warn` 을 박는다. open/close 는 대표적 "분기점"이다.
+ *
+ * @module lib/mega-circuit-breaker
+ * @see https://nodeshift.dev/opossum/ (opossum 공식 문서)
+ * @see ADR-117, ADR-029 (공개 라이브러리 래핑 원칙)
+ */
+import CircuitBreaker from 'opossum'
+
+/**
+ * 회로가 **열려** 호출이 거부됐을 때 `fire()` 가 reject 하는 에러의 `code`. 호출부가
+ * `err.code === OPEN_CIRCUIT_ERROR_CODE` 로 "지금은 차단 중" 을 분기 판별할 때 쓴다. (opossum 정본.)
+ * @type {'EOPENBREAKER'}
+ */
+export const OPEN_CIRCUIT_ERROR_CODE = 'EOPENBREAKER'
+
+/**
+ * 호출이 `timeout` ms 를 넘겨 실패 처리된 에러의 `code`. (opossum 정본.)
+ * @type {'ETIMEDOUT'}
+ */
+export const TIMEOUT_ERROR_CODE = 'ETIMEDOUT'
+
+/**
+ * 동시 호출이 `capacity` 한도를 넘어 거부된 에러의 `code`. (opossum 정본.)
+ * @type {'ESEMLOCKED'}
+ */
+export const CAPACITY_ERROR_CODE = 'ESEMLOCKED'
+
+/**
+ * 브레이커 생성 옵션. opossum 옵션 중 **서킷 브레이커 본질에 해당하는 것만** 추려 노출한다(캐시·
+ * coalesce 등 부가 기능은 escape hatch {@link MegaCircuitBreaker#raw} 로 직접 접근). 디폴트는
+ * opossum 정본값을 **명시적으로** 다시 박는다 — opossum 버전 드리프트와 무관하게 동작을 고정.
+ *
+ * @typedef {Object} MegaCircuitBreakerOptions
+ * @property {number} [timeout=10000] - 단일 호출 제한 시간(ms). 초과 시 `ETIMEDOUT` 으로 실패 처리.
+ *   `false`(또는 0)면 타임아웃 끔.
+ * @property {number} [errorThresholdPercentage=50] - 롤링 윈도우 실패율(%)이 이 값을 넘으면 회로 open.
+ * @property {number} [resetTimeout=30000] - open 상태 유지 시간(ms). 경과 후 halfOpen 으로 1회 프로빙.
+ * @property {number} [rollingCountTimeout=10000] - 실패율 집계 롤링 윈도우 길이(ms).
+ * @property {number} [rollingCountBuckets=10] - 롤링 윈도우를 나누는 버킷 수.
+ * @property {number} [volumeThreshold=0] - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
+ *   (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+ * @property {number} [capacity] - 동시 진행(in-flight) 호출 상한. 초과분은 `ESEMLOCKED` 로 즉시 거부.
+ *   미지정=무제한.
+ * @property {(err: any, ...args: any[]) => boolean} [errorFilter] - `true` 반환 시 그 에러는 **실패로 집계하지 않음**
+ *   (예: 4xx 같은 "정상적 거절"). 회로 trip 대상에서 제외.
+ * @property {string} [name] - 브레이커 이름(이벤트·stats 식별용). 미지정 시 `fn.name || 'anonymous'`.
+ */
+
+/**
+ * 브레이커 통계 스냅샷({@link MegaCircuitBreaker#getStats} 반환). opossum `status.stats` 의 핵심
+ * 카운터만 추려 평탄화한다(핵심 필드만, 페이로드·시크릿 없음).
+ *
+ * @typedef {Object} MegaCircuitBreakerStats
+ * @property {string} name - 브레이커 이름.
+ * @property {'closed'|'open'|'halfOpen'|'shutdown'} state - 현재 상태. shutdown 후엔 `'shutdown'`.
+ * @property {number} fires - 누적 호출 시도 수.
+ * @property {number} successes - 성공 수.
+ * @property {number} failures - 실패 수.
+ * @property {number} timeouts - 타임아웃 수.
+ * @property {number} rejects - 회로 open 으로 거부된 수.
+ * @property {number} fallbacks - 폴백이 실행된 수.
+ */
+
+/** opossum 이벤트명 화이트리스트 — 오타 방지 + 문서화(소비자가 구독 가능한 길목). */
+const KNOWN_EVENTS = Object.freeze([
+  'fire', // 매 호출 시작
+  'success', // 호출 성공
+  'failure', // 호출 실패(집계 대상)
+  'timeout', // timeout 초과
+  'reject', // 회로 open 으로 거부
+  'open', // 회로 열림(차단 시작) — 분기점
+  'halfOpen', // 복구 프로빙 진입 — 분기점
+  'close', // 회로 닫힘(정상 복귀) — 분기점
+  'fallback', // 폴백 실행
+  'semaphoreLocked', // capacity 초과 거부
+  'healthCheckFailed', // healthCheck 함수 실패
+  'shutdown', // 브레이커 종료
+])
+
+/**
+ * 외부 호출을 서킷 브레이커로 감싸는 래퍼. opossum `CircuitBreaker` 인스턴스 1개를 보유하고, 우리
+ * 컨벤션(Boolean `is*` 게터·`getStats()`·이벤트 화이트리스트)으로 표면을 정리한다.
+ *
+ * @example
+ * const breaker = new MegaCircuitBreaker(callPaymentApi, { timeout: 3000, errorThresholdPercentage: 50 })
+ * breaker.on('open', () => log.warn('payment circuit open'))
+ * try {
+ *   const res = await breaker.fire(orderId)
+ * } catch (e) {
+ *   if (e.code === OPEN_CIRCUIT_ERROR_CODE) return useCachedQuote() // 명시적 폴백
+ *   throw e
+ * }
+ */
+export class MegaCircuitBreaker {
+  /** @type {import('opossum')<any[], any>} 내부 opossum 브레이커. */
+  #breaker
+
+  /**
+   * @param {(...args: any[]) => Promise<any>} fn - 보호할 비동기 함수(외부 호출).
+   * @param {MegaCircuitBreakerOptions} [options] - 브레이커 옵션.
+   * @throws {TypeError} `fn` 이 함수가 아니면.
+   */
+  constructor(fn, options = {}) {
+    if (typeof fn !== 'function') {
+      // 잘못된 사용은 부팅 시점에 즉시 드러나게(추측 진행 금지).
+      throw new TypeError(
+        `MegaCircuitBreaker(fn, opts) — fn must be a function (the async call to protect). Got: ${typeof fn}.`,
+      )
+    }
+
+    const {
+      timeout = 10_000,
+      errorThresholdPercentage = 50,
+      resetTimeout = 30_000,
+      rollingCountTimeout = 10_000,
+      rollingCountBuckets = 10,
+      volumeThreshold = 0,
+      capacity,
+      errorFilter,
+      name,
+    } = options
+
+    // 디폴트를 명시 리터럴로 구성(opossum 정본값 1:1) — 버전 드리프트와 무관하게 동작 고정.
+    // 선택 옵션(capacity/errorFilter/name)은 있을 때만 실어 opossum 기본 동작을 유지한다.
+    /** @type {import('opossum').Options} */
+    const opts = {
+      timeout,
+      errorThresholdPercentage,
+      resetTimeout,
+      rollingCountTimeout,
+      rollingCountBuckets,
+      volumeThreshold,
+      // 빈 문자열(익명 화살표의 fn.name='')도 'anonymous' 로 대체 — `||` 가 falsy 전부 걸러냄.
+      // (`??` 는 null/undefined 만 걸러 '' 가 통과 → JSDoc 약속과 어긋남.)
+      name: name ?? (fn.name || 'anonymous'),
+      ...(typeof capacity === 'number' ? { capacity } : {}),
+      ...(typeof errorFilter === 'function' ? { errorFilter } : {}),
+    }
+
+    this.#breaker = new CircuitBreaker(fn, opts)
+  }
+
+  /**
+   * 보호된 함수를 호출한다. 회로가 closed/halfOpen 이면 원함수를 실행하고, open 이면 원함수를 건너뛰고
+   * 즉시 `EOPENBREAKER` 로 reject 한다(빠른 실패). 결과/에러는 **그대로 전파**(삼키지 않음).
+   *
+   * @param {...any} args - 원함수에 그대로 전달할 인자.
+   * @returns {Promise<any>} 원함수의 반환값. 거부/타임아웃/실패 시 reject(에러 `code` 로 분기).
+   */
+  fire(...args) {
+    return this.#breaker.fire(...args)
+  }
+
+  /**
+   * 회로가 열려 있거나 호출이 실패할 때 대신 실행할 폴백을 등록한다. 폴백이 있으면 `fire()` 는 에러로
+   * reject 하지 않고 폴백 반환값으로 resolve 한다(`fallback` 이벤트 발화).
+   *
+   * @param {(...args: any[]) => any} fn - 폴백 함수(동기/비동기 모두 허용). 원호출 인자를 그대로 받는다.
+   * @returns {this} 체이닝용.
+   */
+  fallback(fn) {
+    this.#breaker.fallback(fn)
+    return this
+  }
+
+  /**
+   * 이벤트명 화이트리스트 검증. 모든 구독/해제 메서드가 공유 — 오타 이벤트명을 조용히 무시하지
+   * 않고 즉시 RangeError 로 드러낸다(L-1: on/off 뿐 아니라 once/addListener/prepend* 도 동일 보호).
+   * @param {string} method - 호출된 메서드명(에러 메시지용).
+   * @param {string} event - 검증할 이벤트명.
+   * @returns {void}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  #assertKnownEvent(method, event) {
+    if (!KNOWN_EVENTS.includes(event)) {
+      throw new RangeError(
+        `MegaCircuitBreaker.${method}('${event}', ...) — unknown event. Known: ${KNOWN_EVENTS.join(', ')}.`,
+      )
+    }
+  }
+
+  /**
+   * 화이트리스트 검증 후 내부 opossum 브레이커(EventEmitter)로 위임한다. opossum 의 on/once 등은
+   * 이벤트별 오버로드라 유니온 event 가 단일 오버로드에 안 맞는다 — 런타임 화이트리스트로 이미
+   * 검증했으므로 베이스 EventEmitter 시그니처로 안전하게 상위 캐스트해 위임한다.
+   * @param {'on'|'off'|'once'|'addListener'|'removeListener'|'prependListener'|'prependOnceListener'} method
+   * @param {string} event @param {(...args: any[]) => void} listener @returns {this}
+   */
+  #delegateEvent(method, event, listener) {
+    this.#assertKnownEvent(method, event)
+    const emitter = /** @type {import('node:events').EventEmitter} */ (this.#breaker)
+    emitter[method](event, listener)
+    return this
+  }
+
+  /**
+   * 브레이커 이벤트를 구독한다(소비자가 분기점에 로그를 박는 지점). 알 수 없는 이벤트명은 오타로
+   * 보고 throw 한다(조용히 무시 금지).
+   *
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this} 체이닝용.
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  on(event, listener) {
+    return this.#delegateEvent('on', event, listener)
+  }
+
+  /**
+   * {@link MegaCircuitBreaker#on} 으로 등록한 리스너를 해제한다. 알 수 없는 이벤트명은 오타로 보고
+   * throw 한다 — `on()` 과 동일한 화이트리스트. 검증 없이 위임하면 오타 이벤트명이 조용히 매칭
+   * 실패해 "해제했다고 믿지만 리스너가 그대로 살아있는" 디버깅 지옥을 만든다. (`removeListener` 별칭도 보호.)
+   *
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this} 체이닝용.
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  off(event, listener) {
+    return this.#delegateEvent('off', event, listener)
+  }
+
+  /**
+   * 1회성 구독(EventEmitter `once`). on() 과 동일 화이트리스트(L-1).
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  once(event, listener) {
+    return this.#delegateEvent('once', event, listener)
+  }
+
+  /**
+   * `on` 의 EventEmitter 별칭. 우회로 화이트리스트를 비껴가지 않도록 동일 검증(L-1).
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  addListener(event, listener) {
+    return this.#delegateEvent('addListener', event, listener)
+  }
+
+  /**
+   * `off` 의 EventEmitter 별칭. 동일 화이트리스트 검증(L-1).
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  removeListener(event, listener) {
+    return this.#delegateEvent('removeListener', event, listener)
+  }
+
+  /**
+   * 리스너를 큐 앞에 추가(EventEmitter `prependListener`). 동일 화이트리스트 검증(L-1).
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  prependListener(event, listener) {
+    return this.#delegateEvent('prependListener', event, listener)
+  }
+
+  /**
+   * 1회성 리스너를 큐 앞에 추가(EventEmitter `prependOnceListener`). 동일 화이트리스트 검증(L-1).
+   * @param {'fire'|'success'|'failure'|'timeout'|'reject'|'open'|'halfOpen'|'close'|'fallback'|'semaphoreLocked'|'healthCheckFailed'|'shutdown'} event
+   * @param {(...args: any[]) => void} listener @returns {this}
+   * @throws {RangeError} 알 수 없는 이벤트명일 때.
+   */
+  prependOnceListener(event, listener) {
+    return this.#delegateEvent('prependOnceListener', event, listener)
+  }
+
+  /** 회로를 강제로 연다(차단). 테스트/운영 수동 개입용. */
+  open() {
+    this.#breaker.open()
+  }
+
+  /** 회로를 강제로 닫는다(정상 복귀). 카운터를 비우고 호출을 다시 흘려보낸다. */
+  close() {
+    this.#breaker.close()
+  }
+
+  /** 브레이커를 비활성화한다 — 회로 로직을 우회하고 원함수를 항상 그대로 호출. */
+  disable() {
+    this.#breaker.disable()
+  }
+
+  /** {@link MegaCircuitBreaker#disable} 를 되돌려 회로 로직을 다시 활성화한다. */
+  enable() {
+    this.#breaker.enable()
+  }
+
+  /**
+   * 브레이커를 영구 종료한다 — 내부 롤링 윈도우 타이머를 정리한다. **테스트/graceful shutdown 시 필수**
+   * (호출 안 하면 setInterval 타이머가 남아 프로세스/테스트 종료를 막는다).
+   */
+  shutdown() {
+    this.#breaker.shutdown()
+  }
+
+  /** @returns {boolean} 회로가 열려(차단) 있으면 true. */
+  get isOpen() {
+    return this.#breaker.opened
+  }
+
+  /** @returns {boolean} 회로가 닫혀(정상) 있으면 true. */
+  get isClosed() {
+    return this.#breaker.closed
+  }
+
+  /** @returns {boolean} 복구 프로빙(half-open) 중이면 true. */
+  get isHalfOpen() {
+    return this.#breaker.halfOpen
+  }
+
+  /** @returns {boolean} 브레이커가 활성(enable) 상태면 true. */
+  get isEnabled() {
+    return this.#breaker.enabled
+  }
+
+  /** @returns {boolean} 브레이커가 종료(shutdown)됐으면 true. */
+  get isShutdown() {
+    return this.#breaker.isShutdown
+  }
+
+  /** @returns {string} 브레이커 이름. */
+  get name() {
+    return this.#breaker.name
+  }
+
+  /**
+   * 통계 스냅샷을 평탄화해 반환한다(핵심 카운터만). 모니터링/디버그 로그용.
+   * @returns {MegaCircuitBreakerStats}
+   */
+  getStats() {
+    const s = this.#breaker.stats
+    // shutdown 은 opened/halfOpen/closed 와 별개 종단 상태라 먼저 판별(종료 후 state 정확화, L-2).
+    const state = this.#breaker.isShutdown
+      ? 'shutdown'
+      : this.#breaker.opened
+        ? 'open'
+        : this.#breaker.halfOpen
+          ? 'halfOpen'
+          : 'closed'
+    return {
+      name: this.#breaker.name,
+      state,
+      fires: s.fires,
+      successes: s.successes,
+      failures: s.failures,
+      timeouts: s.timeouts,
+      rejects: s.rejects,
+      fallbacks: s.fallbacks,
+    }
+  }
+
+  /**
+   * 내부 opossum 브레이커 raw 핸들(escape hatch). 여기서 노출하지 않은 opossum 고급 기능(캐시·
+   * coalesce·healthCheck·snapshot 등)이 필요할 때만 직접 접근한다. 어댑터의 `.native` 와 같은 취지.
+   * @returns {import('opossum')<any[], any>}
+   */
+  get raw() {
+    return this.#breaker
+  }
+}
+
+/**
+ * 외부 호출을 서킷 브레이커로 감싸 **재사용 가능한** 브레이커를 만든다(보호 함수 1개당 1 브레이커).
+ * `new MegaCircuitBreaker(fn, opts)` 의 함수형 별칭 — 다른 Mega* 유틸(`withRetry`)과 호출 모양 일관.
+ *
+ * @param {(...args: any[]) => Promise<any>} fn - 보호할 비동기 함수.
+ * @param {MegaCircuitBreakerOptions} [options] - 브레이커 옵션.
+ * @returns {MegaCircuitBreaker} 장수(long-lived) 브레이커. 이후 `.fire(...args)` 로 호출.
+ */
+export function wrap(fn, options = {}) {
+  return new MegaCircuitBreaker(fn, options)
+}