@mandujs/core 0.9.40 → 0.9.42

package/src/runtime/server.ts

@@ -1,20 +1,25 @@
 import type { Server } from "bun";
-import type { RoutesManifest } from "../spec/schema";
-import type { BundleManifest } from "../bundler/types";
-import type { ManduFilling } from "../filling/filling";
-import { ManduContext } from "../filling/context";
-import { Router } from "./router";
-import { renderSSR, renderStreamingResponse } from "./ssr";
-import { PageBoundary, DefaultLoading, DefaultError, type ErrorFallbackProps } from "./boundary";
-import React, { type ReactNode } from "react";
-import path from "path";
-import {
-  formatErrorResponse,
-  createNotFoundResponse,
-  createHandlerNotFoundResponse,
-  createPageLoadErrorResponse,
-  createSSRErrorResponse,
-} from "../error";
+import type { RoutesManifest } from "../spec/schema";
+import type { BundleManifest } from "../bundler/types";
+import type { ManduFilling } from "../filling/filling";
+import { ManduContext } from "../filling/context";
+import { Router } from "./router";
+import { renderSSR, renderStreamingResponse } from "./ssr";
+import { PageBoundary, DefaultLoading, DefaultError, type ErrorFallbackProps } from "./boundary";
+import React, { type ReactNode } from "react";
+import path from "path";
+import fs from "fs/promises";
+import { PORTS } from "../constants";
+import {
+  createNotFoundResponse,
+  createHandlerNotFoundResponse,
+  createPageLoadErrorResponse,
+  createSSRErrorResponse,
+  errorToResponse,
+  err,
+  ok,
+  type Result,
+} from "../error";
 import {
   type CorsOptions,
   isPreflightRequest,
@@ -504,13 +509,34 @@ function createDefaultAppFactory(registry: ServerRegistry) {
  * 경로가 허용된 디렉토리 내에 있는지 검증
  * Path traversal 공격 방지
  */
-function isPathSafe(filePath: string, allowedDir: string): boolean {
-  const resolvedPath = path.resolve(filePath);
-  const resolvedAllowedDir = path.resolve(allowedDir);
-  // 경로가 허용된 디렉토리로 시작하는지 확인 (디렉토리 구분자 포함)
-  return resolvedPath.startsWith(resolvedAllowedDir + path.sep) ||
-         resolvedPath === resolvedAllowedDir;
-}
+async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean> {
+  try {
+    const resolvedPath = path.resolve(filePath);
+    const resolvedAllowedDir = path.resolve(allowedDir);
+
+    if (!resolvedPath.startsWith(resolvedAllowedDir + path.sep) &&
+        resolvedPath !== resolvedAllowedDir) {
+      return false;
+    }
+
+    // 파일이 없으면 안전 (존재하지 않는 경로)
+    try {
+      await fs.access(resolvedPath);
+    } catch {
+      return true;
+    }
+
+    // Symlink 해결 후 재검증
+    const realPath = await fs.realpath(resolvedPath);
+    const realAllowedDir = await fs.realpath(resolvedAllowedDir);
+
+    return realPath.startsWith(realAllowedDir + path.sep) ||
+           realPath === realAllowedDir;
+  } catch (error) {
+    console.warn(`[Mandu Security] Path validation failed: ${filePath}`, error);
+    return false;
+  }
+}
 
 /**
  * 정적 파일 서빙
@@ -520,50 +546,73 @@ function isPathSafe(filePath: string, allowedDir: string): boolean {
  *
  * 보안: Path traversal 공격 방지를 위해 모든 경로를 검증합니다.
  */
-async function serveStaticFile(pathname: string, settings: ServerRegistrySettings): Promise<Response | null> {
-  let filePath: string | null = null;
-  let isBundleFile = false;
-  let allowedBaseDir: string;
-
-  // Path traversal 시도 조기 차단 (정규화 전 raw 체크)
-  if (pathname.includes("..")) {
-    return null;
-  }
+async function serveStaticFile(pathname: string, settings: ServerRegistrySettings): Promise<Response | null> {
+  let filePath: string | null = null;
+  let isBundleFile = false;
+  let allowedBaseDir: string;
+  let relativePath: string;
+
+  // Path traversal 시도 조기 차단 (정규화 전 raw 체크)
+  if (pathname.includes("..")) {
+    return null;
+  }
 
   // 1. 클라이언트 번들 파일 (/.mandu/client/*)
   if (pathname.startsWith("/.mandu/client/")) {
     // pathname에서 prefix 제거 후 안전하게 조합
-    const relativePath = pathname.slice("/.mandu/client/".length);
-    allowedBaseDir = path.join(settings.rootDir, ".mandu", "client");
-    filePath = path.join(allowedBaseDir, relativePath);
-    isBundleFile = true;
-  }
-  // 2. Public 폴더 파일 (/public/*)
-  else if (pathname.startsWith("/public/")) {
-    const relativePath = pathname.slice("/public/".length);
-    allowedBaseDir = path.join(settings.rootDir, "public");
-    filePath = path.join(allowedBaseDir, relativePath);
-  }
-  // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
-  else if (
-    pathname === "/favicon.ico" ||
-    pathname === "/robots.txt" ||
+    relativePath = pathname.slice("/.mandu/client/".length);
+    allowedBaseDir = path.join(settings.rootDir, ".mandu", "client");
+    isBundleFile = true;
+  }
+  // 2. Public 폴더 파일 (/public/*)
+  else if (pathname.startsWith("/public/")) {
+    relativePath = pathname.slice("/public/".length);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  }
+  // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
+  else if (
+    pathname === "/favicon.ico" ||
+    pathname === "/robots.txt" ||
     pathname === "/sitemap.xml" ||
     pathname === "/manifest.json"
-  ) {
-    // 고정된 파일명만 허용 (이미 위에서 정확히 매칭됨)
-    const filename = path.basename(pathname);
-    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
-    filePath = path.join(allowedBaseDir, filename);
-  } else {
-    return null; // 정적 파일이 아님
-  }
-
-  // 최종 경로 검증: 허용된 디렉토리 내에 있는지 확인
-  if (!isPathSafe(filePath, allowedBaseDir!)) {
-    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
-    return null;
-  }
+  ) {
+    // 고정된 파일명만 허용 (이미 위에서 정확히 매칭됨)
+    relativePath = path.basename(pathname);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  } else {
+    return null; // 정적 파일이 아님
+  }
+
+  // URL 디코딩 (실패 시 차단)
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(relativePath);
+  } catch {
+    return null;
+  }
+
+  // 정규화 + Null byte 방지
+  const normalizedPath = path.posix.normalize(decodedPath);
+  if (normalizedPath.includes("\0")) {
+    console.warn(`[Mandu Security] Null byte attack detected: ${pathname}`);
+    return null;
+  }
+
+  // 선행 슬래시 제거 → path.join이 base를 무시하지 않도록 보장
+  const safeRelativePath = normalizedPath.replace(/^\/+/, "");
+
+  // 상대 경로 탈출 차단
+  if (safeRelativePath.startsWith("..")) {
+    return null;
+  }
+
+  filePath = path.join(allowedBaseDir, safeRelativePath);
+
+  // 최종 경로 검증: 허용된 디렉토리 내에 있는지 확인
+  if (!(await isPathSafe(filePath, allowedBaseDir!))) {
+    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
+    return null;
+  }
 
   try {
     const file = Bun.file(filePath);
@@ -601,52 +650,64 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
 
 // ========== Request Handler ==========
 
-async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
-  const url = new URL(req.url);
-  const pathname = url.pathname;
-  const settings = registry.settings;
-
-  // 0. CORS Preflight 요청 처리
-  if (settings.cors && isPreflightRequest(req)) {
-    const corsOptions = settings.cors === true ? {} : settings.cors;
-    return handlePreflightRequest(req, corsOptions);
-  }
+async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
+  const result = await handleRequestInternal(req, router, registry);
+
+  if (!result.ok) {
+    return errorToResponse(result.error, registry.settings.isDev);
+  }
+
+  return result.value;
+}
+
+async function handleRequestInternal(
+  req: Request,
+  router: Router,
+  registry: ServerRegistry
+): Promise<Result<Response>> {
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+  const settings = registry.settings;
+
+  // 0. CORS Preflight 요청 처리
+  if (settings.cors && isPreflightRequest(req)) {
+    const corsOptions = settings.cors === true ? {} : settings.cors;
+    return ok(handlePreflightRequest(req, corsOptions));
+  }
 
   // 1. 정적 파일 서빙 시도 (최우선)
-  const staticResponse = await serveStaticFile(pathname, settings);
-  if (staticResponse) {
-    // 정적 파일에도 CORS 헤더 적용
-    if (settings.cors && isCorsRequest(req)) {
-      const corsOptions = settings.cors === true ? {} : settings.cors;
-      return applyCorsToResponse(staticResponse, req, corsOptions);
-    }
-    return staticResponse;
-  }
+  const staticResponse = await serveStaticFile(pathname, settings);
+  if (staticResponse) {
+    // 정적 파일에도 CORS 헤더 적용
+    if (settings.cors && isCorsRequest(req)) {
+      const corsOptions = settings.cors === true ? {} : settings.cors;
+      return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+    }
+    return ok(staticResponse);
+  }
 
   // 2. 라우트 매칭
   const match = router.match(pathname);
 
-  if (!match) {
-    const error = createNotFoundResponse(pathname);
-    const response = formatErrorResponse(error, {
-      isDev: process.env.NODE_ENV !== "production",
-    });
-    return Response.json(response, { status: 404 });
-  }
+  if (!match) {
+    return err(createNotFoundResponse(pathname));
+  }
 
   const { route, params } = match;
 
-  if (route.kind === "api") {
-    const handler = registry.apiHandlers.get(route.id);
-    if (!handler) {
-      const error = createHandlerNotFoundResponse(route.id, route.pattern);
-      const response = formatErrorResponse(error, {
-        isDev: process.env.NODE_ENV !== "production",
-      });
-      return Response.json(response, { status: 500 });
-    }
-    return handler(req, params);
-  }
+  if (route.kind === "api") {
+    const handler = registry.apiHandlers.get(route.id);
+    if (!handler) {
+      return err(createHandlerNotFoundResponse(route.id, route.pattern));
+    }
+    try {
+      const response = await handler(req, params);
+      return ok(response);
+    } catch (errValue) {
+      const error = errValue instanceof Error ? errValue : new Error(String(errValue));
+      return err(createSSRErrorResponse(route.id, route.pattern, error));
+    }
+  }
 
   if (route.kind === "page") {
     let loaderData: unknown;
@@ -657,30 +718,27 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
 
     // 1. PageHandler 방식 (신규 - filling 포함)
     const pageHandler = registry.pageHandlers.get(route.id);
-    if (pageHandler) {
-      try {
-        const registration = await pageHandler();
-        component = registration.component as RouteComponent;
-        registry.registerRouteComponent(route.id, component);
+    if (pageHandler) {
+      try {
+        const registration = await pageHandler();
+        component = registration.component as RouteComponent;
+        registry.registerRouteComponent(route.id, component);
 
         // Filling의 loader 실행
         if (registration.filling?.hasLoader()) {
           const ctx = new ManduContext(req, params);
           loaderData = await registration.filling.executeLoader(ctx);
         }
-      } catch (err) {
-        const pageError = createPageLoadErrorResponse(
-          route.id,
-          route.pattern,
-          err instanceof Error ? err : new Error(String(err))
-        );
-        console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
-        const response = formatErrorResponse(pageError, {
-          isDev: process.env.NODE_ENV !== "production",
-        });
-        return Response.json(response, { status: 500 });
-      }
-    }
+      } catch (error) {
+        const pageError = createPageLoadErrorResponse(
+          route.id,
+          route.pattern,
+          error instanceof Error ? error : new Error(String(error))
+        );
+        console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+        return err(pageError);
+      }
+    }
     // 2. PageLoader 방식 (레거시 호환)
     else {
       const loader = registry.pageLoaders.get(route.id);
@@ -700,31 +758,28 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
             const ctx = new ManduContext(req, params);
             loaderData = await filling.executeLoader(ctx);
           }
-        } catch (err) {
-          const pageError = createPageLoadErrorResponse(
-            route.id,
-            route.pattern,
-            err instanceof Error ? err : new Error(String(err))
-          );
-          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
-          const response = formatErrorResponse(pageError, {
-            isDev: process.env.NODE_ENV !== "production",
-          });
-          return Response.json(response, { status: 500 });
-        }
-      }
-    }
+        } catch (error) {
+          const pageError = createPageLoadErrorResponse(
+            route.id,
+            route.pattern,
+            error instanceof Error ? error : new Error(String(error))
+          );
+          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+          return err(pageError);
+        }
+      }
+    }
 
     // Client-side Routing: 데이터만 반환 (JSON)
-    if (isDataRequest) {
-      return Response.json({
-        routeId: route.id,
-        pattern: route.pattern,
-        params,
-        loaderData: loaderData ?? null,
-        timestamp: Date.now(),
-      });
-    }
+    if (isDataRequest) {
+      return ok(Response.json({
+        routeId: route.id,
+        pattern: route.pattern,
+        params,
+        loaderData: loaderData ?? null,
+        timestamp: Date.now(),
+      }));
+    }
 
     // SSR 렌더링
     const defaultAppCreator = createDefaultAppFactory(registry);
@@ -753,12 +808,12 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
         ? route.streaming
         : settings.streaming;
 
-      if (useStreaming) {
-        return await renderStreamingResponse(app, {
-          title: `${route.id} - Mandu`,
-          isDev: settings.isDev,
-          hmrPort: settings.hmrPort,
-          routeId: route.id,
+      if (useStreaming) {
+        return ok(await renderStreamingResponse(app, {
+          title: `${route.id} - Mandu`,
+          isDev: settings.isDev,
+          hmrPort: settings.hmrPort,
+          routeId: route.id,
           routePattern: route.pattern,
           hydration: route.hydration,
           bundleManifest: settings.bundleManifest,
@@ -776,63 +831,61 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
                 allReadyTime: `${metrics.allReadyTime}ms`,
                 hasError: metrics.hasError,
               });
-            }
-          },
-        });
-      }
-
-      // 기존 renderToString 방식
-      return renderSSR(app, {
-        title: `${route.id} - Mandu`,
-        isDev: settings.isDev,
-        hmrPort: settings.hmrPort,
-        routeId: route.id,
+            }
+          },
+        }));
+      }
+
+      // 기존 renderToString 방식
+      return ok(renderSSR(app, {
+        title: `${route.id} - Mandu`,
+        isDev: settings.isDev,
+        hmrPort: settings.hmrPort,
+        routeId: route.id,
         hydration: route.hydration,
         bundleManifest: settings.bundleManifest,
         serverData,
-        // Client-side Routing 활성화 정보 전달
-        enableClientRouter: true,
-        routePattern: route.pattern,
-      });
-    } catch (err) {
-      const ssrError = createSSRErrorResponse(
-        route.id,
-        route.pattern,
-        err instanceof Error ? err : new Error(String(err))
-      );
-      console.error(`[Mandu] ${ssrError.errorType}:`, ssrError.message);
-      const response = formatErrorResponse(ssrError, {
-        isDev: process.env.NODE_ENV !== "production",
-      });
-      return Response.json(response, { status: 500 });
-    }
-  }
-
-  return Response.json({
-    errorType: "FRAMEWORK_BUG",
-    code: "MANDU_F003",
-    message: `Unknown route kind: ${route.kind}`,
-    summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
-    fix: {
-      file: "spec/routes.manifest.json",
-      suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
-    },
-    route: {
-      id: route.id,
-      pattern: route.pattern,
-    },
-    timestamp: new Date().toISOString(),
-  }, { status: 500 });
-}
+        // Client-side Routing 활성화 정보 전달
+        enableClientRouter: true,
+        routePattern: route.pattern,
+      }));
+    } catch (error) {
+      const ssrError = createSSRErrorResponse(
+        route.id,
+        route.pattern,
+        error instanceof Error ? error : new Error(String(error))
+      );
+      console.error(`[Mandu] ${ssrError.errorType}:`, ssrError.message);
+      return err(ssrError);
+    }
+  }
+
+  return err({
+    errorType: "FRAMEWORK_BUG",
+    code: "MANDU_F003",
+    httpStatus: 500,
+    message: `Unknown route kind: ${route.kind}`,
+    summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
+    fix: {
+      file: "spec/routes.manifest.json",
+      suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
+    },
+    route: {
+      id: route.id,
+      pattern: route.pattern,
+    },
+    timestamp: new Date().toISOString(),
+  });
+}
 
 // ========== Server Startup ==========
 
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
-  const {
-    port = 3000,
-    hostname = "localhost",
-    rootDir = process.cwd(),
-    isDev = false,
+  const {
+    port = 3000,
+    hostname = "localhost",
+    rootDir = process.cwd(),
+    isDev = false,
     hmrPort,
     bundleManifest,
     publicDir = "public",
@@ -841,8 +894,15 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     registry = defaultRegistry,
   } = options;
 
-  // CORS 옵션 파싱
-  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
+  // CORS 옵션 파싱
+  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
+
+  if (!isDev && cors === true) {
+    console.warn("⚠️  [Security Warning] CORS is set to allow all origins.");
+    console.warn("   This is not recommended for production environments.");
+    console.warn("   Consider specifying allowed origins explicitly:");
+    console.warn("   cors: { origin: ['https://yourdomain.com'] }");
+  }
 
   // Registry settings 저장
   registry.settings = {
@@ -876,10 +936,10 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   });
 
   if (isDev) {
-    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${port}`);
-    if (hmrPort) {
-      console.log(`🔥 HMR enabled on port ${hmrPort + 1}`);
-    }
+    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${port}`);
+    if (hmrPort) {
+      console.log(`🔥 HMR enabled on port ${hmrPort + PORTS.HMR_OFFSET}`);
+    }
     console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
     if (corsOptions) {
       console.log(`🌐 CORS enabled`);

package/src/runtime/ssr.ts

@@ -3,6 +3,7 @@ import { serializeProps } from "../client/serialize";
 import type { ReactElement } from "react";
 import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
+import { PORTS, TIMEOUTS } from "../constants";
 
 // Re-export streaming SSR utilities
 export {
@@ -270,12 +271,12 @@ function generateClientRouterScript(manifest: BundleManifest): string {
  * HMR 스크립트 생성
  */
 function generateHMRScript(port: number): string {
-  const hmrPort = port + 1;
+  const hmrPort = port + PORTS.HMR_OFFSET;
   return `<script>
 (function() {
   var ws = null;
   var reconnectAttempts = 0;
-  var maxReconnectAttempts = 10;
+  var maxReconnectAttempts = ${TIMEOUTS.HMR_MAX_RECONNECT};
 
   function connect() {
     try {
@@ -298,11 +299,11 @@ function generateHMRScript(port: number): string {
       ws.onclose = function() {
         if (reconnectAttempts < maxReconnectAttempts) {
           reconnectAttempts++;
-          setTimeout(connect, 1000 * reconnectAttempts);
+          setTimeout(connect, ${TIMEOUTS.HMR_RECONNECT_DELAY} * reconnectAttempts);
         }
       };
     } catch(err) {
-      setTimeout(connect, 1000);
+      setTimeout(connect, ${TIMEOUTS.HMR_RECONNECT_DELAY});
     }
   }
   connect();

package/src/runtime/streaming-ssr.ts

@@ -19,6 +19,7 @@ import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { serializeProps } from "../client/serialize";
 import type { Metadata, MetadataItem } from "../seo/types";
 import { injectSEOIntoOptions, resolveSEO, type SEOOptions } from "../seo/integration/ssr";
+import { PORTS, TIMEOUTS } from "../constants";
 
 // ========== Types ==========
 
@@ -564,12 +565,12 @@ function generateDeferredDataScript(routeId: string, key: string, data: unknown)
  * HMR 스크립트 생성
  */
 function generateHMRScript(port: number): string {
-  const hmrPort = port + 1;
+  const hmrPort = port + PORTS.HMR_OFFSET;
   return `<script>
 (function() {
   var ws = null;
   var reconnectAttempts = 0;
-  var maxReconnectAttempts = 10;
+  var maxReconnectAttempts = ${TIMEOUTS.HMR_MAX_RECONNECT};
 
   function connect() {
     try {
@@ -590,11 +591,11 @@ function generateHMRScript(port: number): string {
       ws.onclose = function() {
         if (reconnectAttempts < maxReconnectAttempts) {
           reconnectAttempts++;
-          setTimeout(connect, 1000 * reconnectAttempts);
+          setTimeout(connect, ${TIMEOUTS.HMR_RECONNECT_DELAY} * reconnectAttempts);
         }
       };
     } catch(err) {
-      setTimeout(connect, 1000);
+      setTimeout(connect, ${TIMEOUTS.HMR_RECONNECT_DELAY});
     }
   }
   connect();

package/src/utils/bun.ts

@@ -0,0 +1,8 @@
+export async function readJsonFile(filePath: string): Promise<unknown> {
+  try {
+    return await Bun.file(filePath).json();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse JSON in ${filePath}: ${message}`);
+  }
+}