mega-framework 0.1.6 → 0.1.7

package/types/errors/http-errors.d.ts

@@ -0,0 +1,120 @@
+/**
+ * HTTP 표준 status 와 envelope code 를 가진 베이스. 모든 HTTP 에러는 이걸 상속.
+ *
+ * envelope 변환 시 status → response status, code → error.code, message → error.message,
+ * details → error.details (object | array, ADR-075).
+ *
+ * 코드 컨벤션: `domain.error` (ADR-016). 예: 'user.not_found', 'auth.required'.
+ */
+export class MegaHttpError extends MegaError {
+    /**
+     * @param {number} status - HTTP status code (4xx/5xx).
+     * @param {string} code - 'domain.error' 형식 envelope 코드 (ADR-016).
+     * @param {string} message - 사람이 읽는 에러 메시지.
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     *   - details: 구조화된 부가 정보 (object | array — ADR-075).
+     *   - cause: 원인 에러 (전파용).
+     */
+    constructor(status: number, code: string, message: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+    status: number;
+}
+/** 400 — 클라이언트 검증 실패. AJV 자동 매핑 대상 (ADR-090). */
+export class MegaValidationError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 401 — 인증 누락 / 무효. */
+export class MegaAuthError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 403 — 인증은 했으나 권한 없음. */
+export class MegaForbiddenError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 404 — 리소스 없음. */
+export class MegaNotFoundError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 409 — 충돌 (예: email 중복). */
+export class MegaConflictError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 413 — 페이로드 과대 (업로드 크기·개수 초과). @fastify/multipart 네이티브 413 과 정합. */
+export class MegaPayloadTooLargeError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 415 — 지원하지 않는 미디어 타입 (업로드 MIME 화이트리스트 위반). */
+export class MegaUnsupportedMediaTypeError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+/** 500 — 내부 오류. 기본 code `server.internal` (H-6). */
+export class MegaInternalError extends MegaHttpError {
+    /**
+     * @param {string} [code]
+     * @param {string} [message]
+     * @param {{ details?: object | unknown[], cause?: unknown }} [opts]
+     */
+    constructor(code?: string, message?: string, opts?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+}
+import { MegaError } from './mega-error.js';

package/types/errors/index.d.ts

@@ -0,0 +1,3 @@
+export { MegaError } from "./mega-error.js";
+export { MegaConfigError } from "./config-error.js";
+export { MegaHttpError, MegaValidationError, MegaAuthError, MegaForbiddenError, MegaNotFoundError, MegaConflictError, MegaPayloadTooLargeError, MegaUnsupportedMediaTypeError, MegaInternalError } from "./http-errors.js";

package/types/errors/mega-error.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MEGA-FRAMEWORK 모든 에러의 베이스.
+ * - code: 'domain.error' 컨벤션 (ADR-016)
+ * - details: object | array (ADR-075)
+ * - cause: Error 전파
+ *
+ * @module errors/mega-error
+ */
+/**
+ * 프레임워크 공통 에러 베이스 클래스.
+ *
+ * @example
+ * throw new MegaError('user.not_found', 'User 42 not found', {
+ *   details: { userId: 42 },
+ * })
+ */
+export class MegaError extends Error {
+    /**
+     * @param {string} code - 'domain.error' 형식 에러 코드 (ADR-016).
+     * @param {string} message - 사람이 읽는 에러 메시지.
+     * @param {{ details?: object | unknown[], cause?: unknown }} [options]
+     *   - details: 구조화된 부가 정보 (object | array — ADR-075).
+     *   - cause: 원인 에러 (전파용).
+     */
+    constructor(code: string, message: string, { details, cause }?: {
+        details?: object | unknown[];
+        cause?: unknown;
+    });
+    code: string;
+    details: object;
+    cause: unknown;
+}

package/types/index.d.ts

@@ -0,0 +1,39 @@
+export { MegaError } from "./errors/mega-error.js";
+export { MegaConfigError } from "./errors/config-error.js";
+export { MegaRouteError } from "./core/router.js";
+export * as MegaHealth from "./lib/mega-health.js";
+export { MegaShutdown } from "./lib/mega-shutdown.js";
+export { MegaCron } from "./lib/mega-cron.js";
+export { MegaJobQueue } from "./lib/mega-job-queue.js";
+export { MegaJobWorker } from "./lib/mega-job-worker.js";
+export { MegaWorker } from "./lib/mega-worker.js";
+export { MegaHash } from "./lib/mega-hash.js";
+export { MegaBruteForce } from "./lib/mega-brute-force.js";
+export { MegaTemplate } from "./core/template.js";
+export { buildAdapterEnvConfig } from "./lib/env-mapper.js";
+export * as MegaTracing from "./lib/mega-tracing.js";
+export * as MegaMetrics from "./lib/mega-metrics.js";
+export { MegaModel } from "./models/index.js";
+export { registerAspPlugin } from "./lib/asp/plugin.js";
+export { MegaAspTerminator } from "./lib/asp/ws-terminator.js";
+export { normalizeAspConfig } from "./lib/asp/config.js";
+export { MegaHubLink } from "./core/hub-link.js";
+export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes, bootApp, buildBootContext, MegaService, MegaCluster, wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError, MegaWebSocketController, createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN, buildHttpCtx, buildAdapterAccessors, registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from "./core/index.js";
+export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from "./cli/index.js";
+export { MegaHttpError, MegaValidationError, MegaAuthError, MegaForbiddenError, MegaNotFoundError, MegaConflictError, MegaInternalError } from "./errors/http-errors.js";
+export { buildLogger, buildLoggerOptions, buildTargets } from "./lib/mega-logger.js";
+export { MegaRetry, withRetry, RetryAbortError } from "./lib/mega-retry.js";
+export { MegaCircuitBreaker, wrap as wrapCircuitBreaker, OPEN_CIRCUIT_ERROR_CODE, TIMEOUT_ERROR_CODE, CAPACITY_ERROR_CODE } from "./lib/mega-circuit-breaker.js";
+export { MegaSchedule, MegaScheduler } from "./lib/mega-schedule.js";
+export { MegaJob, resolveJobRetryConfig, JOB_RETRY_DEFAULTS } from "./lib/mega-job.js";
+export { registerStaticAssets, normalizeStaticAssets } from "./core/static-assets.js";
+export { registerOpenapi, normalizeOpenapi } from "./core/openapi.js";
+export { MegaPluginHost, loadPlugins, CORE_API_VERSION } from "./lib/mega-plugin.js";
+export { collectCluster, mergeExposition } from "./core/cluster-metrics.js";
+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";
+export { registerSecurityPlugins, DEFAULT_RATE_LIMIT } from "./core/security.js";
+export { MegaAspNonceCache, MegaMemoryNonceStore } from "./lib/asp/nonce-cache.js";
+export { MegaAspDecryptError, ASP_RULES } from "./lib/asp/errors.js";
+export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from "./lib/ws-hub.js";
+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/types/lib/asp/config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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: Record<string, any>, { logger }?: {
+    logger?: {
+        warn: Function;
+    };
+}): NormalizedAspConfig;
+export type NormalizedAspConfig = {
+    masterSecret: string;
+    /**
+     * - glob 패턴 (예: '/api/*')
+     */
+    enabledPaths: string[];
+    /**
+     * - 암호화 시그널 헤더명 (디폴트 'X-Mega-Encrypted')
+     */
+    headerSignal: string;
+    /**
+     * - 타임스탬프 헤더명 (디폴트 'X-Timestamp')
+     */
+    timestampHeader: string;
+    /**
+     * - 허용 timestamp drift (디폴트 60000)
+     */
+    driftMs: number;
+    /**
+     * - 항상 false (강제)
+     */
+    failOpen: false;
+    nonceCache: MegaAspNonceCache | null;
+};
+import { MegaAspNonceCache } from './nonce-cache.js';

package/types/lib/asp/crypto.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SHA256(hex(HMAC-SHA256(masterSecret, "domain:path:uaSlice:timestamp"))) → 32 bytes Buffer.
+ */
+export function deriveKey(masterSecret: any, domain: any, path: any, uaSlice: any, timestamp: any): NonSharedBuffer;
+/**
+ * timestamp mod UA 길이 위치에서 4 byte 순환 슬라이스. UA 비어 있으면 "0000".
+ * 비-ASCII byte 도 char.fromCharCode(byte) 로 매핑 — Rust char::from_u32(b as u32) 와 동일.
+ */
+export function getUaSlice(ua: any, timestamp: any): string;
+/**
+ * AES-256-GCM 암호화 → nibble-swap → base64.
+ * @param {Buffer} key — 32 bytes
+ * @param {Buffer|string} plain
+ * @returns {string} base64
+ */
+export function encryptTransport(key: Buffer, plain: Buffer | string): string;
+/**
+ * base64 → deobfuscate → AES-256-GCM 복호화. Buffer 반환.
+ * @returns {Buffer}
+ * @throws Error
+ */
+export function decryptTransport(key: any, encryptedB64: any): Buffer;
+/**
+ * 암호문(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: string): Buffer;
+/**
+ * WS 프레임 암호화 — bare "<ts>:<base64>" 반환.
+ * P:/E: prefix 부착은 MegaAspTerminator 책임 (ADR-083).
+ */
+export function wsEncrypt(masterSecret: any, domain: any, path: any, ua: any, plain: any): string;
+/**
+ * WS 프레임 복호화 — bare "<ts>:<base64>" 입력. 평문 string 반환.
+ */
+export function wsDecrypt(masterSecret: any, domain: any, path: any, ua: any, frame: any): string;
+import { Buffer } from 'node:buffer';

package/types/lib/asp/errors.d.ts

@@ -0,0 +1,30 @@
+/** ASP rule 종류 (envelope details 의 `rule` 필드). */
+export const ASP_RULES: Readonly<{
+    KEY_MISMATCH: "key_mismatch";
+    INVALID_PAYLOAD: "invalid_payload";
+    DRIFT: "drift";
+    REPLAY: "replay";
+    MISSING_TIMESTAMP: "missing_timestamp";
+    SIGNAL_REQUIRED: "signal_required";
+}>;
+/**
+ * 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: string, message?: string, opts?: {
+        field?: string;
+        value?: unknown;
+        cause?: unknown;
+    });
+    /** @type {string} 실패 종류 (close code / 로깅 분기용). */
+    rule: string;
+}
+import { MegaHttpError } from '../../errors/http-errors.js';

package/types/lib/asp/nonce-cache.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 }?: {
+        cache?: {
+            setIfNotExists: (key: string, ttlSec: number) => Promise<boolean>;
+        };
+        ttlSec?: number;
+    });
+    _cache: {
+        setIfNotExists: (key: string, ttlSec: number) => Promise<boolean>;
+    };
+    _ttlSec: number;
+    /**
+     * nonce 가 처음 등장하면 기록 후 true, 이미 봤으면(=replay) false.
+     *
+     * @param {string} nonceHex - {@link import('./crypto.js').extractNonce} 결과의 hex.
+     * @returns {Promise<boolean>} fresh 면 true, replay 면 false.
+     */
+    isFresh(nonceHex: string): Promise<boolean>;
+}
+/**
+ * 인메모리 nonce 저장소 — dev / 단일 인스턴스 / 테스트용.
+ *
+ * Map<key, 만료 epoch ms>. setIfNotExists 시 만료된 항목은 자동으로 덮어쓴다.
+ * 멀티 인스턴스에서는 프로세스별로 분리되므로 Redis 권장 (ADR-058).
+ */
+export class MegaMemoryNonceStore {
+    /** @type {Map<string, number>} key → 만료 epoch ms */
+    _store: Map<string, number>;
+    /** @type {number} 마지막 sweep 이후 insert 횟수 — SWEEP_EVERY_OPS 마다 만료 일괄 제거. */
+    _opsSinceSweep: number;
+    /**
+     * @param {string} key
+     * @param {number} ttlSec
+     * @returns {Promise<boolean>} 새로 set 했으면 true, 유효한 기존 항목 있으면 false.
+     */
+    setIfNotExists(key: string, ttlSec: number): Promise<boolean>;
+    /**
+     * 만료 항목 제거 (주기 cleanup 용 — 현재는 수동/테스트 호출).
+     * @param {number} [now=Date.now()]
+     */
+    evictExpired(now?: number): void;
+    /** 현재 저장된 항목 수 (테스트·디버그용). */
+    get size(): number;
+}

package/types/lib/asp/plugin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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: import("fastify").FastifyInstance, aspConfigRaw: Object, opts?: {
+    logger?: {
+        warn: Function;
+        debug?: Function;
+    };
+}): import("./config.js").NormalizedAspConfig;
+/**
+ * per-request ASP 상태. `req[ASP_STATE]` 에 보관 (Fastify 타입에 없는 symbol 키).
+ * `multipart` 는 body 평문 통과 마커(02-architecture §1625).
+ */
+export type AspState = {
+    intent: boolean;
+    ok: boolean;
+    ts: number;
+    key: Buffer;
+    multipart?: boolean;
+};

package/types/lib/asp/ws-terminator.d.ts

@@ -0,0 +1,45 @@
+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 }: {
+        masterSecret: string;
+        domain: string;
+        wsPath: string;
+        ua: string;
+        encrypt?: boolean;
+    });
+    _secret: string;
+    _domain: string;
+    _wsPath: string;
+    _ua: string;
+    _encrypt: boolean;
+    /** 이 terminator 가 기본 암호화 송신인지. */
+    get isEncrypted(): boolean;
+    /**
+     * 송신 프레임 생성. `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: Object | string, { plain }?: {
+        plain?: boolean;
+    }): string;
+    /**
+     * 수신 프레임 디코드. prefix 권위 (ADR-083). `E:` 복호화 실패 → throw (ADR-084).
+     *
+     * @param {string} frame - wire 프레임.
+     * @returns {{ encrypted: boolean, plain: string }} plain = 평문 JSON 문자열.
+     * @throws {MegaAspDecryptError} prefix 누락 / 복호화 실패.
+     */
+    decodeFrame(frame: string): {
+        encrypted: boolean;
+        plain: string;
+    };
+}

package/types/lib/env-mapper.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `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: string, env?: Record<string, string | undefined>, { driver }?: {
+    driver?: string;
+}): Record<string, any>;

package/types/lib/hub-protocol.d.ts

@@ -0,0 +1,106 @@
+/**
+ * bridge 가 REGISTER 로 보낸 최대 지원 버전과 hub 지원 버전의 상호 최고 버전을 고른다.
+ * 선형 누적 계약(vN 지원 = v1..vN 지원)이라 `min(bridgeMax, hubMax)` 가 항상 유효한 상호 버전이다
+ * (v1 이 바닥이라 협상이 실패할 수 없다 — 부재/무효 입력은 v1).
+ *
+ * @param {unknown} requestedMax - bridge 의 `protocolVersion`(최대 지원 버전).
+ * @param {ReadonlyArray<number>} [supported] - 이 측 지원 버전 목록.
+ * @returns {number} 협상된 버전(>= 1).
+ */
+export function negotiateHubProtocolVersion(requestedMax: unknown, supported?: ReadonlyArray<number>): number;
+/**
+ * hub 메시지 전체 검증 — envelope(§6.2) + type 소속(12 종) + payload/error 스키마.
+ *
+ * 던지지 않고 위반 사유 배열을 돌려준다(빈 배열 = 유효). 호출부(hub/link)가 사유를 그대로
+ * `hub.error` envelope 의 `details` 로 실어 보낼 수 있도록 한다(ADR-075 배열 표준).
+ *
+ * @param {any} msg - 파싱된 envelope 객체.
+ * @returns {string[]} 위반 사유 목록(없으면 빈 배열).
+ */
+export function validateHubMessage(msg: any): string[];
+/**
+ * hub 메시지 envelope 생성. {@link createWsMessage} 위임 — v/id/ts 자동.
+ * wire `type` 은 반드시 {@link HUB_MESSAGE_TYPES} 의 값(`hub.*`) 이어야 한다.
+ *
+ * @param {Object} fields
+ * @param {string} fields.type - wire type(`hub.*`). 12 종 아님 → throw.
+ * @param {string} [fields.ns]
+ * @param {Object} [fields.payload]
+ * @param {Object} [fields.error] - hub.error 의 §6.3 ErrorObject.
+ * @param {string} [fields.ref]
+ * @param {{ id?: string, ts?: number }} [opts] - 테스트 주입용.
+ * @returns {{ v: number, id: string, type: string, ts: number }}
+ * @throws {Error} type 이 12 종 hub 타입이 아님.
+ */
+export function createHubMessage(fields: {
+    type: string;
+    ns?: string;
+    payload?: Object;
+    error?: Object;
+    ref?: string;
+}, opts?: {
+    id?: string;
+    ts?: number;
+}): {
+    v: number;
+    id: string;
+    type: string;
+    ts: number;
+};
+/**
+ * JSON 문자열 → 검증된 hub 메시지 envelope. 파싱/검증 실패 시 throw(silent 금지).
+ *
+ * @param {string} json - hub link 평문 JSON.
+ * @returns {HubEnvelope} 검증 통과한 envelope.
+ * @throws {Error} JSON 파싱 실패 또는 hub 프로토콜 위반(메시지에 사유 포함).
+ */
+export function parseHubMessage(json: string): HubEnvelope;
+/**
+ * 논리명(04 §7 UPPERCASE) → wire `type`(`hub.<lower>`, ADR-097) 매핑.
+ * 키는 04-data-models §7 표의 타입명과 1:1. 값은 §6.2 패턴을 통과하는 소문자-점 형식.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const HUB_MESSAGE_TYPES: Readonly<Record<string, string>>;
+/** 12 개 wire `type` 문자열 집합 (빠른 소속 판별용). @type {ReadonlySet<string>} */
+export const HUB_TYPE_SET: ReadonlySet<string>;
+/** bridge↔hub 프로토콜 현 버전. REGISTER/REGISTER_OK 의 `protocolVersion` 협상 기준(부재 = v1). */
+export const HUB_PROTOCOL_VERSION: 1;
+/**
+ * 이 측이 지원하는 bridge↔hub 프로토콜 버전 목록. 버전은 선형 누적 계약 — vN 지원 = v1..vN 전부 지원.
+ * @type {ReadonlyArray<number>}
+ */
+export const SUPPORTED_HUB_PROTOCOL_VERSIONS: ReadonlyArray<number>;
+/**
+ * bridge↔hub WebSocket close code 카탈로그 (ADR-098).
+ *
+ * 클라↔bridge 의 close code(4500 decrypt / 1011 internal, {@link import('../core/ws-upgrade.js')})
+ * 와 **다른 평면**이다 — 이쪽은 bridge↔hub 전송계층(plaintext+Bearer, ADR-059) 전용.
+ *
+ * - `1001` GOING_AWAY — 일반 graceful shutdown(테스트/명시 stop). 재연결 의무 없음.
+ * - `1008` UNAUTHORIZED — REGISTER Bearer 불일치(RFC 6455 policy violation, ADR-097).
+ * - `4503` DRAIN — hub 가 의도적으로 비우는 중. bridge 는 **다른 hub 인스턴스로 재연결**해야 한다
+ *   (LB/mesh 회전). ADR-097 카탈로그가 예약했던 코드를 활성화.
+ * @type {Readonly<Record<string, number>>}
+ */
+export const HUB_CLOSE_CODES: Readonly<Record<string, number>>;
+/** hub drain close code(4503). bridge 가 이 코드를 받으면 재연결 대상으로 간주(ADR-098). */
+export const CLOSE_CODE_DRAIN: number;
+/**
+ * 타입별 payload JSON Schema (04-data-models §7 그대로). AJV 컴파일 대상.
+ * `hub.error` 는 payload 가 아니라 envelope `error` 로 검증하므로 여기엔 없다(아래 별도 처리).
+ * @type {Readonly<Record<string, Object>>}
+ */
+export const HUB_PAYLOAD_SCHEMAS: Readonly<Record<string, Object>>;
+/**
+ * hub 메시지 envelope (§6.2 + hub 타입). payload/error 는 타입별로 다르므로 any 로 둔다.
+ */
+export type HubEnvelope = {
+    v: number;
+    id: string;
+    type: string;
+    ts: number;
+    ns?: string;
+    payload?: any;
+    error?: any;
+    ref?: string;
+};

package/types/lib/index.d.ts

@@ -0,0 +1,22 @@
+export * as MegaHealth from "./mega-health.js";
+export { MegaShutdown } from "./mega-shutdown.js";
+export { MegaCron } from "./mega-cron.js";
+export { MegaJobQueue } from "./mega-job-queue.js";
+export { MegaJobWorker } from "./mega-job-worker.js";
+export { MegaWorker } from "./mega-worker.js";
+export { MegaHash } from "./mega-hash.js";
+export { MegaBruteForce } from "./mega-brute-force.js";
+export { buildAdapterEnvConfig } from "./env-mapper.js";
+export * as MegaTracing from "./mega-tracing.js";
+export * as MegaMetrics from "./mega-metrics.js";
+export * as MegaAspCrypto from "./asp/crypto.js";
+export { registerAspPlugin } from "./asp/plugin.js";
+export { MegaAspTerminator } from "./asp/ws-terminator.js";
+export { normalizeAspConfig } from "./asp/config.js";
+export { MegaRetry, withRetry, RetryAbortError } from "./mega-retry.js";
+export { MegaCircuitBreaker, wrap as wrapCircuitBreaker, OPEN_CIRCUIT_ERROR_CODE, TIMEOUT_ERROR_CODE, CAPACITY_ERROR_CODE } from "./mega-circuit-breaker.js";
+export { MegaSchedule, MegaScheduler } from "./mega-schedule.js";
+export { MegaJob, resolveJobRetryConfig, JOB_RETRY_DEFAULTS } from "./mega-job.js";
+export { MegaPluginHost, loadPlugins, CORE_API_VERSION } from "./mega-plugin.js";
+export { MegaAspNonceCache, MegaMemoryNonceStore } from "./asp/nonce-cache.js";
+export { MegaAspDecryptError, ASP_RULES } from "./asp/errors.js";