@mandujs/core 0.9.45 → 0.10.0

package/src/config/symbols.ts

@@ -0,0 +1,144 @@
+/**
+ * Mandu Symbol 상수 정의 🔣
+ *
+ * ont-run의 Symbol 기반 메타데이터 패턴 참고
+ * @see DNA/ont-run/src/config/categorical.ts
+ * @see docs/plans/08_ont-run_adoption_plan.md - 섹션 3.2
+ *
+ * Symbol.for()를 사용하여 전역 심볼 레지스트리에 등록
+ * → 모듈 간에도 동일한 심볼 공유 가능
+ */
+
+// ============================================
+// 메타데이터 심볼
+// ============================================
+
+/**
+ * MCP 서버 상태 메타데이터
+ * - connected, disconnected, error 등
+ */
+export const MCP_SERVER_STATUS = Symbol.for("mandu:mcpServerStatus");
+
+/**
+ * 검증 컨텍스트 메타데이터
+ * - 커스텀 검증 규칙, 에러 메시지 등
+ */
+export const VALIDATION_CONTEXT = Symbol.for("mandu:validationContext");
+
+/**
+ * 스키마 참조 메타데이터
+ * - 다른 스키마/함수 참조
+ */
+export const SCHEMA_REFERENCE = Symbol.for("mandu:schemaReference");
+
+/**
+ * 필드 소스 메타데이터
+ * - 필드 값의 출처 (env, config, default 등)
+ */
+export const FIELD_SOURCE = Symbol.for("mandu:fieldSource");
+
+/**
+ * 민감 정보 마커
+ * - 로깅/출력 시 마스킹 필요
+ */
+export const SENSITIVE_FIELD = Symbol.for("mandu:sensitiveField");
+
+/**
+ * 보호된 필드 마커
+ * - AI 에이전트 수정 불가
+ */
+export const PROTECTED_FIELD = Symbol.for("mandu:protectedField");
+
+/**
+ * 기본값 출처 메타데이터
+ * - 기본값이 어디서 왔는지 추적
+ */
+export const DEFAULT_SOURCE = Symbol.for("mandu:defaultSource");
+
+/**
+ * 런타임 주입 메타데이터
+ * - 런타임에 주입되는 값 표시
+ */
+export const RUNTIME_INJECTED = Symbol.for("mandu:runtimeInjected");
+
+// ============================================
+// 타입 정의
+// ============================================
+
+export interface McpServerStatusMetadata {
+  status: "connected" | "disconnected" | "error" | "unknown";
+  lastChecked?: string;
+  error?: string;
+}
+
+export interface ValidationContextMetadata {
+  customMessage?: string;
+  severity?: "error" | "warning" | "info";
+  autoFix?: boolean;
+}
+
+export interface SchemaReferenceMetadata {
+  type: "mcpServer" | "function" | "schema" | "env";
+  name: string;
+  optional?: boolean;
+}
+
+export interface FieldSourceMetadata {
+  source: "env" | "config" | "default" | "computed" | "injected";
+  key?: string;
+  fallback?: unknown;
+}
+
+export interface SensitiveFieldMetadata {
+  redactIn: ("log" | "diff" | "snapshot")[];
+  mask?: string;
+}
+
+export interface ProtectedFieldMetadata {
+  reason: string;
+  allowedModifiers?: string[];
+}
+
+// ============================================
+// 심볼-타입 매핑
+// ============================================
+
+export type SymbolMetadataMap = {
+  [MCP_SERVER_STATUS]: McpServerStatusMetadata;
+  [VALIDATION_CONTEXT]: ValidationContextMetadata;
+  [SCHEMA_REFERENCE]: SchemaReferenceMetadata;
+  [FIELD_SOURCE]: FieldSourceMetadata;
+  [SENSITIVE_FIELD]: SensitiveFieldMetadata;
+  [PROTECTED_FIELD]: ProtectedFieldMetadata;
+  [DEFAULT_SOURCE]: string;
+  [RUNTIME_INJECTED]: boolean;
+};
+
+// ============================================
+// 심볼 목록 (순회용)
+// ============================================
+
+export const ALL_METADATA_SYMBOLS = [
+  MCP_SERVER_STATUS,
+  VALIDATION_CONTEXT,
+  SCHEMA_REFERENCE,
+  FIELD_SOURCE,
+  SENSITIVE_FIELD,
+  PROTECTED_FIELD,
+  DEFAULT_SOURCE,
+  RUNTIME_INJECTED,
+] as const;
+
+/**
+ * 심볼이 mandu 메타데이터 심볼인지 확인
+ */
+export function isManduMetadataSymbol(sym: symbol): boolean {
+  return ALL_METADATA_SYMBOLS.includes(sym as any);
+}
+
+/**
+ * 심볼 이름 가져오기 (디버깅용)
+ */
+export function getSymbolName(sym: symbol): string | undefined {
+  return sym.description?.replace("mandu:", "");
+}

package/src/contract/index.ts

@@ -10,18 +10,19 @@
 
 export * from "./schema";
 export * from "./types";
-export * from "./validator";
-export * from "./handler";
-export * from "./client";
-export * from "./normalize";
-export * from "./registry";
-export * from "./client-safe";
-
-import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
-import type { ContractHandlers, RouteDefinition } from "./handler";
-import { defineHandler, defineRoute } from "./handler";
-import { createClient, contractFetch, type ClientOptions } from "./client";
-import { createClientContract } from "./client-safe";
+export * from "./validator";
+export * from "./handler";
+export * from "./client";
+export * from "./normalize";
+export * from "./registry";
+export * from "./client-safe";
+export * from "./protection";
+
+import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
+import type { ContractHandlers, RouteDefinition } from "./handler";
+import { defineHandler, defineRoute } from "./handler";
+import { createClient, contractFetch, type ClientOptions } from "./client";
+import { createClientContract } from "./client-safe";
 
 /**
  * Create a Mandu API Contract
@@ -123,7 +124,7 @@ export function createContract<T extends ContractDefinition>(definition: T): T &
  * Contract-specific Mandu functions
  * Note: Use `ManduContract` to avoid conflict with other Mandu exports
  */
-export const ManduContract = {
+export const ManduContract = {
   /**
    * Create a typed Contract
    * Contract 스키마 정의 및 타입 추론
@@ -165,9 +166,9 @@ export const ManduContract = {
    */
   route: defineRoute,
 
-  /**
-   * Create a type-safe API client from contract
-   * Contract 기반 타입 안전 클라이언트 생성
+  /**
+   * Create a type-safe API client from contract
+   * Contract 기반 타입 안전 클라이언트 생성
    *
    * @example
    * ```typescript
@@ -180,13 +181,13 @@ export const ManduContract = {
    * const newUser = await client.POST({ body: { name: "Alice" } });
    * ```
    */
-  client: createClient,
-
-  /**
-   * Create a client-safe contract
-   * Client에서 노출할 스키마만 선택
-   */
-  clientContract: createClientContract,
+  client: createClient,
+
+  /**
+   * Create a client-safe contract
+   * Client에서 노출할 스키마만 선택
+   */
+  clientContract: createClientContract,
 
   /**
    * Single type-safe fetch call
@@ -199,8 +200,8 @@ export const ManduContract = {
    * });
    * ```
    */
-  fetch: contractFetch,
-} as const;
+  fetch: contractFetch,
+} as const;
 
 /**
  * Alias for backward compatibility within contract module

package/src/contract/protection.ts

@@ -0,0 +1,364 @@
+/**
+ * Contract Protection - 보호 필드 시스템
+ *
+ * Symbol 메타데이터를 사용하여 Contract의 민감/보호 필드를 관리
+ *
+ * @see docs/plans/09_lockfile_integration_plan.md
+ */
+
+import { z } from "zod";
+import {
+  isSensitiveField,
+  isProtectedField,
+  getMetadata,
+  PROTECTED_FIELD,
+  SENSITIVE_FIELD,
+  type ProtectedFieldMetadata,
+  type SensitiveFieldMetadata,
+} from "../config";
+
+// ============================================
+// 타입
+// ============================================
+
+export interface ProtectedFieldInfo {
+  /** 필드 경로 (예: "body.password") */
+  path: string;
+  /** 보호 이유 */
+  reason: string;
+  /** 수정 허용 대상 */
+  allowedModifiers: string[];
+  /** 민감 필드 여부 */
+  isSensitive: boolean;
+}
+
+export interface ProtectionViolation {
+  /** 위반 필드 경로 */
+  field: string;
+  /** 보호 이유 */
+  reason: string;
+  /** 오류 메시지 */
+  message: string;
+  /** 수정자 */
+  modifier: string;
+}
+
+export interface ContractChangeValidation {
+  /** 유효 여부 */
+  valid: boolean;
+  /** 보호 위반 목록 */
+  violations: ProtectionViolation[];
+}
+
+// ============================================
+// 보호 필드 추출
+// ============================================
+
+/**
+ * Zod 스키마에서 보호된 필드 목록 추출
+ *
+ * @param schema Zod 스키마
+ * @param basePath 기본 경로 (재귀용)
+ * @returns 보호된 필드 정보 목록
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   apiKey: sensitiveToken(),
+ *   config: z.object({
+ *     secret: protectedField("Security"),
+ *   }),
+ * });
+ *
+ * const fields = extractProtectedFields(schema);
+ * // [
+ * //   { path: "apiKey", reason: "Sensitive token...", ... },
+ * //   { path: "config.secret", reason: "Security", ... },
+ * // ]
+ * ```
+ */
+export function extractProtectedFields(
+  schema: z.ZodType,
+  basePath = ""
+): ProtectedFieldInfo[] {
+  const fields: ProtectedFieldInfo[] = [];
+
+  // ZodObject 처리
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape as Record<string, z.ZodType>;
+
+    for (const [key, value] of Object.entries(shape)) {
+      const currentPath = basePath ? `${basePath}.${key}` : key;
+
+      // 보호된 필드 확인
+      if (isProtectedField(value)) {
+        const meta = getMetadata(value, PROTECTED_FIELD) as ProtectedFieldMetadata | undefined;
+        fields.push({
+          path: currentPath,
+          reason: meta?.reason ?? "Protected field",
+          allowedModifiers: meta?.allowedModifiers ?? ["human"],
+          isSensitive: isSensitiveField(value),
+        });
+      }
+      // 민감 필드도 보호 대상
+      else if (isSensitiveField(value)) {
+        const meta = getMetadata(value, SENSITIVE_FIELD) as SensitiveFieldMetadata | undefined;
+        fields.push({
+          path: currentPath,
+          reason: "Sensitive field - redacted in logs",
+          allowedModifiers: ["human"],
+          isSensitive: true,
+        });
+      }
+
+      // 중첩 객체 재귀 탐색
+      if (value instanceof z.ZodObject) {
+        const nested = extractProtectedFields(value, currentPath);
+        fields.push(...nested);
+      }
+      // Optional 처리
+      else if (value instanceof z.ZodOptional) {
+        const inner = value.unwrap();
+        if (inner instanceof z.ZodObject) {
+          const nested = extractProtectedFields(inner, currentPath);
+          fields.push(...nested);
+        }
+      }
+      // Nullable 처리
+      else if (value instanceof z.ZodNullable) {
+        const inner = value.unwrap();
+        if (inner instanceof z.ZodObject) {
+          const nested = extractProtectedFields(inner, currentPath);
+          fields.push(...nested);
+        }
+      }
+    }
+  }
+
+  return fields;
+}
+
+/**
+ * Contract 스키마 전체에서 보호 필드 추출
+ */
+export function extractContractProtectedFields(
+  contract: { request?: unknown; response?: unknown }
+): {
+  request: ProtectedFieldInfo[];
+  response: ProtectedFieldInfo[];
+} {
+  const request: ProtectedFieldInfo[] = [];
+  const response: ProtectedFieldInfo[] = [];
+
+  // Request 스키마 탐색
+  if (contract.request && typeof contract.request === "object") {
+    for (const [method, schema] of Object.entries(contract.request)) {
+      if (schema && typeof schema === "object") {
+        const methodSchema = schema as Record<string, z.ZodType>;
+
+        // body, query, params, headers
+        for (const [part, partSchema] of Object.entries(methodSchema)) {
+          if (partSchema instanceof z.ZodType) {
+            const fields = extractProtectedFields(partSchema, `${method}.${part}`);
+            request.push(...fields);
+          }
+        }
+      }
+    }
+  }
+
+  // Response 스키마 탐색
+  if (contract.response && typeof contract.response === "object") {
+    for (const [status, schema] of Object.entries(contract.response)) {
+      if (schema instanceof z.ZodType) {
+        const fields = extractProtectedFields(schema, `${status}`);
+        response.push(...fields);
+      }
+    }
+  }
+
+  return { request, response };
+}
+
+// ============================================
+// 변경 검증
+// ============================================
+
+/**
+ * 객체에서 경로로 값 가져오기
+ */
+function getValueByPath(obj: unknown, path: string): unknown {
+  const parts = path.split(".");
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Contract 변경 시 보호 필드 검증
+ *
+ * @param oldSchema 이전 스키마
+ * @param newSchema 새 스키마
+ * @param modifier 수정자 ("human" | "ai")
+ * @returns 검증 결과
+ *
+ * @example
+ * ```typescript
+ * const validation = validateContractChanges(
+ *   oldContract.request,
+ *   newContract.request,
+ *   "ai"
+ * );
+ *
+ * if (!validation.valid) {
+ *   console.error("AI가 보호된 필드를 수정하려고 합니다:", validation.violations);
+ * }
+ * ```
+ */
+export function validateContractChanges(
+  oldSchema: z.ZodType,
+  newSchema: z.ZodType,
+  modifier: "human" | "ai"
+): ContractChangeValidation {
+  const violations: ProtectionViolation[] = [];
+
+  // 이전 스키마에서 보호 필드 추출
+  const protectedFields = extractProtectedFields(oldSchema);
+
+  for (const field of protectedFields) {
+    // 수정 권한 확인
+    if (!field.allowedModifiers.includes(modifier)) {
+      // 스키마 구조 변경 감지 (간단한 비교)
+      const oldValue = getSchemaDefinition(oldSchema, field.path);
+      const newValue = getSchemaDefinition(newSchema, field.path);
+
+      // 구조가 변경되었는지 확인
+      if (hasSchemaChanged(oldValue, newValue)) {
+        violations.push({
+          field: field.path,
+          reason: field.reason,
+          message: `${modifier}는 보호된 필드 '${field.path}'를 수정할 수 없습니다`,
+          modifier,
+        });
+      }
+    }
+  }
+
+  return {
+    valid: violations.length === 0,
+    violations,
+  };
+}
+
+/**
+ * 스키마에서 경로로 정의 가져오기
+ */
+function getSchemaDefinition(schema: z.ZodType, path: string): z.ZodType | undefined {
+  const parts = path.split(".");
+  let current: z.ZodType | undefined = schema;
+
+  for (const part of parts) {
+    if (!current) return undefined;
+
+    if (current instanceof z.ZodObject) {
+      current = current.shape[part] as z.ZodType | undefined;
+    } else if (current instanceof z.ZodOptional) {
+      current = current.unwrap();
+      if (current instanceof z.ZodObject) {
+        current = current.shape[part] as z.ZodType | undefined;
+      }
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+/**
+ * 스키마가 변경되었는지 확인 (간단한 비교)
+ */
+function hasSchemaChanged(
+  oldSchema: z.ZodType | undefined,
+  newSchema: z.ZodType | undefined
+): boolean {
+  // 둘 다 없으면 변경 없음
+  if (!oldSchema && !newSchema) return false;
+
+  // 하나만 있으면 변경됨
+  if (!oldSchema || !newSchema) return true;
+
+  // 타입이 다르면 변경됨
+  const oldTypeName = (oldSchema._def as { typeName?: string }).typeName;
+  const newTypeName = (newSchema._def as { typeName?: string }).typeName;
+  if (oldTypeName !== newTypeName) {
+    return true;
+  }
+
+  // ZodObject의 경우 shape 키 비교
+  if (oldSchema instanceof z.ZodObject && newSchema instanceof z.ZodObject) {
+    const oldKeys = Object.keys(oldSchema.shape);
+    const newKeys = Object.keys(newSchema.shape);
+
+    if (oldKeys.length !== newKeys.length) return true;
+
+    for (const key of oldKeys) {
+      if (!newKeys.includes(key)) return true;
+    }
+  }
+
+  return false;
+}
+
+// ============================================
+// 포맷팅
+// ============================================
+
+/**
+ * 보호 필드 목록을 문자열로 포맷
+ */
+export function formatProtectedFields(fields: ProtectedFieldInfo[]): string {
+  if (fields.length === 0) {
+    return "보호된 필드 없음";
+  }
+
+  const lines: string[] = ["보호된 필드:"];
+
+  for (const field of fields) {
+    const sensitive = field.isSensitive ? " 🔐" : "";
+    lines.push(`  - ${field.path}${sensitive}`);
+    lines.push(`    이유: ${field.reason}`);
+    lines.push(`    수정 가능: ${field.allowedModifiers.join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 보호 위반 목록을 문자열로 포맷
+ */
+export function formatProtectionViolations(violations: ProtectionViolation[]): string {
+  if (violations.length === 0) {
+    return "위반 없음";
+  }
+
+  const lines: string[] = ["🛑 보호 필드 위반:"];
+
+  for (const v of violations) {
+    lines.push(`  - ${v.field}`);
+    lines.push(`    ${v.message}`);
+    lines.push(`    이유: ${v.reason}`);
+  }
+
+  return lines.join("\n");
+}