@mandujs/core 0.9.46 → 0.11.0

package/src/plugins/types.ts

@@ -0,0 +1,363 @@
+/**
+ * DNA-001: Plugin Adapter Pattern - Core Types
+ *
+ * 플러그인 시스템의 핵심 인터페이스 정의
+ * - 타입 안전한 플러그인 등록
+ * - 설정 스키마 검증
+ * - 라이프사이클 훅
+ */
+
+import type { z, ZodSchema } from "zod";
+
+/**
+ * 플러그인 카테고리
+ */
+export type PluginCategory =
+  | "guard-preset"    // Guard 아키텍처 프리셋
+  | "build"           // 빌드 플러그인 (analyzer, minifier)
+  | "logger"          // 로깅 전송
+  | "mcp-tool"        // MCP 도구 확장
+  | "middleware"      // 글로벌 미들웨어
+  | "custom";         // 사용자 정의
+
+/**
+ * 플러그인 메타데이터
+ */
+export interface PluginMeta {
+  /** 고유 ID (예: "guard-preset-fsd", "build-analyzer") */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 설명 */
+  description?: string;
+
+  /** 버전 (semver) */
+  version: string;
+
+  /** 카테고리 */
+  category: PluginCategory;
+
+  /** 작성자 */
+  author?: string;
+
+  /** 저장소 URL */
+  repository?: string;
+
+  /** 태그 (검색용) */
+  tags?: string[];
+}
+
+/**
+ * 플러그인 API - 플러그인이 프레임워크와 상호작용하는 인터페이스
+ */
+export interface PluginApi {
+  /**
+   * Guard 프리셋 등록
+   */
+  registerGuardPreset: (preset: GuardPresetPlugin) => void;
+
+  /**
+   * 빌드 플러그인 등록
+   */
+  registerBuildPlugin: (plugin: BuildPlugin) => void;
+
+  /**
+   * 로거 전송 등록
+   */
+  registerLoggerTransport: (transport: LoggerTransportPlugin) => void;
+
+  /**
+   * MCP 도구 등록
+   */
+  registerMcpTool: (tool: McpToolPlugin) => void;
+
+  /**
+   * 미들웨어 등록
+   */
+  registerMiddleware: (middleware: MiddlewarePlugin) => void;
+
+  /**
+   * 설정 가져오기
+   */
+  getConfig: <T>(key: string) => T | undefined;
+
+  /**
+   * 로거
+   */
+  logger: {
+    debug: (msg: string, data?: unknown) => void;
+    info: (msg: string, data?: unknown) => void;
+    warn: (msg: string, data?: unknown) => void;
+    error: (msg: string, data?: unknown) => void;
+  };
+}
+
+/**
+ * 플러그인 라이프사이클 훅
+ */
+export interface PluginHooks {
+  /**
+   * 플러그인 로드 시 (설정 검증 후)
+   */
+  onLoad?: () => void | Promise<void>;
+
+  /**
+   * 플러그인 언로드 시
+   */
+  onUnload?: () => void | Promise<void>;
+
+  /**
+   * 서버 시작 시
+   */
+  onServerStart?: () => void | Promise<void>;
+
+  /**
+   * 서버 종료 시
+   */
+  onServerStop?: () => void | Promise<void>;
+}
+
+/**
+ * 기본 플러그인 인터페이스
+ */
+export interface Plugin<TConfig = unknown> extends PluginHooks {
+  /** 플러그인 메타데이터 */
+  meta: PluginMeta;
+
+  /** 설정 스키마 (Zod) */
+  configSchema?: ZodSchema<TConfig>;
+
+  /**
+   * 플러그인 등록 함수
+   * @param api - 플러그인 API
+   * @param config - 검증된 설정
+   */
+  register: (api: PluginApi, config: TConfig) => void | Promise<void>;
+}
+
+// ============================================================================
+// 카테고리별 플러그인 타입
+// ============================================================================
+
+/**
+ * Guard 프리셋 플러그인
+ */
+export interface GuardPresetPlugin {
+  /** 프리셋 ID (예: "fsd", "clean", "hexagonal") */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 설명 */
+  description?: string;
+
+  /**
+   * 프리셋 규칙 정의
+   * @returns 규칙 배열
+   */
+  getRules: () => GuardRule[];
+
+  /**
+   * 레이어 정의 (있는 경우)
+   */
+  getLayers?: () => LayerDefinition[];
+}
+
+/**
+ * Guard 규칙
+ */
+export interface GuardRule {
+  id: string;
+  name: string;
+  description?: string;
+  severity: "error" | "warn" | "off";
+  check: (context: GuardRuleContext) => GuardViolation[];
+}
+
+/**
+ * Guard 규칙 실행 컨텍스트
+ */
+export interface GuardRuleContext {
+  filePath: string;
+  sourceCode: string;
+  imports: ImportInfo[];
+  exports: ExportInfo[];
+  projectRoot: string;
+}
+
+/**
+ * Import 정보
+ */
+export interface ImportInfo {
+  source: string;
+  specifiers: string[];
+  isTypeOnly: boolean;
+  line: number;
+}
+
+/**
+ * Export 정보
+ */
+export interface ExportInfo {
+  name: string;
+  isDefault: boolean;
+  isTypeOnly: boolean;
+  line: number;
+}
+
+/**
+ * Guard 위반
+ */
+export interface GuardViolation {
+  ruleId: string;
+  message: string;
+  severity: "error" | "warn";
+  filePath: string;
+  line?: number;
+  column?: number;
+  fix?: {
+    description: string;
+    replacement?: string;
+  };
+}
+
+/**
+ * 레이어 정의
+ */
+export interface LayerDefinition {
+  name: string;
+  pattern: string | RegExp;
+  allowedDependencies: string[];
+}
+
+/**
+ * 빌드 플러그인
+ */
+export interface BuildPlugin {
+  /** 플러그인 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /**
+   * 빌드 전 훅
+   */
+  onBuildStart?: (context: BuildContext) => void | Promise<void>;
+
+  /**
+   * 번들 처리
+   */
+  transform?: (code: string, id: string) => string | null | Promise<string | null>;
+
+  /**
+   * 빌드 후 훅
+   */
+  onBuildEnd?: (context: BuildContext, result: BuildResult) => void | Promise<void>;
+}
+
+/**
+ * 빌드 컨텍스트
+ */
+export interface BuildContext {
+  outDir: string;
+  minify: boolean;
+  sourcemap: boolean;
+  mode: "development" | "production";
+}
+
+/**
+ * 빌드 결과
+ */
+export interface BuildResult {
+  success: boolean;
+  outputFiles: string[];
+  errors?: string[];
+  stats?: {
+    duration: number;
+    totalSize: number;
+  };
+}
+
+/**
+ * 로거 전송 플러그인
+ */
+export interface LoggerTransportPlugin {
+  /** 전송 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /**
+   * 로그 전송
+   */
+  send: (entry: LogEntry) => void | Promise<void>;
+
+  /**
+   * 배치 전송 (옵션)
+   */
+  sendBatch?: (entries: LogEntry[]) => void | Promise<void>;
+
+  /**
+   * 종료 시 플러시
+   */
+  flush?: () => void | Promise<void>;
+}
+
+/**
+ * 로그 항목
+ */
+export interface LogEntry {
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  timestamp: Date;
+  data?: unknown;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * MCP 도구 플러그인
+ */
+export interface McpToolPlugin {
+  /** 도구 이름 */
+  name: string;
+
+  /** 설명 */
+  description: string;
+
+  /**
+   * 입력 스키마 (JSON Schema)
+   */
+  inputSchema: Record<string, unknown>;
+
+  /**
+   * 도구 실행
+   */
+  execute: (input: unknown) => unknown | Promise<unknown>;
+}
+
+/**
+ * 미들웨어 플러그인
+ */
+export interface MiddlewarePlugin {
+  /** 미들웨어 ID */
+  id: string;
+
+  /** 표시 이름 */
+  name: string;
+
+  /** 실행 순서 (낮을수록 먼저) */
+  order?: number;
+
+  /**
+   * 미들웨어 함수
+   */
+  handler: (
+    request: Request,
+    next: () => Promise<Response>
+  ) => Response | Promise<Response>;
+}

package/src/runtime/security.ts

@@ -0,0 +1,155 @@
+/**
+ * Runtime Security
+ *
+ * 동적 import 및 경로 접근 보안 검증
+ */
+
+import path from "path";
+import type { Result } from "../error/result";
+import { ok, err } from "../error/result";
+import { SecurityError } from "../error/domains";
+
+/**
+ * 허용된 import 경로 패턴
+ */
+const ALLOWED_IMPORT_PATTERNS = [
+  /^app\//,           // app/ 디렉토리 (FS Routes)
+  /^src\/client\//,   // 클라이언트 코드
+  /^src\/server\//,   // 서버 코드
+  /^src\/shared\//,   // 공유 코드
+  /^spec\//,          // Spec 디렉토리 (레거시)
+];
+
+/**
+ * 허용된 파일 확장자
+ */
+const ALLOWED_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs"];
+
+/**
+ * 차단된 경로 패턴
+ */
+const BLOCKED_PATTERNS = [
+  /node_modules/,     // node_modules 직접 접근 차단
+  /\.env/,            // 환경 변수 파일
+  /\.git/,            // Git 디렉토리
+  /\.mandu\/.*\.json$/, // 설정 파일
+];
+
+/**
+ * 동적 import 경로 검증
+ *
+ * @param rootDir 프로젝트 루트 디렉토리
+ * @param modulePath 상대 모듈 경로 (예: "app/layout.tsx")
+ * @returns 검증된 전체 경로 또는 에러
+ */
+export function validateImportPath(
+  rootDir: string,
+  modulePath: string
+): Result<string> {
+  // 1. 경로 정규화
+  const normalized = path.posix.normalize(modulePath).replace(/\\/g, "/");
+
+  // 2. Path traversal 체크
+  if (normalized.includes("..")) {
+    return err(
+      new SecurityError(
+        "path_traversal",
+        `경로 탐색 공격 감지: ${modulePath}`,
+        modulePath
+      ).toManduError()
+    );
+  }
+
+  // 3. 차단된 패턴 체크
+  for (const pattern of BLOCKED_PATTERNS) {
+    if (pattern.test(normalized)) {
+      return err(
+        new SecurityError(
+          "import_violation",
+          `차단된 경로 접근: ${modulePath}`,
+          modulePath
+        ).toManduError()
+      );
+    }
+  }
+
+  // 4. 화이트리스트 검증
+  const isAllowed = ALLOWED_IMPORT_PATTERNS.some((pattern) =>
+    pattern.test(normalized)
+  );
+
+  if (!isAllowed) {
+    return err(
+      new SecurityError(
+        "import_violation",
+        `허용되지 않은 import 경로: ${modulePath}. 허용된 경로: app/, src/client/, src/server/, src/shared/, spec/`,
+        modulePath
+      ).toManduError()
+    );
+  }
+
+  // 5. 확장자 검증 (있는 경우만)
+  const ext = path.extname(normalized);
+  if (ext && !ALLOWED_EXTENSIONS.includes(ext)) {
+    return err(
+      new SecurityError(
+        "import_violation",
+        `허용되지 않은 파일 확장자: ${ext}`,
+        modulePath
+      ).toManduError()
+    );
+  }
+
+  // 6. 전체 경로 생성
+  const fullPath = path.join(rootDir, normalized);
+
+  // 7. 최종 경로가 rootDir 내에 있는지 확인
+  const resolvedPath = path.resolve(fullPath);
+  const resolvedRoot = path.resolve(rootDir);
+
+  if (!resolvedPath.startsWith(resolvedRoot + path.sep)) {
+    return err(
+      new SecurityError(
+        "path_traversal",
+        `루트 디렉토리 외부 접근 시도: ${modulePath}`,
+        modulePath
+      ).toManduError()
+    );
+  }
+
+  return ok(fullPath);
+}
+
+/**
+ * 안전한 동적 import
+ *
+ * @param rootDir 프로젝트 루트 디렉토리
+ * @param modulePath 상대 모듈 경로
+ * @returns 로드된 모듈 또는 null
+ */
+export async function safeImport<T = unknown>(
+  rootDir: string,
+  modulePath: string
+): Promise<T | null> {
+  const validation = validateImportPath(rootDir, modulePath);
+
+  if (!validation.ok) {
+    console.error(`[Mandu Security] ${validation.error.message}`);
+    return null;
+  }
+
+  try {
+    const module = await import(validation.value);
+    return module as T;
+  } catch (error) {
+    console.error(`[Mandu] Failed to import: ${modulePath}`, error);
+    return null;
+  }
+}
+
+/**
+ * 모듈 경로 검증 (boolean 반환)
+ */
+export function isValidImportPath(rootDir: string, modulePath: string): boolean {
+  return validateImportPath(rootDir, modulePath).ok;
+}