mega-framework 0.1.0

package/src/eslint-plugin/no-direct-model-import.js

@@ -0,0 +1,113 @@
+// @ts-check
+
+/**
+ * ESLint rule: mega/no-direct-model-import
+ *
+ * ADR-022 절대 룰 강제. 라우트·컨트롤러는 모델을 직접 import 할 수 없다.
+ * 항상 서비스(MegaService) 경유.
+ *
+ * 적용 대상: 파일 경로가 `apps/<any>/routes/**` 또는 `apps/<any>/controllers/**`.
+ * 금지 패턴:
+ *   - 상대 경로 import 가 `models/` 디렉토리로 해석되는 경우 (`../models/user.js`,
+ *     `../../models/posts/comment.js` 등)
+ *   - 절대 경로 import 가 `apps/<any>/models/` 또는 `shared/models/` 를 포함하는 경우
+ *
+ * 위반 시 error.
+ *
+ * 사용 예 (eslint.config.js):
+ *   import megaPlugin from './src/eslint-plugin/index.js'
+ *   export default [
+ *     ...
+ *     { plugins: { mega: megaPlugin }, rules: { 'mega/no-direct-model-import': 'error' } },
+ *   ]
+ */
+
+/**
+ * 파일 경로가 routes 또는 controllers 인지 검사.
+ * @param {string | null | undefined} filename
+ * @returns {boolean}
+ */
+function isControllerOrRouteFile(filename) {
+  if (!filename) return false
+  // posix·win 모두 지원 — 경로 구분자 정규화
+  const norm = filename.replace(/\\/g, '/')
+  return /\/apps\/[^/]+\/(routes|controllers)\//.test(norm)
+}
+
+/**
+ * import 경로가 models 폴더를 가리키는지 검사.
+ * @param {unknown} importSource - AST literal 값 (string 이 아니면 false).
+ * @returns {boolean}
+ */
+function looksLikeModelImport(importSource) {
+  if (typeof importSource !== 'string') return false
+  const norm = importSource.replace(/\\/g, '/')
+  // 상대: ../models/, ../../models/, ./models/ 등
+  if (/(?:^|\/)\.\.?\/(?:[^/]+\/)*models(?:\/|$)/.test(norm)) return true
+  // 절대 또는 alias: apps/<name>/models/, shared/models/
+  if (/(?:^|\/)apps\/[^/]+\/models(?:\/|$)/.test(norm)) return true
+  if (/(?:^|\/)shared\/models(?:\/|$)/.test(norm)) return true
+  return false
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'apps/*/routes/** 와 apps/*/controllers/** 에서 models 직접 import 금지 (ADR-022)',
+    },
+    schema: [],
+    messages: {
+      direct: `라우트/컨트롤러는 모델을 직접 import 할 수 없습니다 — 서비스 경유 필수 (ADR-022). 위반 import: '{{source}}'`,
+    },
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename?.() ?? ''
+    if (!isControllerOrRouteFile(filename)) return {}
+
+    /**
+     * @param {import('eslint').Rule.Node} node - 보고 대상 AST 노드.
+     * @param {unknown} sourceValue - import 소스 리터럴 값.
+     */
+    function checkImport(node, sourceValue) {
+      if (looksLikeModelImport(sourceValue)) {
+        context.report({
+          node,
+          messageId: 'direct',
+          data: { source: sourceValue },
+        })
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        checkImport(node, node.source?.value)
+      },
+      // CommonJS 호환 — require('...')
+      CallExpression(node) {
+        if (
+          node.callee &&
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'require' &&
+          node.arguments.length === 1 &&
+          node.arguments[0].type === 'Literal' &&
+          typeof node.arguments[0].value === 'string'
+        ) {
+          checkImport(node, node.arguments[0].value)
+        }
+      },
+      // dynamic import('...')
+      ImportExpression(node) {
+        if (node.source && node.source.type === 'Literal' && typeof node.source.value === 'string') {
+          checkImport(node, node.source.value)
+        }
+      },
+    }
+  },
+}
+
+export default rule
+export { isControllerOrRouteFile, looksLikeModelImport }

package/src/index.js

@@ -0,0 +1,131 @@
+// MEGA-FRAMEWORK — 공개 entry point
+export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes } from './core/index.js'
+// 중앙 부팅 orchestrator + CLI (ADR-123)
+export { bootApp, buildBootContext } from './core/index.js'
+export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from './cli/index.js'
+export { MegaService } from './core/index.js'
+export { MegaCluster } from './core/index.js'
+export { wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError } from './core/index.js'
+// WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)
+export {
+  MegaWebSocketController,
+  createWsMessage,
+  validateWsMessage,
+  parseWsMessage,
+  generateMessageId,
+  WS_MESSAGE_SCHEMA,
+  WS_PROTOCOL_VERSION,
+  WS_TYPE_PATTERN,
+} from './core/index.js'
+export { MegaError } from './errors/mega-error.js'
+export { MegaConfigError } from './errors/config-error.js'
+export { MegaRouteError } from './core/router.js'
+export {
+  MegaHttpError,
+  MegaValidationError,
+  MegaAuthError,
+  MegaForbiddenError,
+  MegaNotFoundError,
+  MegaConflictError,
+  MegaInternalError,
+} from './errors/http-errors.js'
+export * as MegaHealth from './lib/mega-health.js'
+export { MegaShutdown } from './lib/mega-shutdown.js'
+// pino + multi-sink 로거 (ADR-023/141)
+export { buildLogger, buildLoggerOptions, buildTargets } from './lib/mega-logger.js'
+// 재시도 백오프 유틸 (p-retry 래퍼, ADR-029/098)
+export { MegaRetry, withRetry, RetryAbortError } from './lib/mega-retry.js'
+// 서킷 브레이커 — 외부 호출 보호 (opossum 래퍼, ADR-029/117)
+export {
+  MegaCircuitBreaker,
+  wrap as wrapCircuitBreaker,
+  OPEN_CIRCUIT_ERROR_CODE,
+  TIMEOUT_ERROR_CODE,
+  CAPACITY_ERROR_CODE,
+} from './lib/mega-circuit-breaker.js'
+// cron 파서 + cron 기반 스케줄러(분산 중복방지) (croner 래퍼, ADR-029/118)
+export { MegaCron } from './lib/mega-cron.js'
+export { MegaSchedule, MegaScheduler } from './lib/mega-schedule.js'
+// NATS JetStream 잡 큐 — 영속 큐 + 재시도 + DLQ (JetStream 래퍼, ADR-029/119)
+export { MegaJob, resolveJobRetryConfig, JOB_RETRY_DEFAULTS } from './lib/mega-job.js'
+export { MegaJobQueue } from './lib/mega-job-queue.js'
+// 잡 소비 워커 런타임 — 잡 등록 + bus 배선 + consume 라이프사이클 (ADR-120)
+export { MegaJobWorker } from './lib/mega-job-worker.js'
+// CPU 워커 풀(정본) — worker_threads/child_process 격리 + ctx.workers.<name>.run(task) (ADR-121/124)
+export { MegaWorker } from './lib/mega-worker.js'
+// 인증 보안 묶음 — 비밀번호 해싱(scrypt) + brute-force 차단 (ADR-049/050/130)
+export { MegaHash } from './lib/mega-hash.js'
+export { MegaBruteForce } from './lib/mega-brute-force.js'
+// 서버사이드 템플릿(정본) — EJS + ejs-mate 렌더 (ADR-011/136)
+export { MegaTemplate } from './core/template.js'
+// 정적 자산 옵트인 — @fastify/static (ADR-071/139)
+export { registerStaticAssets, normalizeStaticAssets } from './core/static-assets.js'
+// OpenAPI/Swagger 옵트인 — @fastify/swagger + swagger-ui (ADR-070/140)
+export { registerOpenapi, normalizeOpenapi } from './core/openapi.js'
+// 플러그인 시스템 — install(mega) 패턴 + apiVersion 호환 (ADR-079/122)
+export { MegaPluginHost, loadPlugins, CORE_API_VERSION } from './lib/mega-plugin.js'
+// .env → 어댑터 옵션 자동 매핑 (12-factor, ADR-109)
+export { buildAdapterEnvConfig } from './lib/env-mapper.js'
+// OpenTelemetry 분산 트레이싱 옵트인 (ADR-077 hook 위 자동 span, ADR-114)
+export * as MegaTracing from './lib/mega-tracing.js'
+// OpenTelemetry 메트릭 + Prometheus /metrics 옵트인 (ADR-072/131)
+export * as MegaMetrics from './lib/mega-metrics.js'
+// 클러스터 메트릭 집계 — 워커별 메트릭을 마스터 IPC 로 합산 (ADR-154/163)
+export { collectCluster, mergeExposition } from './core/cluster-metrics.js'
+
+// 데이터 어댑터 베이스 트리 + 드라이버 레지스트리 (ADR-027/044/045/077)
+export {
+  MegaAdapter,
+  MegaDbAdapter,
+  MegaCacheAdapter,
+  MegaBusAdapter,
+  MegaLockAdapter,
+  MegaLogSinkAdapter,
+  MegaSessionAdapter,
+  MegaAdapterRegistry,
+  BUILTIN_DRIVERS,
+  MegaAdapterManager,
+  MegaSqliteAdapter,
+  MegaPostgresAdapter,
+  MegaMariaAdapter,
+  MegaMongoAdapter,
+  MegaRedisAdapter,
+  MegaFileAdapter,
+  MegaNatsAdapter,
+  MegaRedlockAdapter,
+  MegaFileSessionAdapter,
+  MegaRedisSessionAdapter,
+} from './adapters/index.js'
+// 요청 ctx 의 db/cache/bus 함수형 lookup 배선 (ADR-102)
+export { buildHttpCtx, buildAdapterAccessors } from './core/index.js'
+
+// 데이터 모델 베이스 (ADR-008/009/010/081)
+export { MegaModel } from './models/index.js'
+
+// 보안 플러그인 자동 등록 — helmet/cors/rate-limit/csrf + ASP HTTP (ADR-127)
+export { registerSecurityPlugins, DEFAULT_RATE_LIMIT } from './core/security.js'
+// 세션 — 미들웨어 + 스토어 팩토리 + cleanup 스케줄 + 어댑터 (ADR-129/046)
+export { registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from './core/index.js'
+
+// ASP (Application Secure Protocol) — 서버측 HTTP/WS terminator (ADR-053 ~ ADR-060, ADR-094)
+export { registerAspPlugin } from './lib/asp/plugin.js'
+export { MegaAspTerminator } from './lib/asp/ws-terminator.js'
+export { MegaAspNonceCache, MegaMemoryNonceStore } from './lib/asp/nonce-cache.js'
+export { MegaAspDecryptError, ASP_RULES } from './lib/asp/errors.js'
+export { normalizeAspConfig } from './lib/asp/config.js'
+
+// Bridge ↔ Hub 12-타입 프로토콜 (ADR-033/059/097)
+export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from './cli/ws-hub.js'
+export { MegaHubLink } from './core/hub-link.js'
+// WS per-message deflate 압축 (ADR-078)
+export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from './core/ws-compression.js'
+export {
+  HUB_MESSAGE_TYPES,
+  HUB_TYPE_SET,
+  HUB_PAYLOAD_SCHEMAS,
+  HUB_CLOSE_CODES,
+  CLOSE_CODE_DRAIN,
+  validateHubMessage,
+  createHubMessage,
+  parseHubMessage,
+} from './lib/hub-protocol.js'

package/src/lib/asp/config.js

@@ -0,0 +1,83 @@
+// @ts-check
+/**
+ * ASP 설정 정규화 + fail-fast 검증 (ADR-056, ADR-057, ADR-058).
+ *
+ * 부팅 시 한 번 호출되어 다음을 강제한다 (roadmap Phase 1 검증 기준):
+ *   - `failOpen` 은 코어가 **강제로 false** 로 덮어쓴다 (사용자가 true 박아도 무시 + warn).
+ *   - `masterSecret` 누락 → throw (ADR-056).
+ *   - `nonceCache` 가 켜져 있으면 `cache`(또는 MegaAspNonceCache) 존재 검증.
+ *
+ * @module lib/asp/config
+ */
+import { MegaAspNonceCache } from './nonce-cache.js'
+
+/**
+ * @typedef {Object} NormalizedAspConfig
+ * @property {string} masterSecret
+ * @property {string[]} enabledPaths - glob 패턴 (예: '/api/*')
+ * @property {string} headerSignal - 암호화 시그널 헤더명 (디폴트 'X-Mega-Encrypted')
+ * @property {string} timestampHeader - 타임스탬프 헤더명 (디폴트 'X-Timestamp')
+ * @property {number} driftMs - 허용 timestamp drift (디폴트 60000)
+ * @property {false} failOpen - 항상 false (강제)
+ * @property {MegaAspNonceCache | null} nonceCache
+ */
+
+/**
+ * 원시 ASP config → 정규화 + 검증.
+ *
+ * @param {Record<string, any>} asp - { masterSecret, enabledPaths?, headerSignal?, timestampHeader?,
+ *   driftMs?, failOpen?, nonceCache? }
+ * @param {{ logger?: { warn: Function } }} [opts]
+ * @returns {NormalizedAspConfig}
+ * @throws {Error} masterSecret 누락 / nonceCache 잘못된 형태.
+ */
+export function normalizeAspConfig(asp, { logger } = {}) {
+  if (!asp || typeof asp !== 'object') {
+    throw new Error('ASP config must be an object (set asp in mega.config.js).')
+  }
+
+  // masterSecret 필수 (ADR-056) — 누락 시 fail-fast.
+  if (typeof asp.masterSecret !== 'string' || asp.masterSecret.length === 0) {
+    throw new Error(
+      'ASP config: masterSecret is required (ADR-056). Set asp.masterSecret in mega.config.js.',
+    )
+  }
+
+  // failOpen 강제 false (ADR-057). 사용자가 true 박았으면 무시 + warn.
+  if (asp.failOpen === true) {
+    const msg =
+      'asp.failOpen=true is ignored — core forces fail-closed (ADR-057). ' +
+      'Key mismatch always rejects; plaintext never passes.'
+    if (logger?.warn) logger.warn({ asp: 'failOpen', forced: false }, msg)
+    else console.warn(`[mega:asp] ${msg}`)
+  }
+
+  // nonceCache 검증 (ADR-058) — 켜져 있으면 cache 존재 필수.
+  let nonceCache = null
+  if (asp.nonceCache) {
+    if (asp.nonceCache instanceof MegaAspNonceCache) {
+      nonceCache = asp.nonceCache
+    } else if (asp.nonceCache.cache) {
+      nonceCache = new MegaAspNonceCache({
+        cache: asp.nonceCache.cache,
+        ttlSec: asp.nonceCache.ttlSec,
+      })
+    } else {
+      throw new Error(
+        'ASP config: nonceCache requires a `cache` with setIfNotExists(key, ttlSec) ' +
+          'or a MegaAspNonceCache instance (ADR-058).',
+      )
+    }
+  }
+
+  return {
+    masterSecret: asp.masterSecret,
+    enabledPaths: Array.isArray(asp.enabledPaths) ? asp.enabledPaths : [],
+    headerSignal: typeof asp.headerSignal === 'string' ? asp.headerSignal : 'X-Mega-Encrypted',
+    timestampHeader:
+      typeof asp.timestampHeader === 'string' ? asp.timestampHeader : 'X-Timestamp',
+    driftMs: typeof asp.driftMs === 'number' && asp.driftMs > 0 ? asp.driftMs : 60000,
+    failOpen: false, // 강제 (ADR-057)
+    nonceCache,
+  }
+}

package/src/lib/asp/crypto.js

@@ -0,0 +1,145 @@
+// MEGA ASP 알고리즘 JS mirror — Rust 정본(`packages/mega-client-wasm/src/crypto.rs`) 과 byte-level 호환.
+// zero-dep: node:crypto 만 사용. known-vector 양방향 단언 (ADR-060).
+
+import { createHmac, createCipheriv, createDecipheriv, randomBytes, createHash } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+
+const OBFUSCATE_SEED = 0x5a
+const AES_NONCE_LEN = 12
+const AES_TAG_LEN = 16
+
+/**
+ * SHA256(hex(HMAC-SHA256(masterSecret, "domain:path:uaSlice:timestamp"))) → 32 bytes Buffer.
+ */
+export function deriveKey(masterSecret, domain, path, uaSlice, timestamp) {
+  const seed = `${domain}:${path}:${uaSlice}:${timestamp}`
+  const mac = createHmac('sha256', masterSecret).update(seed).digest()
+  const hexKey = mac.toString('hex')
+  return createHash('sha256').update(hexKey).digest()  // Buffer length 32
+}
+
+/**
+ * timestamp mod UA 길이 위치에서 4 byte 순환 슬라이스. UA 비어 있으면 "0000".
+ * 비-ASCII byte 도 char.fromCharCode(byte) 로 매핑 — Rust char::from_u32(b as u32) 와 동일.
+ */
+export function getUaSlice(ua, timestamp) {
+  const uaBuf = Buffer.from(ua, 'utf8')
+  if (uaBuf.length === 0) return '0000'
+  const uaLen = uaBuf.length
+  const startIdx = Number(BigInt(timestamp) % BigInt(uaLen))
+  let out = ''
+  for (let i = 0; i < 4; i++) {
+    const b = uaBuf[(startIdx + i) % uaLen]
+    out += String.fromCharCode(b)
+  }
+  return out
+}
+
+/**
+ * 모든 byte 에 nibble-swap + XOR(0x5A) 적용. in-place.
+ */
+function obfuscateBytes(buf) {
+  for (let i = 0; i < buf.length; i++) {
+    const b = buf[i]
+    const swapped = ((b << 4) | (b >> 4)) & 0xff
+    buf[i] = swapped ^ OBFUSCATE_SEED
+  }
+}
+
+/**
+ * obfuscateBytes 의 역연산. byte-level 호환 위해 fuzionx 원본과 동일.
+ * XOR(0x5A) → nibble-swap (역순) 적용. in-place.
+ */
+function deobfuscateBytes(buf) {
+  for (let i = 0; i < buf.length; i++) {
+    const xored = (buf[i] ^ OBFUSCATE_SEED) & 0xff
+    buf[i] = ((xored << 4) | (xored >> 4)) & 0xff
+  }
+}
+
+/**
+ * AES-256-GCM 암호화 → nibble-swap → base64.
+ * @param {Buffer} key — 32 bytes
+ * @param {Buffer|string} plain
+ * @returns {string} base64
+ */
+export function encryptTransport(key, plain) {
+  const nonce = randomBytes(AES_NONCE_LEN)
+  const cipher = createCipheriv('aes-256-gcm', key, nonce)
+  const plainBuf = Buffer.isBuffer(plain) ? plain : Buffer.from(plain, 'utf8')
+  const ct = Buffer.concat([cipher.update(plainBuf), cipher.final()])
+  const tag = cipher.getAuthTag()
+  const combined = Buffer.concat([nonce, ct, tag])   // nonce || ciphertext || tag
+  obfuscateBytes(combined)
+  return combined.toString('base64')
+}
+
+/**
+ * base64 → deobfuscate → AES-256-GCM 복호화. Buffer 반환.
+ * @returns {Buffer}
+ * @throws Error
+ */
+export function decryptTransport(key, encryptedB64) {
+  let s = encryptedB64.trim()
+  while (s.length % 4 !== 0) s += '='
+  const combined = Buffer.from(s, 'base64')
+  if (combined.length < AES_NONCE_LEN + AES_TAG_LEN) {
+    throw new Error('encrypted blob too short')
+  }
+  deobfuscateBytes(combined)
+  const nonce = combined.subarray(0, AES_NONCE_LEN)
+  const tag = combined.subarray(combined.length - AES_TAG_LEN)
+  const ct = combined.subarray(AES_NONCE_LEN, combined.length - AES_TAG_LEN)
+  const decipher = createDecipheriv('aes-256-gcm', key, nonce)
+  decipher.setAuthTag(tag)
+  return Buffer.concat([decipher.update(ct), decipher.final()])
+}
+
+/**
+ * 암호문(base64)에서 AES-GCM nonce(앞 12 byte) 만 추출 — replay 방어용 (ADR-058).
+ *
+ * deobfuscate 후 앞 12 byte 가 nonce. **복호화하지 않고** nonce 만 뽑아 nonce_cache 의
+ * SETNX 키로 쓴다. GCM nonce 는 암호화마다 random 이라 동일 nonce 재등장 = replay.
+ *
+ * @param {string} encryptedB64 — encryptTransport 가 만든 base64 (URL-safe 아님 — STANDARD)
+ * @returns {Buffer} 12-byte nonce
+ * @throws {Error} blob 이 nonce+tag 보다 짧으면.
+ */
+export function extractNonce(encryptedB64) {
+  let s = encryptedB64.trim()
+  while (s.length % 4 !== 0) s += '='
+  const combined = Buffer.from(s, 'base64')
+  if (combined.length < AES_NONCE_LEN + AES_TAG_LEN) {
+    throw new Error('encrypted blob too short')
+  }
+  deobfuscateBytes(combined)
+  // subarray 는 같은 메모리 view — 복사본을 반환해 호출부가 안전하게 보관.
+  return Buffer.from(combined.subarray(0, AES_NONCE_LEN))
+}
+
+/**
+ * WS 프레임 암호화 — bare "<ts>:<base64>" 반환.
+ * P:/E: prefix 부착은 MegaAspTerminator 책임 (ADR-083).
+ */
+export function wsEncrypt(masterSecret, domain, path, ua, plain) {
+  const ts = Date.now()
+  const uaSlice = getUaSlice(ua, ts)
+  const key = deriveKey(masterSecret, domain, path, uaSlice, ts)
+  const enc = encryptTransport(key, plain)
+  return `${ts}:${enc}`
+}
+
+/**
+ * WS 프레임 복호화 — bare "<ts>:<base64>" 입력. 평문 string 반환.
+ */
+export function wsDecrypt(masterSecret, domain, path, ua, frame) {
+  const colonIdx = frame.indexOf(':')
+  if (colonIdx < 0) throw new Error("missing ':' in frame")
+  const tsStr = frame.slice(0, colonIdx)
+  const enc = frame.slice(colonIdx + 1)
+  const ts = Number(tsStr)
+  if (!Number.isFinite(ts) || ts < 0) throw new Error('invalid timestamp')
+  const uaSlice = getUaSlice(ua, ts)
+  const key = deriveKey(masterSecret, domain, path, uaSlice, ts)
+  return decryptTransport(key, enc).toString('utf8')
+}

package/src/lib/asp/errors.js

@@ -0,0 +1,49 @@
+// @ts-check
+/**
+ * ASP 에러 (ADR-025, ADR-053, ADR-058).
+ *
+ * MegaAspDecryptError 는 요청 복호화·검증 실패 시 던진다. 글로벌 에러 핸들러
+ * (error-mapper.js) 가 MegaHttpError 계층을 그대로 envelope 으로 변환하므로,
+ * 403 + code `asp.decrypt_failed` + details 배열(ADR-075) 이 자동으로 응답된다.
+ *
+ * @module lib/asp/errors
+ */
+import { MegaHttpError } from '../../errors/http-errors.js'
+
+/** ASP rule 종류 (envelope details 의 `rule` 필드). */
+export const ASP_RULES = Object.freeze({
+  KEY_MISMATCH: 'key_mismatch', // 복호화 실패 (auth tag 불일치 / 잘못된 키)
+  INVALID_PAYLOAD: 'invalid_payload', // ciphertext 깨짐 / 포맷 오류
+  DRIFT: 'drift', // timestamp 가 허용 윈도우(±driftMs) 밖
+  REPLAY: 'replay', // 동일 nonce 재사용 (nonce_cache, ADR-058)
+  MISSING_TIMESTAMP: 'missing_timestamp', // X-Timestamp 헤더 누락
+  SIGNAL_REQUIRED: 'signal_required', // ASP 활성 경로인데 암호화 시그널 없음 (fail-closed)
+})
+
+/**
+ * ASP 요청 복호화/검증 실패 — 403. fail-closed (ADR-057): 평문 통과 금지.
+ *
+ * `details` 는 배열 표준(ADR-075): `[{ field, rule, value? }]`. 여러 ASP 실패를
+ * 한 응답으로 표현 가능. 단일 실패도 1-원소 배열로 통일.
+ */
+export class MegaAspDecryptError extends MegaHttpError {
+  /**
+   * @param {string} rule - ASP_RULES 중 하나.
+   * @param {string} [message] - 사람이 읽는 메시지 (디버그용 — 시크릿 금지).
+   * @param {{ field?: string, value?: unknown, cause?: unknown }} [opts]
+   */
+  constructor(rule, message, opts = {}) {
+    super(403, 'asp.decrypt_failed', message ?? `ASP request rejected (${rule})`, {
+      details: [
+        {
+          field: opts.field ?? 'request',
+          rule,
+          ...(opts.value !== undefined ? { value: opts.value } : {}),
+        },
+      ],
+      cause: opts.cause,
+    })
+    /** @type {string} 실패 종류 (close code / 로깅 분기용). */
+    this.rule = rule
+  }
+}

package/src/lib/asp/nonce-cache.js

@@ -0,0 +1,94 @@
+// @ts-check
+/**
+ * ASP replay 방어 2단계 중 nonce 캐시 (ADR-058).
+ *
+ * AES-GCM 의 12-byte random nonce 를 cache 에 SETNX (set-if-not-exists) 한다.
+ * 동일 nonce 가 두 번째로 등장하면 replay → reject. timestamp drift(±60s) 와 결합해
+ * 윈도우 내 재전송까지 차단한다.
+ *
+ * cache 백엔드는 다음 계약만 만족하면 된다 (Redis SETNX 대응):
+ *   `async setIfNotExists(key: string, ttlSec: number): Promise<boolean>`
+ *     - 새로 set 했으면 `true`, 이미 존재하면 `false`.
+ *
+ * Redis 어댑터 도입 전이라 {@link MegaMemoryNonceStore} 를 기본 제공.
+ * 멀티 인스턴스 운영은 Redis 백엔드 권장 (in-memory 는 프로세스별 분리).
+ *
+ * @module lib/asp/nonce-cache
+ */
+
+/** nonce_cache 키 prefix (Redis 키 컨벤션, ADR-058). */
+const NONCE_KEY_PREFIX = 'asp:nonce:'
+
+/** 기본 TTL — drift 윈도우(±60s) 의 2배 (ADR-058: EX 120). */
+const DEFAULT_TTL_SEC = 120
+
+/**
+ * MegaAspNonceCache — nonce SETNX 래퍼.
+ */
+export class MegaAspNonceCache {
+  /**
+   * @param {Object} [opts]
+   * @param {{ setIfNotExists: (key: string, ttlSec: number) => Promise<boolean> }} [opts.cache] - 누락 시 throw.
+   * @param {number} [opts.ttlSec=120]
+   */
+  constructor({ cache, ttlSec = DEFAULT_TTL_SEC } = {}) {
+    if (!cache || typeof cache.setIfNotExists !== 'function') {
+      throw new Error(
+        'MegaAspNonceCache: `cache` with async setIfNotExists(key, ttlSec) is required (ADR-058).',
+      )
+    }
+    this._cache = cache
+    this._ttlSec = ttlSec
+  }
+
+  /**
+   * nonce 가 처음 등장하면 기록 후 true, 이미 봤으면(=replay) false.
+   *
+   * @param {string} nonceHex - {@link import('./crypto.js').extractNonce} 결과의 hex.
+   * @returns {Promise<boolean>} fresh 면 true, replay 면 false.
+   */
+  async isFresh(nonceHex) {
+    return this._cache.setIfNotExists(`${NONCE_KEY_PREFIX}${nonceHex}`, this._ttlSec)
+  }
+}
+
+/**
+ * 인메모리 nonce 저장소 — dev / 단일 인스턴스 / 테스트용.
+ *
+ * Map<key, 만료 epoch ms>. setIfNotExists 시 만료된 항목은 자동으로 덮어쓴다.
+ * 멀티 인스턴스에서는 프로세스별로 분리되므로 Redis 권장 (ADR-058).
+ */
+export class MegaMemoryNonceStore {
+  constructor() {
+    /** @type {Map<string, number>} key → 만료 epoch ms */
+    this._store = new Map()
+  }
+
+  /**
+   * @param {string} key
+   * @param {number} ttlSec
+   * @returns {Promise<boolean>} 새로 set 했으면 true, 유효한 기존 항목 있으면 false.
+   */
+  async setIfNotExists(key, ttlSec) {
+    const now = Date.now()
+    const exp = this._store.get(key)
+    if (exp !== undefined && exp > now) return false
+    this._store.set(key, now + ttlSec * 1000)
+    return true
+  }
+
+  /**
+   * 만료 항목 제거 (주기 cleanup 용 — 현재는 수동/테스트 호출).
+   * @param {number} [now=Date.now()]
+   */
+  evictExpired(now = Date.now()) {
+    for (const [k, exp] of this._store) {
+      if (exp <= now) this._store.delete(k)
+    }
+  }
+
+  /** 현재 저장된 항목 수 (테스트·디버그용). */
+  get size() {
+    return this._store.size
+  }
+}