mega-framework 0.1.0

package/src/core/security.js

@@ -0,0 +1,275 @@
+// @ts-check
+/**
+ * MegaApp 보안 플러그인 자동 등록 — helmet / cors / rate-limit / csrf + ASP HTTP (ADR-127).
+ *
+ * 매 프로젝트에서 보안 플러그인을 수동 등록하면 잊기 쉽다(ADR-047). 본 모듈이 앱 생성 시점에 검증된
+ * 공개 Fastify 플러그인 4종 + 기존 ASP HTTP terminator 를 **앱 config 기반으로 자동 등록**한다.
+ *
+ * # 등록 대상 (ADR-047 ~ ADR-051)
+ *   - `@fastify/helmet`            — 보안 헤더(+CSP). 디폴트 ON.
+ *   - `@fastify/cors`              — CORS. 디폴트 ON 이되 `origin: false`(교차출처 거부) — 안전 디폴트.
+ *   - `@fastify/rate-limit`        — 요청 제한. 디폴트 ON, `100 req / 1 minute`(ADR-048). 멀티 인스턴스는
+ *                                    `caches.rate` 별명(Redis) 백엔드, 미선언 시 in-memory(단일 dev) 폴백.
+ *   - `@fastify/csrf-protection`   — CSRF. 디폴트 ON. `@fastify/cookie` 동반(쿠키 double-submit).
+ *                                    ADR-051: `application/json` 요청은 토큰 면제 + **Origin 헤더 검증**,
+ *                                    폼 요청(`urlencoded`/`multipart`)만 토큰 검증.
+ *   - ASP HTTP                     — `asp.masterSecret` + `asp.http.enabledPaths` 가 있을 때만 옵트인 등록
+ *                                    (기존 {@link registerAspPlugin}).
+ *
+ * # 설정 스코프 (ADR-061 / ADR-047)
+ *   보안 옵션은 `apps/<name>/app.config.js` 의 **top-level 키** `cors / helmet / rateLimit / csrf` 로 받는다
+ *   (`security: {}` 중첩 객체 아님 — scope-registry 의 App-only 키와 정합). 각 키는:
+ *   - `undefined` → 안전 디폴트로 자동 등록.
+ *   - `false`     → 해당 플러그인 비활성(미등록).
+ *   - `object`    → 옵션으로 등록. **라우트 옵션 오버라이드는 완전 교체**(deep merge X, ADR-073).
+ *
+ * # `/health` 면제 실효 (ADR-072)
+ *   라우트 `config.skipAsp / skipCsrf` 플래그를 ASP·CSRF hook 이 검사해 우회한다. rate-limit 은 fastify
+ *   네이티브 라우트 옵션 `config.rateLimit: false` 로 면제한다(@fastify/rate-limit 의 onRoute 가 읽음).
+ *   MegaApp 이 `/health`·`/health/ready` 를 이 세 플래그와 함께 등록한다.
+ *
+ * # 트레이싱 (ADR-126 인프라 재사용)
+ *   보안 거부 시 활성 HTTP span 에 `mega.security.reason` attribute 를 박는다(CSRF Origin 불일치/토큰
+ *   불일치, rate-limit 초과). 옵트인 OFF 면 `activeSpan()` 이 undefined 라 0 비용 no-op.
+ *
+ * @module core/security
+ */
+import fastifyHelmet from '@fastify/helmet'
+import fastifyCors from '@fastify/cors'
+import fastifyRateLimit from '@fastify/rate-limit'
+import fastifyCsrf from '@fastify/csrf-protection'
+import fastifyCookie from '@fastify/cookie'
+import { registerAspPlugin } from '../lib/asp/plugin.js'
+import { MegaForbiddenError } from '../errors/http-errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+
+/** rate-limit 기본값 (ADR-048: IP 당 100 req/min). 사용자 config 로 완전 교체(ADR-073). */
+export const DEFAULT_RATE_LIMIT = Object.freeze({ max: 100, timeWindow: '1 minute' })
+
+/** CSRF 토큰 검증을 건너뛰는 안전 메서드(상태 변경 없음). */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * 보안 거부 사유를 현재 활성 HTTP span 에 기록한다(ADR-126). 활성 span 없거나 트레이싱 OFF 면 no-op.
+ * @param {string} reason - `mega.security.reason` 값(예: `'csrf.origin_mismatch'`).
+ * @param {Record<string, string|number|boolean>} [extra] - 부가 attribute.
+ * @returns {void}
+ */
+function annotateReject(reason, extra = {}) {
+  MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.security.reason': reason, ...extra })
+}
+
+/**
+ * 보안 플러그인 자동 등록 결과 요약(디버그·테스트용).
+ * @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=디폴트(100/min).
+ * @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, opts) {
+  const {
+    appName,
+    hosts = [],
+    helmet,
+    cors,
+    rateLimit,
+    csrf,
+    asp,
+    resolveRateStore,
+    logger,
+  } = opts
+
+  /** @type {SecuritySummary} */
+  const summary = { helmet: false, cors: false, rateLimit: false, csrf: false, asp: false, rateLimitStore: null }
+
+  // ── helmet (보안 헤더 + CSP, ADR-047) ──
+  if (helmet !== false) {
+    fastify.register(fastifyHelmet, /** @type {any} */ (helmet ?? {}))
+    summary.helmet = true
+  }
+
+  // ── cors (ADR-047) — 디폴트 origin:false(교차출처 거부, 안전 디폴트). ──
+  if (cors !== false) {
+    fastify.register(fastifyCors, /** @type {any} */ (cors ?? { origin: false }))
+    summary.cors = true
+  }
+
+  // ── rate-limit (ADR-048) — 멀티 인스턴스는 Redis(caches.rate), 미선언 시 in-memory 폴백. ──
+  if (rateLimit !== false) {
+    const base = /** @type {Record<string, any>} */ (rateLimit ?? DEFAULT_RATE_LIMIT) // ADR-073: 완전 교체.
+    // Redis 백엔드 해석 — 해석기가 ioredis 인스턴스를 주면 분산 카운팅, 아니면 in-memory.
+    const redis = typeof resolveRateStore === 'function' ? resolveRateStore() : null
+    summary.rateLimitStore = redis ? 'redis' : 'memory'
+
+    // ⚠️ onRoute 순서 함정 회피 — @fastify/rate-limit 의 `global:true` 는 onRoute hook 으로 라우트별
+    //   limiter 를 붙이는데, onRoute 는 "등록 이후" 라우트만 잡는다. 우리 라우트는 loadRoutes/Router 가
+    //   생성자 "이후" 직접 등록하므로 onRoute 가 놓친다(실측 확인). 대신 `global:false` 로 등록하고
+    //   `register().after()`(플러그인 로드 직후, 데코레이터 `fastify.rateLimit` 가용)에서 limiter 를
+    //   **글로벌 onRequest hook** 으로 부착한다 — 글로벌 hook 은 등록 순서와 무관하게 전 라우트 적용.
+    //   `/health` 등 면제는 allowList 가 라우트 `config.skipRateLimit` 를 보고 우회한다(ADR-072/127).
+    const userAllow = base.allowList
+    /** @type {(req: any, key: string) => boolean} */
+    const allowList = (req, key) => {
+      if (req.routeOptions?.config?.skipRateLimit === true) return true // 면제 라우트(/health 등).
+      if (Array.isArray(userAllow)) return userAllow.includes(key)
+      if (typeof userAllow === 'function') return userAllow(req, key)
+      return false
+    }
+    fastify.register(fastifyRateLimit, /** @type {any} */ ({ global: false, ...(redis ? { redis } : {}) })).after(
+      (/** @type {Error|null} */ err) => {
+        if (err) throw err // 등록 실패는 fail-fast(묵시 무시 금지).
+        fastify.addHook(
+          'onRequest',
+          /** @type {any} */ (fastify).rateLimit({
+            ...base,
+            allowList,
+            // 초과 시 활성 span 에 거부 사유 기록(ADR-126). 응답은 플러그인 기본(429 + Retry-After).
+            onExceeded: (/** @type {any} */ req, /** @type {string} */ key) => {
+              annotateReject('rate_limit.exceeded', { 'mega.security.rate_limit.key': String(key) })
+              logger?.debug?.({ app: appName, route: req.routeOptions?.url, key }, 'security.rate_limit exceeded')
+            },
+          }),
+        )
+      },
+    )
+    summary.rateLimit = true
+    logger?.debug?.({ app: appName, store: summary.rateLimitStore }, 'security.rate_limit registered')
+  }
+
+  // ── csrf (ADR-051) — cookie double-submit. JSON 면제+Origin 검증 / 폼 토큰 검증. ──
+  if (csrf !== false) {
+    fastify.register(fastifyCookie)
+    fastify.register(fastifyCsrf, /** @type {any} */ (csrf ?? {}))
+    registerCsrfGuard(fastify, { hosts, logger, appName })
+    summary.csrf = true
+  }
+
+  // ── ASP HTTP (옵트인) — masterSecret + http.enabledPaths 둘 다 있을 때만. ──
+  if (asp?.masterSecret && Array.isArray(asp.http?.enabledPaths) && asp.http.enabledPaths.length > 0) {
+    registerAspPlugin(
+      fastify,
+      {
+        masterSecret: asp.masterSecret,
+        enabledPaths: asp.http.enabledPaths,
+        driftMs: asp.http.driftMs,
+        headerSignal: asp.http.headerSignal,
+        timestampHeader: asp.http.timestampHeader,
+        nonceCache: asp.http.nonceCache,
+      },
+      { logger: /** @type {any} */ (logger) },
+    )
+    summary.asp = true
+    logger?.debug?.({ app: appName, paths: asp.http.enabledPaths }, 'security.asp_http registered')
+  }
+
+  logger?.debug?.({ app: appName, ...summary }, 'security.plugins registered')
+  return summary
+}
+
+/**
+ * ADR-051 CSRF 조건부 가드 — 글로벌 `preHandler`(body 파싱 이후, 폼 `_csrf` 필드 접근 위해).
+ *
+ * 동작 (ADR-051 정본: "폼 기반 요청만 토큰 검증, 나머지는 Origin"):
+ *   1. `skipCsrf` 라우트 → 통과(/ health, /metrics 등 면제).
+ *   2. 안전 메서드(GET/HEAD/OPTIONS) → 통과(상태 변경 없음).
+ *   3. **폼**(`application/x-www-form-urlencoded` / `multipart/form-data`) → `fastify.csrfProtection`
+ *      으로 토큰 검증(실패 시 플러그인이 403 송신). HTML 폼 auto-submit 이 CSRF 의 주 공격 벡터.
+ *   4. 그 외(JSON·빈 본문·기타) → **토큰 면제 + Origin 검증**. Origin/Referer 가 앱 도메인과 불일치하면
+ *      403. Origin 헤더 없는 비브라우저 클라(API)는 통과(CSRF 는 브라우저 쿠키 공격이라 해당 없음).
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{ hosts: string[], logger?: { debug?: Function, warn?: Function }, appName: string }} args
+ * @returns {void}
+ */
+function registerCsrfGuard(fastify, { hosts, logger, appName }) {
+  fastify.addHook('preHandler', async (req, reply) => {
+    // skipCsrf 는 우리 전용 라우트 플래그 — Fastify config 타입에 없어 cast.
+    const routeCfg = /** @type {{ skipCsrf?: boolean } | undefined} */ (req.routeOptions?.config)
+    if (routeCfg?.skipCsrf) return
+    if (SAFE_METHODS.has(req.method)) return
+
+    const contentType = String(req.headers['content-type'] ?? '')
+    const isForm =
+      contentType.includes('application/x-www-form-urlencoded') ||
+      contentType.includes('multipart/form-data')
+
+    if (isForm) {
+      // ADR-051: 폼 → 토큰 검증. csrfProtection 은 동기(@fastify/csrf-protection v7):
+      // 성공 시 next() 호출, 실패 시 reply.send(403) 후 next 미호출. next 호출 여부로 통과 판별한다.
+      let passed = false
+      fastify.csrfProtection(/** @type {any} */ (req), /** @type {any} */ (reply), () => {
+        passed = true
+      })
+      if (!passed) {
+        annotateReject('csrf.invalid_token')
+        logger?.debug?.({ app: appName, route: req.routeOptions?.url }, 'security.csrf invalid token')
+        // reply 는 csrfProtection 이 이미 403 송신. **return reply 로 라이프사이클을 명시 중단**한다
+        // (Fastify 정본 관용) — plain return 만 하면, 비동기 onSend 훅(예: 세션 store I/O await, ADR-129)이
+        // 응답 완료를 지연시키는 동안 Fastify 가 핸들러를 실행해 이중 send(ERR_HTTP_HEADERS_SENT)가 난다.
+        return reply
+      }
+      return
+    }
+
+    // ADR-051: 비폼(JSON·빈 본문·기타) → 토큰 면제 + Origin 검증.
+    if (!isOriginAllowed(req, hosts)) {
+      annotateReject('csrf.origin_mismatch')
+      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).',
+        { details: { rule: 'origin_mismatch' } },
+      )
+    }
+  })
+}
+
+/**
+ * CSRF Origin 검증(ADR-051) — Origin/Referer 의 hostname 이 요청 Host 또는 앱 도메인과 일치하는가.
+ * Origin·Referer 둘 다 없으면(비브라우저 API 클라) 통과 — CSRF 는 브라우저 쿠키 공격이라 해당 없음.
+ *
+ * @param {import('fastify').FastifyRequest} req
+ * @param {string[]} hosts - 앱 도메인 allowlist(`app.config.hosts`).
+ * @returns {boolean} 허용 여부.
+ */
+function isOriginAllowed(req, hosts) {
+  const raw = req.headers.origin ?? req.headers.referer
+  if (!raw) return true // 비브라우저 클라 — Origin 없음.
+  let originHost
+  try {
+    originHost = new URL(String(raw)).hostname
+  } 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])
+}

package/src/core/services-loader.js

@@ -0,0 +1,98 @@
+// @ts-check
+import { readdirSync, statSync } from 'node:fs'
+import { join, resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { MegaService } from './mega-service.js'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/**
+ * 서비스 파일명 → 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) {
+  const stem = fileName.replace(/\.js$/, '').replace(/-service$/, '')
+  return stem.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())
+}
+
+/**
+ * 앱의 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 async function loadServices({ servicesDir, appName }) {
+  /** @type {Map<string, Function>} */
+  const registry = new Map()
+
+  let serviceFiles
+  try {
+    serviceFiles = readdirSync(servicesDir)
+      .filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'))
+      .sort()
+  } catch (err) {
+    if (/** @type {any} */ (err).code === 'ENOENT') return registry
+    throw err
+  }
+
+  for (const fileName of serviceFiles) {
+    const absPath = pathResolve(join(servicesDir, fileName))
+    if (!statSync(absPath).isFile()) continue
+
+    let mod
+    try {
+      mod = await import(pathToFileURL(absPath).href)
+    } catch (err) {
+      throw new MegaConfigError(
+        'service.file_load_failed',
+        `Failed to load service file '${appName}/services/${fileName}': ${/** @type {any} */ (err).message}`,
+        { cause: err },
+      )
+    }
+
+    // 서비스 클래스 = export(default 또는 named) 중 MegaService 를 상속한 함수. 스캐폴드 템플릿은
+    // `export class {{Name}}Service extends MegaService`(named) 를 쓰므로 default 만 보지 않고 전체 export 를
+    // 훑는다. DI 인스턴스화 계약은 `new Cls(ctx, { app })`(MegaService 생성자) — 미상속 클래스는 제외된다.
+    const candidates = Object.values(mod).filter(
+      (v) => typeof v === 'function' && (v === MegaService || v.prototype instanceof MegaService),
+    )
+    if (candidates.length === 0) {
+      throw new MegaConfigError(
+        'service.no_service_class',
+        `Service file '${appName}/services/${fileName}' must export a class extending MegaService.`,
+        { details: { app: appName, file: fileName } },
+      )
+    }
+    if (candidates.length > 1) {
+      throw new MegaConfigError(
+        'service.ambiguous',
+        `Service file '${appName}/services/${fileName}' exports ${candidates.length} MegaService classes — keep one service per file.`,
+        { details: { app: appName, file: fileName, count: candidates.length } },
+      )
+    }
+    const Cls = candidates[0]
+
+    const name = serviceNameFromFile(fileName)
+    if (registry.has(name)) {
+      throw new MegaConfigError(
+        'service.duplicate_name',
+        `Service name '${name}' (from '${appName}/services/${fileName}') collides with another service file in the same app.`,
+        { details: { app: appName, name } },
+      )
+    }
+    registry.set(name, Cls)
+  }
+
+  return registry
+}

package/src/core/session-cleanup-schedule.js

@@ -0,0 +1,57 @@
+// @ts-check
+/**
+ * createSessionCleanupSchedule — 만료 세션 정리 스케줄 팩토리 (ADR-129/046, roadmap §216).
+ *
+ * ADR-046: "file 모드 cleanup 은 mega scheduler 가 자동 등록". 세션 스토어는 per-app inline 자원이라
+ * 전역 어댑터 매니저(`ctx.lock` 등)로 해석되지 않으므로, **스토어 인스턴스를 클로저로 캡처**한 `MegaSchedule`
+ * 서브클래스를 만들어 `mega scheduler` 호스트(또는 `config.schedules`)에 등록한다.
+ *
+ * # 단일 인스턴스 vs 멀티 인스턴스
+ *   - 단일 dev: `MegaFileSessionAdapter` 의 `cleanupIntervalMs`(내부 unref 타이머)로 충분(스케줄 불필요).
+ *   - 멀티 인스턴스: 본 팩토리로 스케줄을 만들고 `lock`(분산 락, ctx.lock alias)을 주면 한 인스턴스만
+ *     정리하도록 중복방지된다(`MegaScheduler` 가 lock 을 처리).
+ *   - Redis 스토어는 TTL 자동 만료라 cleanup 이 no-op(0) — 스케줄 등록은 무해하지만 보통 불필요.
+ *
+ * @module core/session-cleanup-schedule
+ */
+import { MegaSchedule } from '../lib/mega-schedule.js'
+
+/**
+ * 만료 세션 정리 `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, opts = {}) {
+  if (!store || typeof store.cleanup !== 'function') {
+    // 잘못된 store 는 fail-fast — 스케줄이 등록만 되고 조용히 아무것도 안 하는 일 방지.
+    throw new Error('createSessionCleanupSchedule: store must be a MegaSessionAdapter with cleanup().')
+  }
+  const cron = opts.cron ?? '0 * * * *'
+  const name = opts.name ?? 'SessionCleanup'
+
+  class SessionCleanup extends MegaSchedule {
+    static cron = cron
+    static timezone = opts.timezone
+    static lock = opts.lock
+
+    /**
+     * 만료 세션 정리. store 는 클로저로 캡처(ctx 불필요).
+     * @param {Record<string, any>} _ctx
+     * @returns {Promise<{ removed: number }>}
+     */
+    async run(_ctx) {
+      const removed = await store.cleanup()
+      return { removed: typeof removed === 'number' ? removed : 0 }
+    }
+  }
+  // MegaScheduler.register 는 ScheduleClass.name(비어있지 않음)을 등록 키로 쓴다 — 익명 클래스라 명시 부여.
+  Object.defineProperty(SessionCleanup, 'name', { value: name, configurable: true })
+  return SessionCleanup
+}

package/src/core/session-store.js

@@ -0,0 +1,55 @@
+// @ts-check
+/**
+ * createSessionStore — 세션 스토어 어댑터 팩토리 (ADR-129).
+ *
+ * `session.store.driver` ('file' | 'redis') 로 구체 `MegaSessionAdapter` 를 만든다.
+ *
+ * # 왜 전용 팩토리인가 (공유 드라이버 레지스트리 미사용)
+ *   `adapters/registry.js` 의 공유 레지스트리는 driver 명 'redis'/'file' 을 이미 **cache 어댑터**
+ *   (`MegaRedisAdapter`/`MegaFileAdapter`)에 매핑한다(ADR-044). 세션 스토어는 같은 driver 명을
+ *   쓰지만 **다른 인터페이스**(load/save/destroy/touch/cleanup)라 같은 레지스트리에 등록하면 충돌한다.
+ *   세션은 도메인이 분리(`ctx.session` = 요청별 로드 객체, db/cache 처럼 alias 접근자가 아님)되므로,
+ *   세션 전용 팩토리로 driver→어댑터를 직접 매핑한다(레지스트리/adapter-manager 무변경, ADR-129).
+ *
+ * @module core/session-store
+ */
+import { MegaConfigError } from '../errors/config-error.js'
+import { MegaFileSessionAdapter } from '../adapters/file-session-adapter.js'
+import { MegaRedisSessionAdapter } from '../adapters/redis-session-adapter.js'
+
+/** 지원 driver → 어댑터 클래스. */
+const SESSION_DRIVERS = Object.freeze({
+  file: MegaFileSessionAdapter,
+  redis: MegaRedisSessionAdapter,
+})
+
+/**
+ * 세션 스토어 어댑터를 만든다(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, defaults = {}) {
+  if (!storeConfig || typeof storeConfig !== 'object' || Array.isArray(storeConfig)) {
+    throw new MegaConfigError('session.invalid_store', 'session.store must be a plain object: { driver: "file"|"redis", ... }.', {
+      details: { type: Array.isArray(storeConfig) ? 'array' : storeConfig === null ? 'null' : typeof storeConfig },
+    })
+  }
+  const driver = storeConfig.driver
+  if (typeof driver !== 'string' || !(driver in SESSION_DRIVERS)) {
+    throw new MegaConfigError('session.unknown_driver', `session.store.driver must be one of [${Object.keys(SESSION_DRIVERS).join(', ')}] (got ${JSON.stringify(driver)}).`, {
+      details: { driver, supported: Object.keys(SESSION_DRIVERS) },
+    })
+  }
+  const Cls = SESSION_DRIVERS[/** @type {'file'|'redis'} */ (driver)]
+  // store 에 ttlMs 가 명시되지 않았으면 미들웨어 기본 ttlMs 를 주입(단일 출처 — session.ttlMs).
+  const cfg = storeConfig.ttlMs === undefined && defaults.ttlMs !== undefined ? { ...storeConfig, ttlMs: defaults.ttlMs } : storeConfig
+  return new Cls(/** @type {any} */ (cfg))
+}
+
+/** 지원 세션 driver 목록(테스트·문서용). */
+export const SESSION_STORE_DRIVERS = Object.freeze(Object.keys(SESSION_DRIVERS))