mega-framework 0.1.0

package/sample/crud/apps/main/locales/server/ko.json

@@ -0,0 +1,316 @@
+{
+  "nav_metrics": "메트릭",
+  "nav_tracing": "트레이싱",
+  "nav_logs": "로그",
+  "nav_upload": "업로드",
+  "nav_docs": "API 문서",
+  "nav_guide": "가이드",
+  "nav_perf": "성능",
+  "perf_title": "성능 벤치마크",
+  "perf_subtitle": "프레임워크 주요 표면(HTTP·암호화·DB·캐시·세션)의 처리량과 지연을 Node 내장 perf_hooks 로 직접 측정합니다.",
+  "perf_form_title": "벤치마크 실행",
+  "perf_form_desc": "시나리오와 반복 횟수를 고르고 실행하면 per-iteration 지연을 모아 백분위수를 계산합니다.",
+  "perf_scenario_label": "시나리오",
+  "perf_iterations_label": "반복",
+  "perf_concurrency_label": "동시성",
+  "perf_payload_label": "페이로드(byte)",
+  "perf_limit_hint": "동시성·페이로드를 비우면 시나리오별 기본값을 씁니다. 안전을 위해 시나리오마다 반복·동시성 상한이 있으며, 초과하면 자동으로 줄이고 결과에 표시합니다.",
+  "perf_run_btn": "실행",
+  "perf_clear_btn": "결과 지우기",
+  "perf_error": "실행 실패:",
+  "perf_results_title": "결과",
+  "perf_results_desc": "실행할 때마다 맨 위에 한 줄씩 쌓입니다. 시간(ms)은 작을수록, RPS 는 클수록 좋습니다.",
+  "perf_results_empty": "아직 실행한 결과가 없습니다.",
+  "perf_col_scenario": "시나리오",
+  "perf_col_iter": "반복",
+  "perf_col_conc": "동시성",
+  "perf_col_duration": "총시간(ms)",
+  "perf_col_rps": "RPS",
+  "perf_col_avg": "평균(ms)",
+  "perf_col_min": "최소",
+  "perf_col_max": "최대",
+  "perf_col_okfail": "성공/실패",
+  "guide_index_title": "가이드",
+  "guide_index_subtitle": "MEGA-FRAMEWORK 사용 가이드 모음입니다.",
+  "guide_index_welcome": "각 주제별 가이드를 골라 읽어보세요. 코드 예시는 서버에서 미리 하이라이트되어 표시됩니다.",
+  "guide_toc": "목차",
+  "guide_back": "목록으로",
+  "metrics_title": "메트릭",
+  "metrics_subtitle": "Prometheus /metrics 카운터를 사람이 보기 좋은 카드로 보여줍니다 (웹 프로세스 기준).",
+  "metrics_disabled": "메트릭이 비활성화되어 있습니다. mega.config.js 의 health.exposeMetrics 를 확인하세요.",
+  "metrics_http_title": "HTTP 요청",
+  "metrics_http_desc": "상태 코드 분류별 누적 요청 수입니다.",
+  "metrics_http_total": "총 요청 수",
+  "metrics_process_title": "프로세스",
+  "metrics_process_desc": "현재 웹 프로세스의 메모리·가동시간·CPU 사용량입니다.",
+  "metrics_process_heap": "힙 사용량",
+  "metrics_process_rss": "RSS",
+  "metrics_process_uptime": "가동 시간",
+  "metrics_process_cpu": "CPU 시간",
+  "metrics_jobs_title": "잡 큐",
+  "metrics_jobs_desc": "잡 처리 이벤트 누적 수입니다 (잡 데모와 연동).",
+  "metrics_jobs_enqueued": "등록",
+  "metrics_jobs_processed": "처리",
+  "metrics_jobs_retried": "재시도",
+  "metrics_jobs_dlq": "DLQ",
+  "metrics_ws_title": "WebSocket",
+  "metrics_ws_desc": "WS 메시지 누적 수입니다 (채팅 데모와 연동).",
+  "metrics_ws_total": "총 메시지 수",
+  "metrics_ws_empty": "아직 WS 메시지가 없습니다.",
+  "metrics_routes_title": "라우트별 요청 수",
+  "metrics_routes_desc": "요청이 많은 상위 라우트입니다.",
+  "metrics_routes_empty": "아직 기록된 요청이 없습니다.",
+  "metrics_routes_route": "라우트",
+  "metrics_routes_count": "요청 수",
+  "metrics_raw_hint": "원본(Prometheus scrape 포맷):",
+  "tracing_title": "분산 추적",
+  "tracing_subtitle": "현재 요청의 trace_id 와 최근 trace 를 Zipkin 으로 잇습니다.",
+  "tracing_notice_generated": "trace 를 생성했습니다. 잠시 후 Zipkin 에서 확인할 수 있습니다.",
+  "tracing_disabled": "트레이싱이 비활성화되어 있습니다. .env 의 MEGA_OTEL_ENABLED=true 후 재시작하세요.",
+  "tracing_current_title": "현재 요청 trace",
+  "tracing_current_desc": "이 페이지를 연 요청의 trace_id 입니다 (응답 헤더 x-trace-id 에도 실립니다).",
+  "tracing_trace_id": "trace_id",
+  "tracing_span_id": "span_id",
+  "tracing_open_zipkin": "Zipkin 에서 보기",
+  "tracing_no_current": "현재 trace 가 없습니다 (트레이싱 비활성).",
+  "tracing_generate": "trace 생성",
+  "tracing_generate_hint": "사용자 span 으로 DB 핑을 한 번 실행해 다층 span 트리를 만듭니다.",
+  "tracing_zipkin_title": "Zipkin",
+  "tracing_zipkin_desc": "trace 는 OTLP→collector→Zipkin 으로 전달됩니다.",
+  "tracing_service": "서비스 이름",
+  "tracing_ui": "Zipkin UI",
+  "tracing_export_hint": "전송에 약간의 지연이 있어, 생성 직후엔 Zipkin 에 잠시 뒤 나타납니다.",
+  "tracing_recent_title": "최근 trace",
+  "tracing_recent_desc": "최근 기록된 trace_id 목록입니다.",
+  "tracing_recent_empty": "아직 기록된 trace 가 없습니다.",
+  "tracing_recent_at": "시각",
+  "tracing_recent_route": "라우트",
+  "tracing_view": "보기",
+  "logs_title": "구조적 로깅",
+  "logs_subtitle": "pino 로그를 emit 하고 trace_id·민감필드 마스킹을 시연합니다.",
+  "logs_notice_emitted": "로그를 emit 했습니다. 서버 콘솔에서 구조적 출력을 확인하세요.",
+  "logs_emit_title": "로그 emit",
+  "logs_emit_desc": "선택한 레벨로 로그 1건을 실제 logger 로 내보냅니다.",
+  "logs_level": "레벨",
+  "logs_message": "메시지",
+  "logs_message_ph": "예: 데모 로그 한 줄",
+  "logs_emit_btn": "emit",
+  "logs_redact_hint": "로그 payload 의 token/password/secret 은 console 출력에서 [Redacted] 로 마스킹되고, 활성 trace_id 가 자동 첨부됩니다 (ADR-141). 서버 콘솔에서 확인하세요.",
+  "logs_recent_title": "최근 emit",
+  "logs_recent_desc": "emit 한 로그의 안전한 메타데이터입니다 (시크릿 제외).",
+  "logs_recent_empty": "아직 emit 한 로그가 없습니다.",
+  "logs_recent_at": "시각",
+  "logs_recent_trace": "trace_id",
+  "upload_title": "파일 업로드",
+  "upload_subtitle": "multipart 업로드를 프로젝트 폴더에 저장하고 메타·다운로드 링크를 보여줍니다.",
+  "upload_form_title": "업로드",
+  "upload_form_desc": "이미지·PDF·텍스트 파일을 올립니다 (MIME·크기·개수 게이트).",
+  "upload_file_label": "파일 선택",
+  "upload_constraints": "허용: 이미지/PDF/텍스트 · 최대 5MB · 한 번에 3개까지",
+  "upload_submit": "업로드",
+  "upload_error": "업로드 실패:",
+  "upload_recent_title": "최근 업로드",
+  "upload_recent_desc": "저장된 파일의 메타데이터입니다 (파일명 클릭 시 다운로드).",
+  "upload_recent_empty": "아직 업로드한 파일이 없습니다.",
+  "upload_dir_hint": "저장 위치(프로젝트 루트 기준):",
+  "upload_recent_at": "시각",
+  "upload_recent_name": "파일명",
+  "upload_recent_path": "저장 경로",
+  "upload_recent_mime": "MIME",
+  "upload_recent_size": "크기",
+  "nav_home": "홈",
+  "nav_users": "사용자",
+  "nav_demo": "데모",
+  "theme_toggle": "테마 전환",
+  "footer_built": "MEGA-FRAMEWORK 로 제작 · Bootstrap 5",
+  "home_title": "사용자 CRUD 관리",
+  "home_subtitle": "postgres 기반 사용자 리소스를 Bootstrap 5 관리 UI 로 생성·조회·수정·삭제합니다. 같은 서비스 계층을 JSON REST API 도 함께 노출합니다.",
+  "home_cta_manage": "사용자 관리",
+  "home_cta_api": "JSON API (/users)",
+  "home_api_note": "모든 요청은 정본 계층 흐름을 따릅니다:",
+  "users_title": "사용자 목록",
+  "users_new": "사용자 추가",
+  "users_empty": "아직 사용자가 없습니다.",
+  "col_id": "ID",
+  "col_name": "이름",
+  "col_email": "이메일",
+  "col_created": "생성일",
+  "col_actions": "관리",
+  "action_edit": "수정",
+  "action_delete": "삭제",
+  "delete_confirm_title": "삭제 확인",
+  "delete_confirm_body": "정말 삭제할까요?",
+  "delete_confirm_cancel": "취소",
+  "delete_confirm_ok": "삭제",
+  "new_title": "사용자 추가",
+  "edit_title": "사용자 수정",
+  "field_name": "이름",
+  "field_name_ph": "예: 홍길동",
+  "field_name_required": "이름을 입력하세요.",
+  "field_email": "이메일",
+  "field_email_ph": "예: hong@example.com",
+  "field_email_required": "올바른 이메일을 입력하세요.",
+  "btn_create": "생성",
+  "btn_save": "저장",
+  "btn_cancel": "취소",
+  "notice_created": "사용자를 생성했습니다.",
+  "notice_updated": "사용자를 수정했습니다.",
+  "notice_deleted": "사용자를 삭제했습니다.",
+  "field_password": "비밀번호",
+  "field_password_hint": "최소 8자 이상 입력하세요.",
+  "login_title": "로그인",
+  "login_failed": "이메일 또는 비밀번호가 올바르지 않습니다.",
+  "login_locked": "로그인 시도가 너무 많습니다. 잠시 후 다시 시도하세요.",
+  "login_no_account": "계정이 없으신가요?",
+  "register_title": "회원가입",
+  "register_have_account": "이미 계정이 있으신가요?",
+  "btn_login": "로그인",
+  "btn_logout": "로그아웃",
+  "btn_register": "가입",
+  "auth_notice_logged_out": "로그아웃되었습니다.",
+  "auth_notice_registered": "가입이 완료되었습니다.",
+  "nav_notes": "노트 (Mongo)",
+  "nav_redis": "캐시 (Redis)",
+  "nav_ws": "채팅 (WS+ASP)",
+  "notes_title": "노트 (MongoDB)",
+  "notes_subtitle": "MongoDB 도큐먼트 어댑터로 notes 컬렉션을 생성·조회·수정·삭제합니다.",
+  "notes_new": "노트 추가",
+  "notes_empty": "아직 노트가 없습니다.",
+  "notes_new_title": "노트 추가",
+  "notes_edit_title": "노트 수정",
+  "notes_field_title": "제목",
+  "notes_field_title_ph": "예: 회의 메모",
+  "notes_field_title_required": "제목을 입력하세요.",
+  "notes_field_body": "본문",
+  "notes_field_body_ph": "내용을 입력하세요 (선택).",
+  "notes_notice_created": "노트를 생성했습니다.",
+  "notes_notice_updated": "노트를 수정했습니다.",
+  "notes_notice_deleted": "노트를 삭제했습니다.",
+  "redis_title": "Redis 데모",
+  "redis_subtitle": "Redis 어댑터로 방문 카운터(원자적 INCR/EXPIRE)와 쿼리 결과 캐시(GET/SET/TTL/DEL)를 시연합니다.",
+  "redis_visits_title": "방문 카운터",
+  "redis_visits_desc": "이 페이지를 열 때마다 카운터를 원자적으로 1씩 올립니다. 당일 카운터는 2일 후 자동 만료됩니다.",
+  "redis_visits_total": "누적 방문",
+  "redis_visits_today": "오늘 방문",
+  "redis_cache_title": "쿼리 결과 캐시",
+  "redis_cache_desc": "사용자 수를 Redis 에 30초간 캐싱합니다. 캐시에 있으면 hit(SQL 미실행), 없으면 miss(SQL 재계산)입니다.",
+  "redis_cache_hit": "캐시 적중",
+  "redis_cache_miss": "캐시 미스",
+  "redis_cache_ttl": "남은 TTL",
+  "redis_cache_reload": "다시 조회",
+  "redis_cache_clear": "캐시 비우기",
+  "redis_notice_cache_cleared": "캐시를 비웠습니다.",
+  "home_demo_notes": "Mongo 노트 데모",
+  "home_demo_redis": "Redis 캐시 데모",
+  "home_demo_ws": "WebSocket 채팅 데모",
+  "ws_title": "실시간 채팅 (WebSocket + ASP)",
+  "ws_subtitle": "WASM MegaSocket 으로 /ws/chat 에 접속합니다. 메시지는 ASP 로 암호화(E: 프레임)되어 브라우저에서 직접 암복호화되고, 서버는 채널 전체에 broadcast 합니다.",
+  "ws_asp_badge": "ASP 암호화",
+  "ws_asp_badge_title": "모든 메시지가 AES-256-GCM(E: 프레임)으로 암호화되어 송수신됩니다.",
+  "ws_status_connecting": "연결 중…",
+  "ws_status_open": "연결됨",
+  "ws_status_closed": "연결 끊김",
+  "ws_status_error": "오류",
+  "ws_online": "접속자 {n}명",
+  "ws_presence_join": "{user} 님이 입장했습니다.",
+  "ws_presence_leave": "{user} 님이 퇴장했습니다.",
+  "ws_empty": "아직 메시지가 없습니다. 첫 메시지를 보내보세요.",
+  "ws_input_placeholder": "메시지를 입력하세요…",
+  "ws_send": "보내기",
+  "ws_encrypted_note": "메시지는 ASP(AES-256-GCM) E: 프레임으로 암호화되어 전송됩니다.",
+  "nav_cron": "스케줄러 (Cron)",
+  "nav_jobs": "잡 큐 (NATS)",
+  "nav_worker": "워커 (Threads)",
+  "home_demo_cron": "스케줄러 데모",
+  "home_demo_jobs": "잡 큐 데모",
+  "home_demo_worker": "CPU 워커 데모",
+  "cron_title": "스케줄러 데모 (MegaSchedule)",
+  "cron_subtitle": "mega scheduler 프로세스가 30초마다 Redis 카운터를 원자적으로 올립니다. 다중 인스턴스 중복 실행은 분산 락(redlock leader election)으로 막습니다.",
+  "cron_counter_title": "실행 카운터",
+  "cron_counter_desc": "스케줄이 돌 때마다(또는 아래 수동 실행) Redis 카운터를 1씩 올립니다.",
+  "cron_counter_total": "누적 실행 횟수",
+  "cron_run_now": "지금 실행",
+  "cron_run_hint": "cron 시각을 기다리지 않고 같은 작업을 즉시 1회 실행합니다(수동 트리거).",
+  "cron_next_title": "다음 실행 시각",
+  "cron_next_desc": "croner 가 계산한 다음 다섯 번의 실행 예정 시각입니다(타이머 미가동 순수 계산).",
+  "cron_next_soonest": "가장 가까움",
+  "cron_history_title": "최근 실행 이력",
+  "cron_history_desc": "Redis LIST 에 최근 10건을 남깁니다(LPUSH + LTRIM). 자동 실행과 수동 실행이 함께 쌓입니다.",
+  "cron_history_empty": "아직 실행 이력이 없습니다. scheduler 프로세스를 켜거나 위에서 수동 실행해 보세요.",
+  "cron_history_at": "실행 시각",
+  "cron_history_source": "출처",
+  "cron_source_schedule": "스케줄",
+  "cron_source_manual": "수동",
+  "cron_notice_triggered": "스케줄 작업을 즉시 1회 실행했습니다.",
+  "jobs_title": "잡 큐 데모 (MegaJob)",
+  "jobs_subtitle": "EmailJob 을 NATS JetStream 에 enqueue 하면 mega worker 프로세스가 소비합니다. 일시 실패는 재시도되고, 영구 실패는 DLQ 로 격리됩니다.",
+  "jobs_enqueue_title": "이메일 발송 잡 넣기",
+  "jobs_enqueue_desc": "실제 발송은 하지 않고 처리만 시뮬레이션합니다. 모드로 성공/재시도/영구실패 흐름을 시연합니다.",
+  "jobs_enqueue_btn": "큐에 넣기",
+  "jobs_reload": "새로고침",
+  "jobs_field_to": "받는 사람",
+  "jobs_field_mode": "모드",
+  "jobs_mode_ok": "성공",
+  "jobs_mode_flaky": "재시도",
+  "jobs_mode_fail": "영구 실패",
+  "jobs_mode_ok_hint": "첫 시도에 바로 성공",
+  "jobs_mode_flaky_hint": "1번째 시도 실패 → 재시도 → 2번째 성공",
+  "jobs_mode_fail_hint": "매 시도 실패 → 재시도 소진 후 DLQ 격리",
+  "jobs_dlq_title": "DLQ (격리된 잡)",
+  "jobs_dlq_desc": "재시도를 모두 소진한 영구 실패 잡이 모이는 곳입니다(NATS 스트림). 원인 분석·재처리용.",
+  "jobs_dlq_empty": "아직 DLQ 로 간 잡이 없습니다.",
+  "jobs_dlq_failed_at": "실패 시각",
+  "jobs_dlq_deliveries": "전달 횟수",
+  "jobs_dlq_error": "오류",
+  "jobs_dlq_payload": "페이로드",
+  "jobs_events_title": "처리 이벤트",
+  "jobs_events_desc": "워커가 각 시도마다 남긴 타임라인입니다(최신순). 재시도가 일어나면 같은 잡이 여러 번 보입니다.",
+  "jobs_events_empty": "아직 처리된 잡이 없습니다. 위에서 잡을 넣고 mega worker 프로세스를 켜 보세요.",
+  "jobs_events_at": "시각",
+  "jobs_events_id": "잡 ID",
+  "jobs_events_attempt": "시도",
+  "jobs_events_status": "상태",
+  "jobs_status_sent": "발송됨",
+  "jobs_status_retry": "재시도",
+  "jobs_status_failed": "실패",
+  "jobs_notice_enqueued": "잡을 큐에 넣었습니다. 워커가 처리하면 아래 이벤트에 나타납니다.",
+  "worker_title": "CPU 워커 데모 (MegaWorker)",
+  "worker_subtitle": "SHA-256 N회 반복 같은 CPU-bound 작업을 worker_threads 풀에서 돌립니다. 계산 도중에도 서버가 다른 요청에 즉시 응답하는지(메인 스레드 non-block) 하트비트로 확인합니다.",
+  "worker_run_title": "해시 계산 실행",
+  "worker_run_desc": "반복 횟수만큼 SHA-256 을 체인 해시합니다. 메인 스레드가 아니라 워커 스레드에서 돕니다.",
+  "worker_run_btn": "워커에서 실행",
+  "worker_rounds_label": "반복 횟수",
+  "worker_pool_mode": "모드",
+  "worker_pool_size": "풀 크기",
+  "worker_error": "실행 실패:",
+  "worker_result_rounds": "반복 횟수",
+  "worker_result_ms": "소요 시간",
+  "worker_result_digest": "최종 해시",
+  "worker_heartbeat_title": "메인 스레드 하트비트",
+  "worker_heartbeat_desc": "1초마다 서버에 ping 을 보냅니다. 워커가 계산하는 동안에도 이 지연이 작게 유지되면 메인 스레드가 안 막힌 것입니다.",
+  "worker_heartbeat_count": "ping 횟수",
+  "worker_heartbeat_latency": "최근 왕복 지연",
+  "worker_heartbeat_last": "마지막 ping",
+  "worker_heartbeat_proof": "계산을 메인 스레드에서 했다면 이 ping 들이 계산이 끝날 때까지 통째로 멈춥니다. 워커 스레드라 멈추지 않습니다.",
+  "server": {
+    "internal": "내부 서버 오류"
+  },
+  "validation": {
+    "failed": "입력값이 올바르지 않습니다."
+  },
+  "auth": {
+    "required": "인증이 필요합니다."
+  },
+  "csrf": {
+    "invalid_token": "Invalid csrf token",
+    "missing_secret": "Missing csrf secret"
+  },
+  "upload": {
+    "unsupported_media_type": "허용되지 않는 파일 형식입니다.",
+    "too_large": "파일 크기가 허용 한도를 초과했습니다.",
+    "not_found": "파일을 찾을 수 없습니다."
+  },
+  "guide": {
+    "not_found": "가이드를 찾을 수 없습니다."
+  }
+}

package/sample/crud/apps/main/middleware/web-auth.js

@@ -0,0 +1,40 @@
+// @ts-check
+/**
+ * 웹(MPA) 인증 가드 + 뷰용 현재 사용자 helper (ADR-155).
+ *
+ * 프레임워크 `requireAuth`(mega-framework/auth)는 비로그인 시 401 을 throw 한다 — JSON 응답을 받는
+ * REST API(`/users`)에 맞는 동작이다. 반면 브라우저로 보는 관리 UI(`/admin/**`)는 401 본문 대신
+ * 로그인 페이지로 보내는 게 자연스럽다. 그래서 웹 라우트 전용 **리다이렉트** 가드를 따로 둔다.
+ *
+ * @module middleware/web-auth
+ */
+
+/** 로그인 페이지 경로 — 가드와 뷰가 같은 출처를 보도록 상수화. */
+export const LOGIN_PATH = '/auth/login'
+
+/**
+ * 세션에서 현재 로그인 사용자를 뷰 locals 형태로 뽑는다. 비로그인이면 null.
+ * 로그인 시 세션에 `userId`+`userName` 을 심어두므로(컨트롤러), navbar 는 DB 재조회 없이 이름을 보여준다.
+ * @param {import('fastify').FastifyRequest} req
+ * @returns {{ id: any, name: string } | null}
+ */
+export function currentUser(req) {
+  const session = /** @type {any} */ (req).session
+  if (session?.userId == null) return null
+  return { id: session.userId, name: typeof session.userName === 'string' ? session.userName : '' }
+}
+
+/**
+ * `/admin/**` 보호용 `before` 가드. 비로그인 요청을 로그인 페이지로 리다이렉트한다(401 throw 대신).
+ * Fastify preHandler 에서 reply 를 보내면(redirect) 핸들러 체인이 단락된다.
+ * @param {import('fastify').FastifyRequest} req
+ * @param {import('fastify').FastifyReply} reply
+ * @returns {Promise<void>}
+ */
+export async function webRequireAuth(req, reply) {
+  const session = /** @type {any} */ (req).session
+  if (session?.userId == null) {
+    req.log?.debug?.({ route: req.url }, 'web.auth redirect — not logged in')
+    return /** @type {any} */ (reply).redirect(LOGIN_PATH)
+  }
+}

package/sample/crud/apps/main/middleware/ws-auth.js

@@ -0,0 +1,48 @@
+// @ts-check
+/**
+ * WS upgrade 인증 가드 (ADR-158) — 로그인 세션만 /ws/chat 연결 허용.
+ *
+ * HTTP `'upgrade'` 핸드셰이크는 Fastify 요청 파이프라인을 타지 않아 `req.session` 이 없다(raw
+ * IncomingMessage). 그래서 프레임워크 `readSession`(ADR-159)으로 쿠키 → 서명 검증 → 세션 스토어
+ * 로드를 직접 수행해 신원을 확인한다. 비로그인/위조/만료는 모두 `false` 반환 → upgrade 401 거부
+ * (ws-upgrade.js handleUpgrade, fail-closed). 반환한 신원 객체는 채널 onConnect 의 `ctx.auth` 가 된다.
+ *
+ * 세션 스토어·시크릿 출처:
+ *   - store: `router.app.sessionStore`(app.config.js 의 session.store 가 연결한 redis 인스턴스).
+ *   - secret: `SESSION_SECRET`(mega.config.js 의 server.sessionSecret 과 동일 출처) — 쿠키 HMAC 검증용.
+ *
+ * @module middleware/ws-auth
+ */
+import { readSession } from 'mega-framework'
+
+/**
+ * `/ws/chat` upgrade 인증 `before` 미들웨어를 만든다(앱 바인딩 팩토리).
+ *
+ * 라우트 파일에서 `router.app` 으로 앱을 얻어 세션 스토어에 닿게 한다 — `before(req)` 는 raw req 만
+ * 받으므로 클로저로 스토어를 주입한다.
+ *
+ * @param {import('mega-framework').MegaApp} app - 바인딩 앱(router.app). sessionStore 출처.
+ * @returns {(req: import('node:http').IncomingMessage) => Promise<false | { userId: string, sessionId: string, userName: string }>}
+ *   비로그인이면 false(401), 로그인이면 ctx.auth 가 될 신원 객체.
+ */
+export function makeWsRequireAuth(app) {
+  const secret = process.env.SESSION_SECRET
+  if (typeof secret !== 'string' || secret.length === 0) {
+    // 시크릿 없는 세션 검증은 불가 — 부팅 시 fail-fast(silent 진행 금지).
+    throw new Error('makeWsRequireAuth: SESSION_SECRET is required (set it in .env).')
+  }
+  return async function wsRequireAuth(req) {
+    const sess = await readSession(req, { store: app.sessionStore, secret })
+    // 로그인 신원은 컨트롤러가 세션에 심은 userId/userName(web-auth.js currentUser 와 동일 키).
+    const userId = sess?.data.userId
+    if (userId == null) {
+      app.fastify.log?.debug?.({ route: req.url }, 'ws.auth deny — not logged in (401)')
+      return false
+    }
+    return {
+      userId: String(userId),
+      sessionId: sess.sid,
+      userName: typeof sess.data.userName === 'string' ? sess.data.userName : '',
+    }
+  }
+}

package/sample/crud/apps/main/migrations/20260606000001-create-users.js

@@ -0,0 +1,27 @@
+// @ts-check
+/**
+ * 마이그레이션 create-users (20260606000001). up = users 테이블 생성, down = 제거(ADR-149).
+ * `mega migrate`(up)·`mega migrate:down`·`mega migrate:status` 로 실행. 적용 이력은 대상 DB 의
+ * `mega_migrations` 테이블이 추적하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ *
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+  await db.query(`
+    CREATE TABLE IF NOT EXISTS users (
+      id         SERIAL PRIMARY KEY,
+      name       TEXT NOT NULL,
+      email      TEXT NOT NULL UNIQUE,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )
+  `)
+}
+
+/**
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+  await db.query('DROP TABLE IF EXISTS users')
+}

package/sample/crud/apps/main/migrations/20260606000002-add-auth-to-users.js

@@ -0,0 +1,30 @@
+// @ts-check
+/**
+ * 마이그레이션 add-auth-to-users (20260606000002). 로그인을 위해 users 에 인증 컬럼을 더한다(ADR-155).
+ * `mega migrate`(up)·`mega migrate:down` 로 실행하며, 각 마이그레이션은 트랜잭션으로 감싸 적용된다.
+ *
+ * 컬럼은 모두 nullable — 기존 row(name+email 만 있는 사용자)를 깨지 않는다. password_hash 가 비어 있는
+ * 계정은 로그인 대상이 아니며, /register 로 만든 계정만 해시를 가진다.
+ *
+ * - password_hash: scrypt 해시 문자열(`$scrypt$…`, src/lib/mega-hash.js). 평문 비밀번호는 저장하지 않는다.
+ * - last_login_at: 마지막 로그인 시각(성공 시 갱신). 운영 관측·"최근 로그인" 표시에 쓴다.
+ *
+ * brute-force 실패 카운트·잠금은 DB 컬럼이 아니라 redis 에 둔다(원자적 INCR, src/lib/mega-brute-force.js,
+ * ADR-049/130) — 여기 failed_login_count 같은 컬럼을 두지 않는 이유다.
+ *
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db - 대상 DB 어댑터(트랜잭션 내 query).
+ * @returns {Promise<void>}
+ */
+export async function up(db) {
+  await db.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
+  await db.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
+}
+
+/**
+ * @param {{ query: (sql: string, params?: any[]) => Promise<any> }} db
+ * @returns {Promise<void>}
+ */
+export async function down(db) {
+  await db.query('ALTER TABLE users DROP COLUMN IF EXISTS last_login_at')
+  await db.query('ALTER TABLE users DROP COLUMN IF EXISTS password_hash')
+}

package/sample/crud/apps/main/models/note.js

@@ -0,0 +1,71 @@
+// @ts-check
+import { randomUUID } from 'node:crypto'
+import { MegaModel } from 'mega-framework'
+
+/**
+ * Note 모델 — `notes` 컬렉션(globalKey 'mongo' 의 MongoDB, ADR-108). SQL 모델(User)과 달리 `this.db` 가
+ * MongoClient 의 `Db` 핸들이라, ORM 없이 도큐먼트 API(`collection().find/insertOne/...`)로 도메인 메서드를
+ * 직접 작성한다(ADR-009). 모델은 서비스만 import 한다(라우트·컨트롤러 직접 import 는 `mega/no-direct-model-import` 차단, ADR-022).
+ *
+ * 식별자는 mongo `_id`(ObjectId) 대신 자체 `id`(UUID v4) 필드를 쓴다 — 라우트 파라미터/폼에서 다루기 쉽고,
+ * `mongodb` 드라이버의 `ObjectId` 를 샘플에서 import 하지 않아도 돼 driver 결합을 피한다. 읽기에서는
+ * `_id` 를 projection 으로 제외해 도메인 형태만 노출한다.
+ *
+ * @typedef {{ id: string, title: string, body: string, created_at: string }} NoteDoc
+ */
+export class Note extends MegaModel {
+  static adapter = 'mongo'
+  static table = 'notes'
+
+  /** 읽기 공통 projection — 내부 `_id` 를 빼고 도메인 필드만 돌려준다. */
+  static #projection = { projection: { _id: 0 } }
+
+  /** @returns {import('mongodb').Collection} `notes` 컬렉션 핸들. */
+  static get collection() {
+    return this.db.collection(this.table)
+  }
+
+  /** 최신순 전체 목록. @returns {Promise<NoteDoc[]>} */
+  static async list() {
+    return /** @type {Promise<NoteDoc[]>} */ (
+      this.collection.find({}, Note.#projection).sort({ created_at: -1 }).toArray()
+    )
+  }
+
+  /** 단건 조회(없으면 null). @param {string} id @returns {Promise<NoteDoc | null>} */
+  static async findById(id) {
+    return /** @type {Promise<NoteDoc | null>} */ (this.collection.findOne({ id }, Note.#projection))
+  }
+
+  /** 생성 — UUID·생성시각을 부여해 삽입한다. @param {{ title: string, body: string }} input @returns {Promise<NoteDoc>} */
+  static async create({ title, body }) {
+    /** @type {NoteDoc} */
+    const doc = { id: randomUUID(), title, body, created_at: new Date().toISOString() }
+    await this.collection.insertOne({ ...doc })
+    return doc
+  }
+
+  /**
+   * 수정 — 주어진 필드만 $set 한다(undefined 는 제외해 기존 값 보존). 대상이 없으면 null.
+   * @param {string} id @param {{ title?: string, body?: string }} patch @returns {Promise<NoteDoc | null>}
+   */
+  static async update(id, { title, body }) {
+    /** @type {Record<string, string>} */
+    const set = {}
+    if (title !== undefined) set.title = title
+    if (body !== undefined) set.body = body
+    if (Object.keys(set).length > 0) await this.collection.updateOne({ id }, { $set: set })
+    return this.findById(id)
+  }
+
+  /** 삭제 — 삭제 건수가 1 이상이면 true. @param {string} id @returns {Promise<boolean>} */
+  static async remove(id) {
+    const { deletedCount } = await this.collection.deleteOne({ id })
+    return deletedCount > 0
+  }
+
+  /** 전체 도큐먼트 수(캐시 데모용 카운트 쿼리). @returns {Promise<number>} */
+  static async count() {
+    return this.collection.countDocuments({})
+  }
+}

package/sample/crud/apps/main/models/user.js

@@ -0,0 +1,86 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * User 모델 — `users` 테이블(globalKey 'primary' 의 postgres). ORM 없이 계측 SQL(`this.query`, ADR-138)로
+ * 도메인 메서드를 직접 작성한다(ADR-009). 모델은 서비스만 import 한다(라우트·컨트롤러 직접 import 는
+ * `mega/no-direct-model-import` 가 차단, ADR-022).
+ *
+ * @typedef {{ id: number, name: string, email: string, created_at: string }} UserRow
+ * @typedef {{ id: number, name: string, email: string, password_hash: string | null }} UserAuthRow
+ */
+export class User extends MegaModel {
+  static adapter = 'primary'
+  static table = 'users'
+
+  /** @returns {Promise<UserRow[]>} */
+  static async list() {
+    const { rows } = await this.query('SELECT id, name, email, created_at FROM users ORDER BY id ASC')
+    return rows
+  }
+
+  /** 전체 사용자 수 — /demo/redis 캐시 데모가 캐싱하는 SQL 카운트 쿼리. @returns {Promise<number>} */
+  static async count() {
+    const { rows } = await this.query('SELECT count(*)::int AS n FROM users')
+    return rows[0].n
+  }
+
+  /** @param {number} id @returns {Promise<UserRow | null>} */
+  static async findById(id) {
+    const { rows } = await this.query('SELECT id, name, email, created_at FROM users WHERE id = $1', [id])
+    return rows[0] ?? null
+  }
+
+  /** @param {{ name: string, email: string }} input @returns {Promise<UserRow>} */
+  static async create({ name, email }) {
+    const { rows } = await this.query(
+      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id, name, email, created_at',
+      [name, email],
+    )
+    return rows[0]
+  }
+
+  /** @param {number} id @param {{ name?: string, email?: string }} patch @returns {Promise<UserRow | null>} */
+  static async update(id, { name, email }) {
+    const { rows } = await this.query(
+      'UPDATE users SET name = COALESCE($2, name), email = COALESCE($3, email) WHERE id = $1 RETURNING id, name, email, created_at',
+      [id, name ?? null, email ?? null],
+    )
+    return rows[0] ?? null
+  }
+
+  /** @param {number} id @returns {Promise<boolean>} 삭제 여부. */
+  static async remove(id) {
+    const { rowCount } = await this.query('DELETE FROM users WHERE id = $1', [id])
+    return rowCount > 0
+  }
+
+  /**
+   * 비밀번호 해시를 포함해 새 사용자를 만든다(/register). 반환에는 해시를 포함하지 않는다(노출 최소화).
+   * @param {{ name: string, email: string, passwordHash: string }} input
+   * @returns {Promise<UserRow>}
+   */
+  static async register({ name, email, passwordHash }) {
+    const { rows } = await this.query(
+      'INSERT INTO users (name, email, password_hash) VALUES ($1, $2, $3) RETURNING id, name, email, created_at',
+      [name, email, passwordHash],
+    )
+    return rows[0]
+  }
+
+  /**
+   * 로그인 검증용 — 이메일로 사용자를 찾아 password_hash 까지 돌려준다. 해시가 필요한 인증 경로에서만 쓴다
+   * (일반 조회 list/findById 는 해시를 SELECT 하지 않아 노출되지 않는다).
+   * @param {string} email
+   * @returns {Promise<UserAuthRow | null>}
+   */
+  static async findByEmailWithHash(email) {
+    const { rows } = await this.query('SELECT id, name, email, password_hash FROM users WHERE email = $1', [email])
+    return rows[0] ?? null
+  }
+
+  /** 로그인 성공 시각 갱신. @param {number} id @returns {Promise<void>} */
+  static async touchLastLogin(id) {
+    await this.query('UPDATE users SET last_login_at = now() WHERE id = $1', [id])
+  }
+}