mega-framework 0.1.6 → 0.1.8

package/types/core/pipeline.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 미들웨어를 Fastify 가 async preHandler 로 인식하는 arity-2 래퍼로 감싸고, canonical ctx 를
+ * 3번째 인자로 주입한다 — 핸들러·글로벌 미들웨어와 동일한 `(req, reply, ctx)` 계약(ADR-134/184).
+ * ctx 는 **lazy 프록시**(ADR-214) — 미들웨어가 실제로 속성을 만질 때만 빌드되고, 요청당 캐싱이라
+ * 같은 요청의 모든 미들웨어·핸들러가 동일 ctx 객체를 공유한다.
+ *
+ * @param {Function} fn - `(req, reply, ctx?)` 미들웨어 (arity-2 도 하위 호환 — 3번째 인자 무시).
+ * @param {import('./mega-app.js').MegaApp | null} [app] - ctx 의 어댑터·서비스 접근자 출처(없으면 null).
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<any>}
+ */
+export function wrapPreHandler(fn: Function, app?: import("./mega-app.js").MegaApp | null): (req: import("fastify").FastifyRequest, reply: import("fastify").FastifyReply) => Promise<any>;
+/**
+ * transform 배열을 단일 preSerialization 함수로 합성한다 — 순차 await, 각 변환의 반환값이
+ * 다음 변환의 payload 가 된다(raw data 만 다룸 — envelope 는 이후 단계, ADR-091).
+ *
+ * @param {Function[]} transforms
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply, payload: any) => Promise<any>}
+ */
+export function composeTransform(transforms: Function[]): (req: import("fastify").FastifyRequest, reply: import("fastify").FastifyReply, payload: any) => Promise<any>;
+/**
+ * after 배열을 단일 onResponse 함수로 합성한다 — 응답 전송 후 side-effect 전용.
+ * 개별 after 의 throw 는 warn 로그 후 다음 after 로 진행(응답 영향 없음, ADR-091 / P4).
+ *
+ * @param {Function[]} afters
+ * @param {{ method: string, path: string }} route - warn 로그 식별용.
+ * @returns {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<void>}
+ */
+export function composeAfter(afters: Function[], { method, path }: {
+    method: string;
+    path: string;
+}): (req: import("fastify").FastifyRequest, reply: import("fastify").FastifyReply) => Promise<void>;
+/**
+ * @typedef {object} HttpPipeline
+ * @property {(req: import('fastify').FastifyRequest, reply: import('fastify').FastifyReply) => Promise<any>} handler -
+ *   canonical `(req, reply, ctx)` 주입이 적용된 Fastify 핸들러.
+ * @property {Function[]} [preHandler] - before 래퍼 배열 (before 없으면 생략).
+ * @property {Function} [preSerialization] - transform 합성 (transform 없으면 생략).
+ * @property {Function} [onResponse] - after 합성 (after 없으면 생략).
+ * @property {() => { method: string, path: string, before: string[], transform: string[], after: string[] }} describe -
+ *   체인 introspection — 단계별 미들웨어 이름 목록(익명은 `(anonymous)`).
+ */
+/**
+ * 라우트 1개의 HTTP 라이프사이클을 합성한다. Router._registerHttp 가 Fastify routeOpts 로 옮긴다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app - ctx 출처 (standalone Router 면 null).
+ * @param {string} args.method - HTTP 메서드 (소문자).
+ * @param {string} args.path - 라우트 경로.
+ * @param {Function} args.handler - 사용자 핸들러 (inline 또는 static method ref, ADR-074).
+ * @param {Function[]} [args.before]
+ * @param {Function[]} [args.transform]
+ * @param {Function[]} [args.after]
+ * @returns {HttpPipeline}
+ */
+export function buildHttpPipeline({ app, method, path, handler, before, transform, after }: {
+    app: import("./mega-app.js").MegaApp | null;
+    method: string;
+    path: string;
+    handler: Function;
+    before?: Function[];
+    transform?: Function[];
+    after?: Function[];
+}): HttpPipeline;
+export type HttpPipeline = {
+    /**
+     * -
+     * canonical `(req, reply, ctx)` 주입이 적용된 Fastify 핸들러.
+     */
+    handler: (req: import("fastify").FastifyRequest, reply: import("fastify").FastifyReply) => Promise<any>;
+    /**
+     * - before 래퍼 배열 (before 없으면 생략).
+     */
+    preHandler?: Function[];
+    /**
+     * - transform 합성 (transform 없으면 생략).
+     */
+    preSerialization?: Function;
+    /**
+     * - after 합성 (after 없으면 생략).
+     */
+    onResponse?: Function;
+    /**
+     * -
+     * 체인 introspection — 단계별 미들웨어 이름 목록(익명은 `(anonymous)`).
+     */
+    describe: () => {
+        method: string;
+        path: string;
+        before: string[];
+        transform: string[];
+        after: string[];
+    };
+};

package/types/core/router.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 라우트 등록 옵션 (router.http.*(path, handler, opts) / router.ws(path, Channel, opts)).
+ * @typedef {object} HttpRouteOpts
+ * @property {Function[]} [before] - preHandler 단계 미들웨어 (인증·rateLimit·검증).
+ * @property {Function[]} [transform] - preSerialization 이른 단계 변환 (HTTP 전용).
+ * @property {Function[]} [after] - onResponse 단계 side-effect (HTTP 전용).
+ * @property {Object} [schema] - Fastify schema (ADR-019).
+ * @property {{ tags?: string[], summary?: string, description?: string, deprecated?: boolean }} [openapi] -
+ *   OpenAPI 라우트 메타 (ADR-070/140). 라우트 schema 의 비검증 메타 필드로 병합돼 명세에 반영(openapi 옵트인 시).
+ */
+/** 라우트 등록 시 잘못된 형식 시 throw. */
+export class MegaRouteError extends MegaError {
+}
+/**
+ * Router 인스턴스 — MegaApp 부팅 시 각 라우트 파일마다 생성·전달.
+ *
+ * HTTP 핸들러 등록 + before/transform/after 미들웨어 wiring.
+ * WS 는 hub 통합 시 등록 시그니처만 보존, 실제 핸들러는 inline /
+ * Static method ref 패턴 지원.
+ */
+export class Router {
+    /**
+     * @param {Object} ctx
+     * @param {import('fastify').FastifyInstance} ctx.fastify - 등록 대상 Fastify
+     * @param {string} ctx.appName - 디버그·에러 메시지용 앱 이름
+     * @param {string} [ctx.sourceFile] - 라우트 파일 경로 (에러 메시지용)
+     * @param {import('./mega-app.js').MegaApp} [ctx.app] - 바인딩 앱. HTTP 핸들러 ctx 의 `db/cache/bus`
+     *   접근자(ADR-102) 출처. 미지정(standalone Router)이면 ctx 에 어댑터 접근자가 빠진다.
+     */
+    constructor(ctx: {
+        fastify: import("fastify").FastifyInstance;
+        appName: string;
+        sourceFile?: string;
+        app?: import("./mega-app.js").MegaApp;
+    });
+    _fastify: import("fastify").FastifyInstance<import("fastify").RawServerDefault, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>;
+    _appName: string;
+    _sourceFile: string;
+    /** @type {import('./mega-app.js').MegaApp | null} */
+    _app: import("./mega-app.js").MegaApp | null;
+    /** @type {Function[]} 파일 레벨 transform — 이 Router(=라우트 파일)로 이후 등록되는 라우트에 합성 (ADR-194). */
+    _fileTransforms: Function[];
+    /** @type {Function[]} 파일 레벨 after — 위와 동일 스코프 (ADR-194). */
+    _fileAfters: Function[];
+    http: Readonly<Record<string, (path: string, handler: Function, opts?: HttpRouteOpts) => void>>;
+    /**
+     * 바인딩된 MegaApp (standalone Router 면 null).
+     *
+     * 라우트 모듈(`export default (router) => {}`)이 앱 표면에 닿는 통로다 — 특히 WS `before(req)`
+     * upgrade 인증은 Fastify 밖이라 `req.session` 이 없어, `router.app.sessionStore` 로 세션 스토어를
+     * 얻어 {@link import('./session.js').readSession} 으로 신원을 확인한다(ADR-159).
+     *
+     * @returns {import('./mega-app.js').MegaApp | null}
+     */
+    get app(): import("./mega-app.js").MegaApp | null;
+    /**
+     * HTTP 프록시: router.http.get(...), router.http.post(...) 등 7개 메서드.
+     * @private
+     */
+    private _buildHttpProxy;
+    /**
+     * 실제 HTTP 라우트 등록 — Fastify route() + before/transform/after wiring.
+     * @param {string} method - HTTP 메서드 (소문자).
+     * @param {string} path - 라우트 경로.
+     * @param {Function} handler - 핸들러 (inline async fn 또는 static method ref).
+     * @param {HttpRouteOpts} opts
+     * @private
+     */
+    private _registerHttp;
+    /**
+     * WebSocket 라우트 등록 (실 upgrade wiring).
+     *
+     * `ChannelClass` 가 {@link MegaWebSocketController} 를 상속하는지 **부팅 시 검증** (ADR-089 fail-fast).
+     * 등록된 라우트는 `fastify._megaWsRoutes` 에 보관되고, MegaApp 이 listen 시점에 HTTP `'upgrade'`
+     * 이벤트에 연결한다 (core/ws-upgrade.js).
+     *
+     * WS 는 `before`(upgrade 인증) 만 지원한다 — `transform`/`after` 는 HTTP 전용 (ADR-074/091).
+     *
+     * `schemas` 는 **메시지 type 별 payload JSON Schema** 맵이다 (`{ [type]: jsonSchema }`, M2).
+     * 등록 시점에 AJV 로 사전 컴파일되며, 수신 메시지의 `type` 에 해당 스키마가 있으면 dispatch
+     * 직전에 `payload` 를 검증한다. 실패 시 `ws.invalid_payload` error envelope 응답(연결 유지) —
+     * HTTP AJV 매핑(ADR-090)과 동일한 fail-closed 정책. 스키마 없는 type 은 그대로 통과.
+     *
+     * @param {string} path - WS 경로 (= ASP namespace, 예: '/ws/chat').
+     * @param {Function} ChannelClass - MegaWebSocketController 를 상속한 채널 클래스.
+     * @param {{ before?: Function[], schemas?: Object, transform?: unknown, after?: unknown }} [opts]
+     *   - schemas: `{ [messageType]: JSONSchema }` — type 별 payload 스키마 (AJV 사전 컴파일됨).
+     * @throws {MegaRouteError} path/ChannelClass 형식 위반, 상속 위반, 또는 schemas 형식·컴파일 실패.
+     */
+    ws(path: string, ChannelClass: Function, opts?: {
+        before?: Function[];
+        schemas?: Object;
+        transform?: unknown;
+        after?: unknown;
+    }): void;
+    /**
+     * 파일 전체 적용 미들웨어 (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: Function, opts?: {
+        stage?: "before" | "transform" | "after";
+    }): void;
+    /**
+     * @param {unknown} arr - 검증 대상 (Function[] 기대).
+     * @param {string} name - 옵션 이름 (before/transform/after).
+     * @param {string} method - HTTP 메서드 또는 'ws'.
+     * @param {string} path - 라우트 경로.
+     * @returns {Function[]}
+     * @private
+     */
+    private _validateMiddlewareArray;
+}
+/**
+ * 라우트 등록 옵션 (router.http.*(path, handler, opts) / router.ws(path, Channel, opts)).
+ */
+export type HttpRouteOpts = {
+    /**
+     * - preHandler 단계 미들웨어 (인증·rateLimit·검증).
+     */
+    before?: Function[];
+    /**
+     * - preSerialization 이른 단계 변환 (HTTP 전용).
+     */
+    transform?: Function[];
+    /**
+     * - onResponse 단계 side-effect (HTTP 전용).
+     */
+    after?: Function[];
+    /**
+     * - Fastify schema (ADR-019).
+     */
+    schema?: Object;
+    /**
+     * -
+     * OpenAPI 라우트 메타 (ADR-070/140). 라우트 schema 의 비검증 메타 필드로 병합돼 명세에 반영(openapi 옵트인 시).
+     */
+    openapi?: {
+        tags?: string[];
+        summary?: string;
+        description?: string;
+        deprecated?: boolean;
+    };
+};
+import { MegaError } from '../errors/mega-error.js';

package/types/core/routes-loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 앱의 routes/ 폴더 전체 스캔 → 각 파일을 Router 와 함께 실행.
+ *
+ * @param {Object} opts
+ * @param {import('fastify').FastifyInstance} opts.fastify
+ * @param {string} opts.appName
+ * @param {string} opts.routesDir - apps/<name>/routes 절대 경로
+ * @param {import('./mega-app.js').MegaApp} [opts.app] - 바인딩 앱 (HTTP ctx 의 db/cache/bus 접근자 출처, ADR-102)
+ * @returns {Promise<{ filesLoaded: number, routes: Array<{file: string}> }>}
+ */
+export function loadRoutes({ fastify, appName, routesDir, app }: {
+    fastify: import("fastify").FastifyInstance;
+    appName: string;
+    routesDir: string;
+    app?: import("./mega-app.js").MegaApp;
+}): Promise<{
+    filesLoaded: number;
+    routes: Array<{
+        file: string;
+    }>;
+}>;

package/types/core/scope-registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * mega.config.js (Global) / apps/<name>/app.config.js (App + Shared-Reference) 의
+ * 키 분리 규약 (ADR-061). 알 수 없는 키 + 잘못된 스코프 → 부팅 throw.
+ *
+ * @module core/scope-registry
+ */
+/** mega.config.js 최상위에만 허용되는 키 */
+export const GLOBAL_ONLY_KEYS: readonly string[];
+/** apps/<name>/app.config.js 에만 허용되는 키 */
+export const APP_ONLY_KEYS: readonly string[];
+/** Shared-Reference 키 — 전역 services 의 키만 참조 가능 */
+export const SHARED_REFERENCE_KEYS: readonly string[];
+export const ALL_GLOBAL_KEYS: readonly string[];
+export const ALL_APP_KEYS: readonly string[];

package/types/core/security.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 보안 플러그인 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} SecuritySummary
+ * @property {boolean} helmet
+ * @property {boolean} cors
+ * @property {boolean} rateLimit
+ * @property {boolean} csrf
+ * @property {boolean} asp - HTTP ASP 등록 여부.
+ * @property {'redis'|'memory'|null} rateLimitStore - rate-limit 백엔드(미등록이면 null).
+ */
+/**
+ * Fastify 인스턴스에 보안 플러그인 4종 + ASP HTTP 를 자동 등록한다.
+ *
+ * ⚠️ **호출 순서** — 반드시 `/health` 라우트 등록 "이전"에 호출해야 한다. @fastify/rate-limit 은 onRoute
+ *   hook 으로 라우트별 제한을 붙이는데, onRoute 는 플러그인 등록 "이후" 라우트만 잡는다. health 보다 먼저
+ *   등록해야 health 의 `config.rateLimit: false` 면제가 실효한다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {string} opts.appName - 앱 이름(로그·에러 메시지용).
+ * @param {string[]} [opts.hosts] - 앱 도메인 목록(CSRF Origin 검증 allowlist, ADR-051).
+ * @param {Object|false} [opts.helmet] - fastify-helmet 옵션. false=미등록, undefined=디폴트 ON.
+ * @param {Object|false} [opts.cors] - fastify-cors 옵션. false=미등록, undefined=origin:false(교차출처 거부).
+ * @param {Object|false} [opts.rateLimit] - fastify-rate-limit 옵션. false=미등록, undefined=디폴트(1000/min, ADR-214).
+ * @param {Object|false} [opts.csrf] - fastify-csrf-protection 옵션. false=미등록, undefined=디폴트 ON.
+ * @param {{ masterSecret?: string, http?: { enabledPaths?: string[], driftMs?: number, headerSignal?: string, timestampHeader?: string, nonceCache?: any } }} [opts.asp] -
+ *   ASP 설정. `masterSecret` + `http.enabledPaths`(비어있지 않음)가 둘 다 있을 때만 HTTP ASP 등록.
+ * @param {(() => import('ioredis').Redis | null)} [opts.resolveRateStore] - rate-limit Redis 백엔드 해석기.
+ *   `caches.rate` 별명을 ioredis 인스턴스로 돌려주면 분산 카운팅(ADR-048), null 이면 in-memory 폴백.
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 길목 debug 로그(선택).
+ * @returns {SecuritySummary}
+ */
+export function registerSecurityPlugins(fastify: import("fastify").FastifyInstance, opts: {
+    appName: string;
+    hosts?: string[];
+    helmet?: Object | false;
+    cors?: Object | false;
+    rateLimit?: Object | false;
+    csrf?: Object | false;
+    asp?: {
+        masterSecret?: string;
+        http?: {
+            enabledPaths?: string[];
+            driftMs?: number;
+            headerSignal?: string;
+            timestampHeader?: string;
+            nonceCache?: any;
+        };
+    };
+    resolveRateStore?: (() => import("ioredis").Redis | null);
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): SecuritySummary;
+/** rate-limit 기본값 (IP 당 1000 req/min — ADR-048 의 100/min 은 평상 트래픽도 429 를 만드는 운영 함정이라 상향, ADR-214). 사용자 config 로 완전 교체(ADR-073). */
+export const DEFAULT_RATE_LIMIT: Readonly<{
+    max: 1000;
+    timeWindow: "1 minute";
+}>;
+/**
+ * 보안 플러그인 자동 등록 결과 요약(디버그·테스트용).
+ */
+export type SecuritySummary = {
+    helmet: boolean;
+    cors: boolean;
+    rateLimit: boolean;
+    csrf: boolean;
+    /**
+     * - HTTP ASP 등록 여부.
+     */
+    asp: boolean;
+    /**
+     * - rate-limit 백엔드(미등록이면 null).
+     */
+    rateLimitStore: "redis" | "memory" | null;
+};

package/types/core/services-loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 서비스 파일명 → DI 이름 도출. `-service` suffix 를 떼고 kebab→camelCase 한다
+ * (`user-service.js` → `user`, `audit-log-service.js` → `auditLog`, docs/03 §149 정본).
+ * suffix 가 없으면 파일명 stem 을 그대로 camelCase 한다(`user.js` → `user`).
+ *
+ * @param {string} fileName - `.js` 포함 파일명.
+ * @returns {string} ctx.services.<name> 키.
+ */
+export function serviceNameFromFile(fileName: string): string;
+/**
+ * 앱의 services/ 폴더 전체 스캔 → 각 파일의 default export(MegaService 서브클래스)를
+ * `name → Class` 레지스트리(Map)로 만든다. 부팅 시 1회 실행되며, 요청별 인스턴스화는
+ * `ctx.services` lazy proxy 가 이 레지스트리를 보고 수행한다(ADR-148).
+ *
+ * routes-loader 와 동일하게 flat readdir(하위 폴더 미스캔) + `.test.js` 제외 + 정렬한다.
+ * 폴더 부재(ENOENT)는 정상(서비스 없는 앱) — 빈 Map 반환.
+ *
+ * @param {Object} opts
+ * @param {string} opts.servicesDir - apps/<name>/services 절대 경로.
+ * @param {string} opts.appName - 앱 이름(에러 메시지용).
+ * @returns {Promise<Map<string, Function>>} name → 서비스 클래스.
+ * @throws {MegaConfigError} 로드 실패 / default export 없음 / MegaService 미상속 / 이름 중복.
+ */
+export function loadServices({ servicesDir, appName }: {
+    servicesDir: string;
+    appName: string;
+}): Promise<Map<string, Function>>;

package/types/core/session-cleanup-schedule.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 만료 세션 정리 `MegaSchedule` 서브클래스를 만든다.
+ *
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} store - 정리할 세션 스토어(연결됨).
+ * @param {object} [opts]
+ * @param {string} [opts.cron='0 * * * *'] - cron 표현식(기본 매시 정각).
+ * @param {string} [opts.timezone] - IANA 타임존.
+ * @param {import('../lib/mega-schedule.js').MegaScheduleLock} [opts.lock] - 분산 중복방지 락(멀티 인스턴스).
+ * @param {string} [opts.name='SessionCleanup'] - 스케줄 이름(MegaScheduler 등록 키).
+ * @returns {typeof MegaSchedule}
+ * @throws {Error} store 가 없거나 cleanup 메서드가 없을 때.
+ */
+export function createSessionCleanupSchedule(store: import("../adapters/mega-session-adapter.js").MegaSessionAdapter, opts?: {
+    cron?: string;
+    timezone?: string;
+    lock?: import("../lib/mega-schedule.js").MegaScheduleLock;
+    name?: string;
+}): typeof MegaSchedule;
+import { MegaSchedule } from '../lib/mega-schedule.js';

package/types/core/session-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 세션 스토어 어댑터를 만든다(connect 는 호출자 책임 — MegaApp 가 부팅 시 connect).
+ *
+ * @param {{ driver?: string, [k: string]: any }} storeConfig - `session.store` 설정.
+ *   `driver` ('file'|'redis') + driver 별 옵션(basePath / url / keyPrefix / ttlMs …).
+ * @param {{ ttlMs?: number }} [defaults] - 미들웨어가 주입하는 기본값(store 에 ttlMs 미지정 시 사용).
+ * @returns {import('../adapters/mega-session-adapter.js').MegaSessionAdapter}
+ * @throws {MegaConfigError} `session.invalid_store` - storeConfig 누락/형식 오류.
+ * @throws {MegaConfigError} `session.unknown_driver` - 미지원 driver.
+ */
+export function createSessionStore(storeConfig: {
+    driver?: string;
+    [k: string]: any;
+}, defaults?: {
+    ttlMs?: number;
+}): import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+/**
+ * file driver 만료 스캔 cleanup 기본 주기(1시간, ms) — ADR-046 의 "file 모드 cleanup 자동" 약속 구현(ADR-215).
+ * 어댑터 자체 디폴트는 0(off)이라, 팩토리 경유 생성(=프레임워크 부팅 경로)에서만 기본 주기를 주입한다.
+ * 만료 파일의 lazy 삭제는 같은 sid 재접근 시에만 일어나므로, 주기 스캔이 없으면 미접근 만료 세션이
+ * 디스크에 무한 누적된다(G5 audit M-3). `cleanupIntervalMs: 0` 명시로 옵트아웃(외부 cron/scheduler 운용 시).
+ */
+export const DEFAULT_FILE_CLEANUP_INTERVAL_MS: 3600000;
+/** 지원 세션 driver 목록(테스트·문서용). */
+export const SESSION_STORE_DRIVERS: readonly string[];

package/types/core/session.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ULID sid 생성 — 48-bit timestamp + 80-bit randomness = 26자 Crockford base32 (ADR-046).
+ * (ws-message 의 generateMessageId 는 "envelope 전용"이라 세션용 독립 helper 를 둔다. 정식 MegaIdGen 은 OQ-014.)
+ *
+ * @param {number} [timestamp] - epoch ms(테스트 주입용).
+ * @returns {string} 26자 ULID.
+ */
+export function generateSid(timestamp?: number): string;
+/**
+ * Fastify 인스턴스에 세션 미들웨어를 등록한다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} opts
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} opts.store - 연결된 세션 스토어.
+ * @param {string} opts.secret - 쿠키 HMAC 서명 시크릿(global `server.sessionSecret`).
+ * @param {number} [opts.ttlMs] - 세션 TTL(ms). 기본 24시간.
+ * @param {boolean} [opts.rolling] - rolling TTL(기본 true, ADR-046).
+ * @param {{ name?: string, path?: string, httpOnly?: boolean, secure?: boolean|'auto', sameSite?: string }} [opts.cookie]
+ * @param {string} [opts.driver] - 스토어 driver 명(트레이싱용; 미지정 시 store.getStats().driver).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger]
+ * @returns {void}
+ * @throws {Error} secret 누락 — 서명 불가(부팅 abort).
+ */
+export function registerSession(fastify: import("fastify").FastifyInstance, opts: {
+    store: import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+    secret: string;
+    ttlMs?: number;
+    rolling?: boolean;
+    cookie?: {
+        name?: string;
+        path?: string;
+        httpOnly?: boolean;
+        secure?: boolean | "auto";
+        sameSite?: string;
+    };
+    driver?: string;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): void;
+/**
+ * Fastify 요청 파이프라인 밖(raw `IncomingMessage`)에서 세션을 **읽기 전용**으로 복원한다.
+ *
+ * HTTP `'upgrade'` 핸드셰이크는 Fastify 의 onRequest 훅을 타지 않아 `req.session` 이 없다. 그래서
+ * WS 라우트의 `before(req)` 인증은 이 helper 로 세션 신원을 확인한다 — {@link registerSession} 의
+ * onRequest 가 하는 경로(쿠키 → unsign → `store.load`)를 그대로 재사용하되, rolling touch·쿠키 발급·
+ * 변경 저장은 하지 않는다(upgrade 응답엔 set-cookie 를 실을 수 없고, 읽기만 필요하므로).
+ *
+ * 보안상 동일 규칙을 따른다: 쿠키가 없거나 서명 위조면 `null`(익명), 스토어에 없으면(만료/삭제) `null`.
+ * 절대 silent 하게 통과시키지 않는다(fail-closed) — 신원이 없으면 `before` 가 401 로 거부한다.
+ *
+ * @param {{ headers?: Record<string, any> }} req - raw `IncomingMessage`(또는 `headers.cookie` 를 가진 객체).
+ * @param {object} opts
+ * @param {import('../adapters/mega-session-adapter.js').MegaSessionAdapter} opts.store - 연결된 세션 스토어(`app.sessionStore`).
+ * @param {string} opts.secret - 쿠키 HMAC 서명 시크릿(global `server.sessionSecret`).
+ * @param {string} [opts.cookieName] - 세션 쿠키 이름(기본 `'mega.sid'` — {@link registerSession} 디폴트와 일치).
+ * @returns {Promise<{ sid: string, data: Record<string, any> } | null>} 유효 세션이면 `{ sid, data }`, 아니면 `null`.
+ * @throws {Error} `secret`/`store` 누락 — 서명 검증·로드가 불가하므로 fail-fast(silent 진행 금지).
+ * @example
+ *   // WS before 인증 — 로그인한 세션만 upgrade 허용
+ *   async function wsRequireAuth(req) {
+ *     const sess = await readSession(req, { store: app.sessionStore, secret })
+ *     if (sess?.data.userId == null) return false // 401
+ *     return { userId: String(sess.data.userId), sessionId: sess.sid } // ctx.auth
+ *   }
+ */
+export function readSession(req: {
+    headers?: Record<string, any>;
+}, { store, secret, cookieName }?: {
+    store: import("../adapters/mega-session-adapter.js").MegaSessionAdapter;
+    secret: string;
+    cookieName?: string;
+}): Promise<{
+    sid: string;
+    data: Record<string, any>;
+} | null>;

package/types/core/static-assets.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 정적 자산 자동 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} StaticAssetsSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string|null} root - 서빙 루트 절대경로(미등록 시 null).
+ * @property {string} prefix - URL prefix.
+ */
+/**
+ * `staticAssets` config 를 **순수 정규화**한다(파일시스템 접근 없음 — dir 실존 검사는 register 가 담당).
+ *
+ * - falsy / `enabled !== true` → `null`(미옵트인).
+ * - 그 외 → `{ dir, prefix, cacheControlHeader, dotfiles }`(prefix 디폴트 `/static`).
+ *
+ * `cacheControl`(정본: 문자열 = `Cache-Control` 헤더값, 예 `'public, max-age=3600'`)은 `cacheControlHeader`
+ * 로 전달. `dotfiles`(디폴트 false=차단)는 `'allow'`/`'deny'` 로 변환.
+ *
+ * @param {unknown} staticAssets - `MegaStaticAssetsAppConfig`.
+ * @returns {{ dir: string, prefix: string, cacheControlHeader: string|null, dotfiles: 'allow'|'ignore' } | null}
+ */
+export function normalizeStaticAssets(staticAssets: unknown): {
+    dir: string;
+    prefix: string;
+    cacheControlHeader: string | null;
+    dotfiles: "allow" | "ignore";
+} | null;
+/**
+ * Fastify 인스턴스에 `@fastify/static` 을 옵트인 등록한다.
+ *
+ * `staticAssets.enabled !== true` 면 **미등록**(정적 라우트 없음). 보안 플러그인·템플릿 등록 이후·`/health`
+ * 등록 이전에 호출한다(라우트 등록이므로 보안 onRoute hook 뒤여야 면제/제한이 일관). 멀티앱은 각자 Fastify
+ * 인스턴스라 prefix 충돌 없음.
+ *
+ * `enabled:true` 인데 `dir` 누락/미존재면 — 프로덕션 부팅 throw(`config.static_dir_not_found`), dev warn+skip
+ * (ADR-071, 04-data-models §3 검증표). `@fastify/static` 자체도 root 미존재 시 throw 하지만, dev 에선 warn 후
+ * 건너뛰어 잘못된 dir 하나로 앱 전체가 죽지 않게 한다.
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.staticAssets - `MegaStaticAssetsAppConfig`. `enabled:true` + 실존 `dir` 일 때만 등록.
+ * @param {string} [opts.appName] - 앱 이름(로그용).
+ * @param {boolean} [opts.isProduction] - 프로덕션 여부. 미지정 시 `NODE_ENV==='production'`.
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug/warn 로그(선택).
+ * @returns {StaticAssetsSummary}
+ * @throws {MegaConfigError} 프로덕션에서 `enabled:true` + `dir` 누락/미존재.
+ */
+export function registerStaticAssets(fastify: import("fastify").FastifyInstance, { staticAssets, appName, isProduction, logger }?: {
+    staticAssets: unknown;
+    appName?: string;
+    isProduction?: boolean;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): StaticAssetsSummary;
+/** 정적 자산 prefix 디폴트 (04-data-models §2 정본). */
+export const DEFAULT_STATIC_PREFIX: "/static";
+/**
+ * 정적 자산 자동 등록 결과 요약(디버그·테스트용).
+ */
+export type StaticAssetsSummary = {
+    /**
+     * - 등록 여부.
+     */
+    enabled: boolean;
+    /**
+     * - 서빙 루트 절대경로(미등록 시 null).
+     */
+    root: string | null;
+    /**
+     * - URL prefix.
+     */
+    prefix: string;
+};