mega-framework 0.1.5 → 0.1.7

package/src/core/router.js

@@ -22,9 +22,10 @@
 // 명명 import — AJV 8 은 ESM/TS 정합을 위해 `Ajv` named export 를 제공한다(default 는 TS 에서
 // construct 불가로 잡힘). `ValidateFunction` 등 타입도 같은 모듈에서 가져온다.
 import { Ajv } from 'ajv'
+import ajvFormats from 'ajv-formats'
 import { MegaError } from '../errors/mega-error.js'
 import { MegaWebSocketController } from './ws-controller.js'
-import { getHttpCtx } from './ctx-builder.js'
+import { buildHttpPipeline, wrapPreHandler } from './pipeline.js'
 
 const HTTP_METHODS = Object.freeze(['get', 'post', 'put', 'patch', 'delete', 'head', 'options'])
 
@@ -35,6 +36,10 @@ const HTTP_METHODS = Object.freeze(['get', 'post', 'put', 'patch', 'delete', 'he
  * 우리 dispatch 경로에서 payload 만 검증하므로 직접 컴파일·실행한다.
  */
 const wsAjv = new Ajv({ allErrors: true })
+// HTTP 검증(Fastify 네이티브 @fastify/ajv-compiler)은 ajv-formats 가 배선돼 `format:'email'` 등이
+// 동작하는데, WS 쪽만 빠지면 같은 스키마가 WS 등록에서 부팅 throw 되는 비대칭이 생긴다(ADR-192).
+// CJS default 인터롭 — 런타임 default 는 플러그인 함수지만 TS(nodenext)가 모듈 객체로 봐 cast.
+;/** @type {(ajv: Ajv) => unknown} */ (/** @type {unknown} */ (ajvFormats))(wsAjv)
 
 /**
  * `router.ws({ schemas })` 의 type 별 JSON Schema 를 **등록(부팅) 시점에 사전 컴파일**한다
@@ -119,6 +124,10 @@ export class Router {
     this._sourceFile = ctx.sourceFile
     /** @type {import('./mega-app.js').MegaApp | null} */
     this._app = ctx.app ?? null
+    /** @type {Function[]} 파일 레벨 transform — 이 Router(=라우트 파일)로 이후 등록되는 라우트에 합성 (ADR-194). */
+    this._fileTransforms = []
+    /** @type {Function[]} 파일 레벨 after — 위와 동일 스코프 (ADR-194). */
+    this._fileAfters = []
     this.http = this._buildHttpProxy()
   }
 
@@ -176,22 +185,26 @@ export class Router {
     const transform = this._validateMiddlewareArray(opts.transform, 'transform', method, path)
     const after = this._validateMiddlewareArray(opts.after, 'after', method, path)
 
+    // before/transform/after 합성은 Pipeline 모듈이 정본이다 (ADR-185) — arity 흡수·ctx 주입·
+    // after 에러 정책을 한곳에서 보장하고, describe() 로 라우트별 체인을 introspection 한다.
+    // 파일 레벨 transform/after(router.use stage 옵션, ADR-194)를 라우트 슬롯 뒤에 합성 —
+    // ADR-021 순서(transform/after: 라우트 → 파일). 앱/전역 슬롯은 MegaApp onRoute 가 잇는다.
+    const pipeline = buildHttpPipeline({
+      app: this._app,
+      method,
+      path,
+      handler,
+      before,
+      transform: [...transform, ...this._fileTransforms],
+      after: [...after, ...this._fileAfters],
+    })
+
     // 동적으로 schema/preHandler/preSerialization/onResponse 를 덧붙이므로 permissive 타입.
     /** @type {Record<string, any>} */
     const routeOpts = {
       method: method.toUpperCase(),
       url: path,
-      handler: async (
-        /** @type {import('fastify').FastifyRequest} */ req,
-        /** @type {import('fastify').FastifyReply} */ reply,
-      ) => {
-        // canonical 핸들러 시그니처 (req, res, ctx) (ADR-074, docs/03 §581). ctx 는 요청 단위로 만들어
-        // app/log/requestId/req/reply + db/cache/bus 접근자(ADR-102)를 노출. 기존 (req, reply) 핸들러는
-        // 3번째 인자를 무시하므로 하위 호환. getHttpCtx 는 요청당 1회 캐싱이라 글로벌 미들웨어가 먼저
-        // 만든 ctx 를 그대로 이어받는다(ADR-134 — 미들웨어→핸들러 ctx 공유).
-        const ctx = getHttpCtx({ app: this._app, req, reply })
-        return handler(req, reply, ctx)
-      },
+      handler: pipeline.handler,
     }
 
     // schema (ADR-019) 그대로 Fastify 에 전달
@@ -209,55 +222,19 @@ export class Router {
       if (meta.deprecated === true) routeOpts.schema.deprecated = true
     }
 
-    // before — Fastify preHandler 체인. 각 미들웨어를 arity-2 async 래퍼로 감싼다.
-    //
-    // 왜 래핑하나: Fastify 는 async preHandler 의 arity 가 3 이상이면 3번째 인자를 콜백 `done` 으로
-    // 오해해 "Async function has too many arguments" 로 **등록을 거부**한다. 그런데 인증 가드
-    // `requireAuth`/`requireRole`(ADR-143)은 시그니처가 `(req, reply, ctx)` 로 arity 3 다 — 글로벌
-    // 미들웨어 경로(ADR-134)에서 ctx 를 받기 위함. 라우트 `before` 는 ctx 를 주입하지 않으므로(=undefined,
-    // 가드는 req.session 으로 동작) arity-2 래퍼 `(req, reply)` 로 감싸면 Fastify 계약에 맞으면서 ADR-143 이
-    // 문서화한 `{ before: [requireAuth] }` 가 실제로 동작한다. 래퍼는 각각 독립 preHandler 라 순서·reply
-    // 단락(앞 미들웨어가 응답 전송 시 이후 미들웨어·핸들러 skip) 의미는 그대로다(ADR-156).
-    if (before.length > 0) {
-      routeOpts.preHandler = before.map(
-        (fn) =>
-          /** @param {import('fastify').FastifyRequest} req @param {import('fastify').FastifyReply} reply */
-          async (req, reply) => fn(req, reply),
-      )
-    }
+    // before — preHandler / transform — preSerialization 이른 단계 / after — onResponse.
+    // 합성·arity 처리·에러 정책은 전부 Pipeline 산출물(ADR-091/156/185 — pipeline.js 가 정본).
+    if (pipeline.preHandler) routeOpts.preHandler = pipeline.preHandler
+    if (pipeline.preSerialization) routeOpts.preSerialization = pipeline.preSerialization
+    if (pipeline.onResponse) routeOpts.onResponse = pipeline.onResponse
 
-    // transform — preSerialization 이른 단계. Fastify preSerialization 훅의 payload 를 변환.
-    if (transform.length > 0) {
-      routeOpts.preSerialization = async (
-        /** @type {import('fastify').FastifyRequest} */ req,
-        /** @type {import('fastify').FastifyReply} */ reply,
-        /** @type {any} */ payload,
-      ) => {
-        let current = payload
-        for (const fn of transform) {
-          current = await fn(req, reply, current)
-        }
-        return current
-      }
-    }
-
-    // after — onResponse 단계 (응답 전송 후). throw 시 warn 로그 + 응답 영향 없음 (ADR-091).
-    if (after.length > 0) {
-      routeOpts.onResponse = async (
-        /** @type {import('fastify').FastifyRequest} */ req,
-        /** @type {import('fastify').FastifyReply} */ reply,
-      ) => {
-        for (const fn of after) {
-          try {
-            await fn(req, reply)
-          } catch (err) {
-            // ADR-091: silent fallback 금지 — warn 로그.
-            const log = req.log ?? console
-            log.warn?.({ err, hook: 'after', method, path }, `after middleware threw — ignored (response already sent)`)
-          }
-        }
-      }
-    }
+    // 라우트별 체인 introspection 보관 (ADR-185) — 디버그·CLI(`mega routes` 확장)용.
+    // _megaHttpPipelines 는 Fastify 타입에 없는 우리 전용 보관소 — 부착 시 cast.
+    const fastifyWithPipelines = /** @type {import('fastify').FastifyInstance & { _megaHttpPipelines?: Array<() => Object> }} */ (
+      this._fastify
+    )
+    if (!fastifyWithPipelines._megaHttpPipelines) fastifyWithPipelines._megaHttpPipelines = []
+    fastifyWithPipelines._megaHttpPipelines.push(pipeline.describe)
 
     // routeOpts 는 동적 조립(method 대문자화·옵션 키 추가)이라 RouteOptions 로 캐스팅해 전달.
     this._fastify.route(/** @type {import('fastify').RouteOptions} */ (routeOpts))
@@ -344,19 +321,47 @@ export class Router {
   }
 
   /**
-   * 파일 전체 적용 미들웨어 (router.use). fastify.addHook 으로 등록.
-   * 실행 순서: 전역 → 앱 → 파일(router.use) → 라우트(before opts) → handler.
+   * 파일 전체 적용 미들웨어 (router.use, ADR-194 — stage 3종).
+   *
+   * - `stage: 'before'`(디폴트) — fastify preHandler 훅 등록. 실행 순서: 전역 → 앱 → 파일(use)
+   *   → 라우트(before opts) → handler. 라우트 `before` 와 동일하게 arity-2 래퍼 + ctx 주입 —
+   *   raw 로 넘기면 arity-3 미들웨어(`requireAuth` 등 canonical `(req, reply, ctx)`)가 Fastify
+   *   async hook arity 검사(`FST_ERR_HOOK_INVALID_ASYNC_HANDLER`)에 걸려 부팅이 거부된다(ADR-156).
+   * - `stage: 'transform'` — 응답 raw data 변환 `(req, reply, payload) => payload`. 이 Router
+   *   (=라우트 파일)로 **이후 등록되는** 라우트의 transform 체인 뒤에 합성된다(라우트 → 파일,
+   *   ADR-021). envelope wrap 전 단계.
+   * - `stage: 'after'` — 응답 전송 후 side-effect `(req, reply)`. 동일 스코프로 after 체인 뒤에
+   *   합성(라우트 → 파일). throw 는 warn 로그 후 무시(ADR-091).
+   *
+   * 세 stage 모두 **호출 이후 등록되는 라우트**에만 적용된다 — 파일 상단(라우트 등록 전)에서
+   * 호출할 것.
+   *
    * @param {Function} middleware
+   * @param {{ stage?: 'before' | 'transform' | 'after' }} [opts]
    */
-  use(middleware) {
+  use(middleware, opts = {}) {
     if (typeof middleware !== 'function') {
       throw new MegaRouteError(
         'route.invalid_use',
         `router.use: middleware must be a function. Got: ${typeof middleware}.`,
       )
     }
-    // 사용자 제공 범용 미들웨어 — Fastify preHandler 훅 시그니처로 캐스팅.
-    this._fastify.addHook('preHandler', /** @type {any} */ (middleware))
+    const stage = opts.stage ?? 'before'
+    if (stage !== 'before' && stage !== 'transform' && stage !== 'after') {
+      throw new MegaRouteError(
+        'route.invalid_use_stage',
+        `router.use: opts.stage must be 'before' | 'transform' | 'after'. Got: '${String(stage)}'.`,
+      )
+    }
+    if (stage === 'transform') {
+      this._fileTransforms.push(middleware)
+      return
+    }
+    if (stage === 'after') {
+      this._fileAfters.push(middleware)
+      return
+    }
+    this._fastify.addHook('preHandler', wrapPreHandler(middleware, this._app))
   }
 
   /**

package/src/core/scope-registry.js

@@ -16,7 +16,6 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'apps', // 활성 앱 whitelist (ADR-066)
   'asp', // masterSecret 등 시크릿
   'health', // /health, /health/ready
-  'tracing', // OpenTelemetry (ADR-077)
   'plugins', // 명시 등록 배열 (ADR-079)
   'jobs', // MegaJob 서브클래스 배열 — mega worker 가 소비 (ADR-123)
   'schedules', // MegaSchedule 서브클래스 배열 — mega scheduler 가 소비 (ADR-123)

package/src/core/security.js

@@ -243,16 +243,39 @@ function registerCsrfGuard(fastify, { hosts, logger, appName }) {
       logger?.debug?.({ app: appName, origin: req.headers.origin ?? req.headers.referer }, 'security.csrf origin mismatch')
       throw new MegaForbiddenError(
         'csrf.origin_mismatch',
-        'CSRF: Origin header does not match an allowed host (ADR-051).',
+        'CSRF: Origin header does not match the request origin or an allowed host (scheme+host+port, ADR-051/186).',
         { details: { rule: 'origin_mismatch' } },
       )
     }
   })
 }
 
+/** 스킴별 기본 포트 — Origin/Host 의 생략 포트 정규화용(WHATWG URL 은 기본 포트를 빈 문자열로 돌려준다). */
+const DEFAULT_PORTS = Object.freeze({ 'http:': '80', 'https:': '443' })
+
 /**
- * CSRF Origin 검증(ADR-051) — Origin/Referer 의 hostname 이 요청 Host 또는 앱 도메인과 일치하는가.
- * Origin·Referer 둘 다 없으면(비브라우저 API 클라) 통과 — CSRF 는 브라우저 쿠키 공격이라 해당 없음.
+ * URL 의 실효 포트 — 명시 포트, 생략 시 스킴 기본 포트(http=80/https=443). 미지원 스킴은 빈 문자열.
+ * @param {URL} u @returns {string}
+ */
+function effectivePort(u) {
+  if (u.port !== '') return u.port
+  return DEFAULT_PORTS[/** @type {'http:'|'https:'} */ (u.protocol)] ?? ''
+}
+
+/**
+ * CSRF Origin 검증(ADR-051/186) — Origin/Referer 의 **출처(스킴+hostname+포트)** 가 요청 자신 또는
+ * 앱 도메인 allowlist 와 일치하는가. hostname 단독 비교는 http→https 강등 출처·포트 교차 출처를
+ * 통과시키므로(F5 audit S-1) 스킴·포트까지 본다(생략 포트는 스킴 기본 포트로 정규화).
+ *
+ * - Origin·Referer 둘 다 없으면(비브라우저 API 클라) 통과 — CSRF 는 브라우저 쿠키 공격이라 해당 없음.
+ * - 동일 출처: Origin 의 스킴이 `req.protocol`, hostname·포트가 Host 헤더와 일치해야 한다.
+ *   ⚠️ TLS 종료 프록시 뒤에서는 `server.trustProxy`(ADR-181)를 켜야 `req.protocol` 이 https 로
+ *   잡힌다 — 미설정 시 https Origin 이 거부된다(fail-closed: 오설정을 조용히 통과시키지 않음).
+ * - allowlist(`app.config.hosts`) 두 형태:
+ *   `'https://admin.example.com[:port]'`(스킴 포함) = 그 출처와 정확 일치.
+ *   `'admin.example.com[:port]'`(스킴 생략) = 요청과 같은 스킴만 허용, 포트 생략 = 그 스킴의 기본 포트.
+ *   (포트 불문 entry 는 두지 않는다 — 자기 도메인 entry 가 포트 검사를 무력화하는 구멍이 된다. 앱 자신의
+ *   출처는 Host 헤더가 포트를 포함하므로 위 동일 출처 검사가 비표준 포트도 커버한다.)
  *
  * @param {import('fastify').FastifyRequest} req
  * @param {string[]} hosts - 앱 도메인 allowlist(`app.config.hosts`).
@@ -261,15 +284,50 @@ function registerCsrfGuard(fastify, { hosts, logger, appName }) {
 function isOriginAllowed(req, hosts) {
   const raw = req.headers.origin ?? req.headers.referer
   if (!raw) return true // 비브라우저 클라 — Origin 없음.
-  let originHost
+  /** @type {URL} */
+  let origin
   try {
-    originHost = new URL(String(raw)).hostname
+    origin = new URL(String(raw))
   } catch {
     // 파싱 불가능한 Origin = 위조 의심 → 거부(묵시 무시 아님, 명시 거부).
     return false
   }
-  const reqHostname = String(req.headers.host ?? '').split(':')[0]
-  if (originHost === reqHostname) return true // 동일 출처.
-  // 앱 도메인 allowlist 와도 비교(host:port 형태면 hostname 만).
-  return hosts.some((h) => originHost === String(h).split(':')[0])
+  const reqProto = `${req.protocol}:`
+  const originPort = effectivePort(origin)
+
+  // 동일 출처 — 스킴·hostname·포트 전부 일치. Host 헤더가 없거나 호스트로 못 읽히면 동일 출처 판정을
+  // 건너뛰고 allowlist 로만 판단한다(통과 아님 — fail-closed 방향).
+  const hostHeader = String(req.headers.host ?? '')
+  if (hostHeader.length > 0) {
+    try {
+      const reqUrl = new URL(`${reqProto}//${hostHeader}`)
+      if (origin.protocol === reqProto && origin.hostname === reqUrl.hostname && originPort === effectivePort(reqUrl)) {
+        return true
+      }
+    } catch {
+      // 변조/형식오류 Host 헤더 — 동일 출처 비교 불가. 아래 allowlist 비교로 진행(매치 없으면 거부).
+    }
+  }
+
+  // 앱 도메인 allowlist.
+  for (const h of hosts) {
+    const entry = String(h)
+    try {
+      if (entry.includes('://')) {
+        // 스킴 포함 entry — 출처 정확 일치(교차 스킴 허용은 운영자가 명시적으로만).
+        const u = new URL(entry)
+        if (origin.protocol === u.protocol && origin.hostname === u.hostname && originPort === effectivePort(u)) return true
+      } else {
+        // 스킴 생략 entry — 요청 스킴 강제(https 앱에 http 출처 불허). 포트 생략 = 그 스킴의 기본 포트
+        // (포트 불문으로 두면 자기 도메인 entry 가 포트 검사를 무력화한다 — 비표준 포트는 entry 에 명시).
+        if (origin.protocol !== reqProto) continue
+        const u = new URL(`${reqProto}//${entry}`)
+        if (origin.hostname === u.hostname && originPort === effectivePort(u)) return true
+      }
+    } catch {
+      // 형식 오류 entry 는 "매치 실패"로 간주하고 다음 entry 로 — 조용한 통과가 아니라 거부 방향(fail-closed).
+      continue
+    }
+  }
+  return false
 }

package/src/core/workers-manager.js

@@ -65,7 +65,8 @@ export function buildWorkers(globalConfig, { projectRoot, registerShutdownHook =
   }
   if (registerShutdownHook) {
     MegaShutdown.unregister(SHUTDOWN_HOOK)
-    MegaShutdown.register(SHUTDOWN_HOOK, async () => stopAll())
+    // 'workers' stage — 잡/앱 정리(워커를 쓸 수 있는 단계) 뒤·어댑터 disconnect 앞에 풀을 내린다.
+    MegaShutdown.register(SHUTDOWN_HOOK, async () => stopAll(), { stage: 'workers' })
   }
 }
 
@@ -132,6 +133,15 @@ export function list() {
   })
 }
 
+/**
+ * Proxy get 트랩이 throw 하면 안 되는 "암묵 조회" string 키 모음. `await`(then)·`JSON.stringify`(toJSON)·
+ * 문자열/원시값 변환(toString/valueOf)·inspect 류(constructor/inspect)가 일반 객체에 으레 조회하는 키라,
+ * 미등록 fail-fast 대상(오타)과 구분해 undefined 를 돌려준다. 같은 이름이 실제로 등록돼 있으면 그대로
+ * 해석한다. `then` 은 Symbol 이 아니라 **string 키**다 — Promise resolution 이 string 'then' 을 조회하므로
+ * 이 가드가 없으면 `await ctx.workers`/`await ctx.services` 가 not_registered 로 죽는다.
+ */
+export const PROXY_PROTOCOL_KEYS = new Set(['then', 'catch', 'finally', 'toJSON', 'toString', 'valueOf', 'constructor', 'inspect'])
+
 /**
  * `ctx.workers` 로 줄 객체 — `ctx.workers.<name>.run(task)`. 미등록 이름 접근은 fail-fast.
  * 동일 Proxy 를 boot ctx·요청 ctx 가 공유한다(워커는 글로벌 자원이라 요청·앱 무관).
@@ -144,6 +154,7 @@ export function contextProxy() {
       {
         get(_t, prop) {
           if (typeof prop !== 'string') return undefined
+          if (!has(prop) && PROXY_PROTOCOL_KEYS.has(prop)) return undefined // 암묵 조회 키 — throw 금지.
           return get(prop) // 미등록 → worker.not_registered throw.
         },
         has(_t, prop) {

package/src/core/ws-cluster.js

@@ -150,7 +150,10 @@ export class MegaWsCluster {
       this._heartbeatTimer.unref?.()
       this._sweepTimer.unref?.()
       // 신규 인스턴스 — 전원에게 즉시 heartbeat 요청(빠른 수렴) + 자기 현재 멤버 공지.
-      await this._publishRoster({ op: ROSTER_OP.SYNC_REQUEST }).catch(() => {})
+      // 실패는 비치명적(heartbeat 주기에 자연 수렴)이나 묵히지 않는다 — roster 수렴 지연 관측용.
+      await this._publishRoster({ op: ROSTER_OP.SYNC_REQUEST }).catch((err) =>
+        this._log?.warn?.({ err, app: this._appName }, 'ws-cluster roster sync_request publish failed'),
+      )
       await this._publishHeartbeat()
     }
 
@@ -249,11 +252,15 @@ export class MegaWsCluster {
     // graceful: 자기 멤버를 LEAVE 로 공지(crash 가 아닌 정상 종료라 즉시 정리되게).
     if (this._rosterDriver === 'nats' && this._localMembers.size > 0) {
       for (const sessionId of this._localMembers.keys()) {
-        await this._publishRoster({ op: ROSTER_OP.REMOVE, sessionId }).catch(() => {})
+        // 실패해도 종료는 계속(TTL sweep 이 정리) — 단 타 인스턴스에 stale presence 가 TTL 까지 남으므로 알린다.
+        await this._publishRoster({ op: ROSTER_OP.REMOVE, sessionId }).catch((err) =>
+          this._log?.warn?.({ err, app: this._appName, sessionId }, 'ws-cluster graceful leave publish failed (stale until TTL)'),
+        )
       }
     }
     for (const sub of this._subs) {
-      await sub.unsubscribe().catch(() => {})
+      // 종료 중 unsubscribe 실패는 비치명적(연결 자체가 곧 닫힘) — 묵히지 않고 debug 로 남긴다.
+      await sub.unsubscribe().catch((err) => this._log?.debug?.({ err, app: this._appName }, 'ws-cluster unsubscribe failed (stopping)'))
     }
     this._subs = []
     this._localMembers.clear()

package/src/core/ws-message.js

@@ -22,6 +22,47 @@ import { randomBytes } from 'node:crypto'
 /** 현 프로토콜 버전 (04-data-models §6.2 `v: { const: 1 }`). */
 export const WS_PROTOCOL_VERSION = 1
 
+/**
+ * 이 서버가 지원하는 WS envelope 프로토콜 버전 목록. 버전은 선형 누적 계약 — vN 지원 = v1..vN 전부
+ * 지원. 협상은 클라이언트 제안과의 **최고 상호 버전**을 채택한다(v2 도입 시 [1, 2] 로 확장).
+ * @type {ReadonlyArray<number>}
+ */
+export const SUPPORTED_WS_PROTOCOL_VERSIONS = Object.freeze([WS_PROTOCOL_VERSION])
+
+/** WS 버전 협상 subprotocol 토큰 형식 — `mega.v<양의 정수>` (예: 'mega.v1'). */
+export const WS_SUBPROTOCOL_PATTERN = /^mega\.v([1-9][0-9]*)$/
+
+/**
+ * Sec-WebSocket-Protocol 제안 목록에서 envelope 프로토콜 버전을 협상한다.
+ *
+ * 규칙 (구버전 클라/서버 혼합 롤링 배포 안전):
+ *   - `mega.v<N>` 토큰이 하나도 없으면 → **레거시 폴백 v1** (`{ version: 1, subprotocol: undefined }`)
+ *     — subprotocol 미사용 클라(현 WASM MegaSocket·브라우저 기본)는 전부 v1 로 취급한다.
+ *   - 상호 지원 버전이 있으면 최고 버전 채택 → `{ version: N, subprotocol: 'mega.v<N>' }`
+ *     (서버가 핸드셰이크 응답 `Sec-WebSocket-Protocol` 로 확정 통지 — 클라는 `WebSocket.protocol` 로 읽는다).
+ *   - `mega.v*` 를 제안했지만 상호 버전이 없으면(클라가 미래 버전만 지원) → `null`
+ *     — 호출부는 subprotocol 없이 수락한다(클라 입장에선 "서버가 내 버전을 못 함" = v1 폴백 신호.
+ *     v1 을 못 하는 클라이언트는 스스로 닫는다). 핸드셰이크를 거부하지 않아 하위호환이 절대 깨지지 않는다.
+ *
+ * @param {Iterable<string>} offered - 클라이언트가 제안한 subprotocol 토큰들(ws 는 Set 을 전달).
+ * @param {ReadonlyArray<number>} [supported] - 서버 지원 버전 목록.
+ * @returns {{ version: number, subprotocol: string | undefined } | null} 협상 결과, 상호 버전 없으면 null.
+ */
+export function negotiateWsProtocol(offered, supported = SUPPORTED_WS_PROTOCOL_VERSIONS) {
+  let sawMegaToken = false
+  let best = 0
+  for (const token of offered ?? []) {
+    const m = typeof token === 'string' ? WS_SUBPROTOCOL_PATTERN.exec(token) : null
+    if (!m) continue // mega.* 외 토큰(앱 자체 subprotocol 등)은 협상 대상이 아니다.
+    sawMegaToken = true
+    const version = Number(m[1])
+    if (supported.includes(version) && version > best) best = version
+  }
+  if (!sawMegaToken) return { version: WS_PROTOCOL_VERSION, subprotocol: undefined } // 레거시 v1 폴백.
+  if (best === 0) return null // mega.v* 제안은 있었으나 상호 버전 없음.
+  return { version: best, subprotocol: `mega.v${best}` }
+}
+
 /**
  * 메시지 `type` / `error.code` 패턴 — `domain.action[.result]` (ADR-016, §6.2/§6.3).
  * 점(`.`)이 최소 1개 강제 → 베이스 메서드명(`onMessage` 등, 점 없음) 과 절대 충돌하지 않음.
@@ -129,12 +170,14 @@ function isPlainObject(v) {
  * `details` 로 그대로 실어 보낼 수 있도록 (ADR-075 배열 표준).
  *
  * @param {any} msg
+ * @param {{ version?: number }} [opts] - `version` = 이 연결에서 협상된 envelope 버전
+ *   ({@link negotiateWsProtocol}). 미지정 시 v1 — 협상 없는 기존 호출부와 하위호환.
  * @returns {string[]} 위반 메시지 목록 (없으면 빈 배열).
  */
-export function validateWsMessage(msg) {
+export function validateWsMessage(msg, { version = WS_PROTOCOL_VERSION } = {}) {
   if (!isPlainObject(msg)) return ['message must be a non-null object']
   const errors = []
-  if (msg.v !== WS_PROTOCOL_VERSION) errors.push(`v must be ${WS_PROTOCOL_VERSION}`)
+  if (msg.v !== version) errors.push(`v must be ${version}`)
   if (typeof msg.id !== 'string') errors.push('id must be a string')
   if (typeof msg.type !== 'string' || !WS_TYPE_PATTERN.test(msg.type)) {
     errors.push(`type must match ${WS_TYPE_PATTERN.source}`)
@@ -154,10 +197,11 @@ export function validateWsMessage(msg) {
  * JSON 문자열 → 검증된 WS 메시지 envelope. 파싱/검증 실패 시 throw (silent 금지).
  *
  * @param {string} json - wire 평문 JSON (ASP 복호화 후 또는 `P:` 평문).
+ * @param {{ version?: number }} [opts] - 협상된 envelope 버전(미지정 시 v1, {@link validateWsMessage}).
  * @returns {Object} 검증 통과한 envelope.
  * @throws {Error} JSON 파싱 실패 또는 schema 위반 (메시지에 사유 포함).
  */
-export function parseWsMessage(json) {
+export function parseWsMessage(json, opts) {
   let obj
   try {
     obj = JSON.parse(json)
@@ -168,7 +212,7 @@ export function parseWsMessage(json) {
       { cause: err },
     )
   }
-  const errors = validateWsMessage(obj)
+  const errors = validateWsMessage(obj, opts)
   if (errors.length > 0) {
     throw new Error(`parseWsMessage: invalid WS message — ${errors.join('; ')}`)
   }