@mandujs/core 0.9.23 → 0.9.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.23",
+  "version": "0.9.25",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/contract/index.ts

@@ -13,6 +13,7 @@ export * from "./types";
 export * from "./validator";
 export * from "./handler";
 export * from "./client";
+export * from "./normalize";
 
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
 import type { ContractHandlers, RouteDefinition } from "./handler";

package/src/contract/normalize.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Mandu Schema Normalization Tests
+ */
+
+import { describe, test, expect } from "bun:test";
+import { z } from "zod";
+import {
+  normalizeData,
+  safeNormalizeData,
+  normalizeSchema,
+  createCoerceSchema,
+  normalizeRequestData,
+  setNormalizeOptions,
+  resetNormalizeOptions,
+  getNormalizeOptions,
+} from "./normalize";
+
+describe("normalizeData", () => {
+  const schema = z.object({
+    name: z.string(),
+    age: z.number(),
+  });
+
+  test("strip 모드: 정의되지 않은 필드 제거", () => {
+    const input = { name: "Kim", age: 25, admin: true, role: "superuser" };
+    const result = normalizeData(schema, input, { mode: "strip" });
+
+    expect(result).toEqual({ name: "Kim", age: 25 });
+    expect(result).not.toHaveProperty("admin");
+    expect(result).not.toHaveProperty("role");
+  });
+
+  test("strict 모드: 정의되지 않은 필드 있으면 에러", () => {
+    const input = { name: "Kim", age: 25, admin: true };
+
+    expect(() => {
+      normalizeData(schema, input, { mode: "strict" });
+    }).toThrow();
+  });
+
+  test("passthrough 모드: 모든 필드 허용", () => {
+    const input = { name: "Kim", age: 25, admin: true };
+    const result = normalizeData(schema, input, { mode: "passthrough" });
+
+    expect(result).toEqual({ name: "Kim", age: 25, admin: true });
+  });
+
+  test("기본 모드는 strip", () => {
+    resetNormalizeOptions();
+    const input = { name: "Kim", age: 25, extra: "field" };
+    const result = normalizeData(schema, input);
+
+    expect(result).toEqual({ name: "Kim", age: 25 });
+  });
+});
+
+describe("safeNormalizeData", () => {
+  const schema = z.object({
+    name: z.string(),
+    age: z.number(),
+  });
+
+  test("성공 시 success: true와 data 반환", () => {
+    const input = { name: "Kim", age: 25, extra: true };
+    const result = safeNormalizeData(schema, input, { mode: "strip" });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ name: "Kim", age: 25 });
+    }
+  });
+
+  test("실패 시 success: false와 error 반환", () => {
+    const input = { name: "Kim", age: "not a number" };
+    const result = safeNormalizeData(schema, input);
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBeDefined();
+    }
+  });
+});
+
+describe("createCoerceSchema", () => {
+  test("문자열을 숫자로 변환", () => {
+    const schema = z.object({
+      page: z.number(),
+      limit: z.number(),
+    });
+
+    const coerced = createCoerceSchema(schema);
+    const result = coerced.parse({ page: "1", limit: "10" });
+
+    expect(result).toEqual({ page: 1, limit: 10 });
+  });
+
+  test("문자열을 불리언으로 변환", () => {
+    const schema = z.object({
+      active: z.boolean(),
+      verified: z.boolean(),
+    });
+
+    const coerced = createCoerceSchema(schema);
+
+    expect(coerced.parse({ active: "true", verified: "false" })).toEqual({
+      active: true,
+      verified: false,
+    });
+
+    expect(coerced.parse({ active: "1", verified: "0" })).toEqual({
+      active: true,
+      verified: false,
+    });
+  });
+
+  test("optional 필드 처리", () => {
+    const schema = z.object({
+      page: z.number().optional(),
+      sort: z.string().optional(),
+    });
+
+    const coerced = createCoerceSchema(schema);
+
+    expect(coerced.parse({ page: "5" })).toEqual({ page: 5 });
+    expect(coerced.parse({})).toEqual({});
+  });
+
+  test("default 값 처리", () => {
+    const schema = z.object({
+      page: z.number().default(1),
+      limit: z.number().default(10),
+    });
+
+    const coerced = createCoerceSchema(schema);
+
+    expect(coerced.parse({})).toEqual({ page: 1, limit: 10 });
+    expect(coerced.parse({ page: "5" })).toEqual({ page: 5, limit: 10 });
+  });
+
+  test("숫자 제약 조건 유지 (min, max)", () => {
+    const schema = z.object({
+      page: z.number().min(1).max(100),
+    });
+
+    const coerced = createCoerceSchema(schema);
+
+    expect(coerced.parse({ page: "50" })).toEqual({ page: 50 });
+    expect(() => coerced.parse({ page: "0" })).toThrow();
+    expect(() => coerced.parse({ page: "101" })).toThrow();
+  });
+
+  test("배열 요소 변환", () => {
+    const schema = z.object({
+      ids: z.array(z.number()),
+    });
+
+    const coerced = createCoerceSchema(schema);
+
+    expect(coerced.parse({ ids: ["1", "2", "3"] })).toEqual({
+      ids: [1, 2, 3],
+    });
+  });
+});
+
+describe("normalizeRequestData", () => {
+  const schemas = {
+    query: z.object({
+      page: z.number(),
+      limit: z.number(),
+    }),
+    params: z.object({
+      id: z.number(),
+    }),
+    body: z.object({
+      name: z.string(),
+      email: z.string(),
+    }),
+  };
+
+  test("query: coerce + strip 적용", () => {
+    const result = normalizeRequestData(
+      schemas,
+      {
+        query: { page: "1", limit: "10", extra: "field" },
+        params: { id: "123" },
+        body: { name: "Kim", email: "a@b.c" },
+      },
+      { mode: "strip", coerceQueryParams: true }
+    );
+
+    expect(result.query).toEqual({ page: 1, limit: 10 });
+    expect(result.params).toEqual({ id: 123 });
+    expect(result.body).toEqual({ name: "Kim", email: "a@b.c" });
+  });
+
+  test("body: strip 적용 (악의적 필드 제거)", () => {
+    const result = normalizeRequestData(
+      schemas,
+      {
+        body: {
+          name: "Kim",
+          email: "a@b.c",
+          admin: true,
+          role: "superuser",
+        },
+      },
+      { mode: "strip" }
+    );
+
+    expect(result.body).toEqual({ name: "Kim", email: "a@b.c" });
+    expect(result.body).not.toHaveProperty("admin");
+    expect(result.body).not.toHaveProperty("role");
+  });
+});
+
+describe("전역 옵션 설정", () => {
+  test("setNormalizeOptions로 기본 모드 변경", () => {
+    resetNormalizeOptions();
+    expect(getNormalizeOptions().mode).toBe("strip");
+
+    setNormalizeOptions({ mode: "strict" });
+    expect(getNormalizeOptions().mode).toBe("strict");
+
+    resetNormalizeOptions();
+    expect(getNormalizeOptions().mode).toBe("strip");
+  });
+});
+
+describe("보안 시나리오", () => {
+  test("Mass Assignment 공격 방지", () => {
+    const UserSchema = z.object({
+      name: z.string(),
+      email: z.string().email(),
+    });
+
+    // 공격자가 admin 필드를 추가해서 보냄
+    const attackPayload = {
+      name: "Hacker",
+      email: "hacker@evil.com",
+      isAdmin: true,
+      role: "superuser",
+      permissions: ["all"],
+    };
+
+    const result = normalizeData(UserSchema, attackPayload, { mode: "strip" });
+
+    // 정의된 필드만 남음
+    expect(result).toEqual({
+      name: "Hacker",
+      email: "hacker@evil.com",
+    });
+    expect(result).not.toHaveProperty("isAdmin");
+    expect(result).not.toHaveProperty("role");
+    expect(result).not.toHaveProperty("permissions");
+  });
+
+  test("Prototype Pollution 방지", () => {
+    const schema = z.object({
+      name: z.string(),
+    });
+
+    // __proto__ 필드로 공격 시도
+    const attackPayload = {
+      name: "Kim",
+      __proto__: { polluted: true },
+      constructor: { prototype: { hacked: true } },
+    };
+
+    const result = normalizeData(schema, attackPayload, { mode: "strip" });
+
+    expect(result).toEqual({ name: "Kim" });
+    // Object.keys()로 실제 own property 확인 (모든 객체는 __proto__ 접근 가능)
+    expect(Object.keys(result)).toEqual(["name"]);
+    expect(Object.keys(result)).not.toContain("constructor");
+  });
+});

package/src/contract/normalize.ts

@@ -0,0 +1,404 @@
+/**
+ * Mandu Schema Normalization
+ * 스키마 기반 데이터 정규화 (보안 + 타입 안전성)
+ *
+ * 기능:
+ * - Strip: 정의되지 않은 필드 제거 (Mass Assignment 방지)
+ * - Strict: 정의되지 않은 필드 있으면 에러
+ * - Coerce: 타입 자동 변환 (문자열 → 숫자 등)
+ *
+ * @example
+ * ```typescript
+ * import { normalizeData, NormalizeMode } from "@mandujs/core/contract";
+ *
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const input = { name: "Kim", age: 25, admin: true };
+ *
+ * // Strip 모드: 정의된 필드만 추출
+ * const result = normalizeData(schema, input, { mode: "strip" });
+ * // { name: "Kim", age: 25 }
+ * ```
+ */
+
+import { z, type ZodTypeAny, type ZodObject, type ZodRawShape } from "zod";
+
+/**
+ * 정규화 모드
+ * - strip: 정의되지 않은 필드 제거 (기본값, 권장)
+ * - strict: 정의되지 않은 필드 있으면 에러
+ * - passthrough: 모든 필드 허용 (정규화 안 함)
+ */
+export type NormalizeMode = "strip" | "strict" | "passthrough";
+
+/**
+ * 정규화 옵션
+ */
+export interface NormalizeOptions {
+  /**
+   * 정규화 모드
+   * @default "strip"
+   */
+  mode?: NormalizeMode;
+
+  /**
+   * Query/Params의 타입 자동 변환 (coerce) 활성화
+   * URL의 query string과 path params는 항상 문자열이므로
+   * 스키마에 정의된 타입으로 자동 변환
+   * @default true
+   */
+  coerceQueryParams?: boolean;
+
+  /**
+   * 깊은 정규화 (중첩 객체에도 적용)
+   * @default true
+   */
+  deep?: boolean;
+}
+
+/**
+ * 전역 기본 정규화 옵션
+ */
+const DEFAULT_OPTIONS: Required<NormalizeOptions> = {
+  mode: "strip",
+  coerceQueryParams: true,
+  deep: true,
+};
+
+/**
+ * 전역 옵션 설정
+ */
+let globalOptions: Required<NormalizeOptions> = { ...DEFAULT_OPTIONS };
+
+/**
+ * 전역 정규화 옵션 설정
+ *
+ * @example
+ * ```typescript
+ * setNormalizeOptions({
+ *   mode: "strict",
+ *   coerceQueryParams: true,
+ * });
+ * ```
+ */
+export function setNormalizeOptions(options: NormalizeOptions): void {
+  globalOptions = { ...DEFAULT_OPTIONS, ...options };
+}
+
+/**
+ * 현재 전역 옵션 조회
+ */
+export function getNormalizeOptions(): Required<NormalizeOptions> {
+  return { ...globalOptions };
+}
+
+/**
+ * 전역 옵션 초기화
+ */
+export function resetNormalizeOptions(): void {
+  globalOptions = { ...DEFAULT_OPTIONS };
+}
+
+/**
+ * ZodObject 스키마에 정규화 모드 적용
+ *
+ * @param schema - Zod 객체 스키마
+ * @param mode - 정규화 모드
+ * @returns 모드가 적용된 스키마
+ */
+export function applyNormalizeMode<T extends ZodRawShape>(
+  schema: ZodObject<T>,
+  mode: NormalizeMode
+): ZodObject<T> {
+  switch (mode) {
+    case "strip":
+      return schema.strip();
+    case "strict":
+      return schema.strict();
+    case "passthrough":
+      return schema.passthrough();
+    default:
+      return schema.strip();
+  }
+}
+
+/**
+ * 스키마가 ZodObject인지 확인
+ */
+function isZodObject(schema: ZodTypeAny): schema is ZodObject<ZodRawShape> {
+  return schema instanceof z.ZodObject;
+}
+
+/**
+ * 스키마에 정규화 적용
+ * ZodObject가 아닌 경우 원본 반환
+ *
+ * @param schema - Zod 스키마
+ * @param options - 정규화 옵션
+ * @returns 정규화된 스키마
+ */
+export function normalizeSchema<T extends ZodTypeAny>(
+  schema: T,
+  options?: NormalizeOptions
+): T {
+  const opts = { ...globalOptions, ...options };
+
+  if (!isZodObject(schema)) {
+    return schema;
+  }
+
+  return applyNormalizeMode(schema, opts.mode) as T;
+}
+
+/**
+ * 데이터 정규화 실행
+ * 스키마에 정의된 필드만 추출하고 타입 변환
+ *
+ * @param schema - Zod 스키마
+ * @param data - 입력 데이터
+ * @param options - 정규화 옵션
+ * @returns 정규화된 데이터
+ * @throws ZodError - 검증 실패 시
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ *
+ * // Strip 모드 (기본)
+ * normalizeData(schema, { name: "Kim", age: 25, admin: true });
+ * // → { name: "Kim", age: 25 }
+ *
+ * // Strict 모드
+ * normalizeData(schema, { name: "Kim", age: 25, admin: true }, { mode: "strict" });
+ * // → ZodError: Unrecognized key(s) in object: 'admin'
+ * ```
+ */
+export function normalizeData<T extends ZodTypeAny>(
+  schema: T,
+  data: unknown,
+  options?: NormalizeOptions
+): z.infer<T> {
+  const normalizedSchema = normalizeSchema(schema, options);
+  return normalizedSchema.parse(data);
+}
+
+/**
+ * 안전한 데이터 정규화 (에러 시 null 반환)
+ *
+ * @param schema - Zod 스키마
+ * @param data - 입력 데이터
+ * @param options - 정규화 옵션
+ * @returns 정규화 결과
+ */
+export function safeNormalizeData<T extends ZodTypeAny>(
+  schema: T,
+  data: unknown,
+  options?: NormalizeOptions
+): {
+  success: true;
+  data: z.infer<T>;
+} | {
+  success: false;
+  error: z.ZodError;
+} {
+  const normalizedSchema = normalizeSchema(schema, options);
+  const result = normalizedSchema.safeParse(data);
+
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+
+  return { success: false, error: result.error };
+}
+
+/**
+ * Query/Params용 coerce 스키마 생성
+ * URL에서 오는 값은 항상 문자열이므로 자동 변환 필요
+ *
+ * @example
+ * ```typescript
+ * // 원본 스키마
+ * const schema = z.object({
+ *   page: z.number(),
+ *   active: z.boolean(),
+ * });
+ *
+ * // Coerce 적용
+ * const coercedSchema = createCoerceSchema(schema);
+ * coercedSchema.parse({ page: "1", active: "true" });
+ * // → { page: 1, active: true }
+ * ```
+ */
+export function createCoerceSchema<T extends ZodRawShape>(
+  schema: ZodObject<T>
+): ZodObject<T> {
+  const shape = schema.shape;
+  const coercedShape: Record<string, ZodTypeAny> = {};
+
+  for (const [key, value] of Object.entries(shape)) {
+    coercedShape[key] = applyCoercion(value as ZodTypeAny);
+  }
+
+  return z.object(coercedShape as T);
+}
+
+/**
+ * 단일 스키마에 coercion 적용
+ */
+function applyCoercion(schema: ZodTypeAny): ZodTypeAny {
+  // ZodNumber → z.coerce.number()
+  if (schema instanceof z.ZodNumber) {
+    let coerced = z.coerce.number();
+    // 기존 체크 유지 (min, max 등)
+    const checks = (schema as any)._def.checks || [];
+    for (const check of checks) {
+      switch (check.kind) {
+        case "min":
+          coerced = check.inclusive
+            ? coerced.gte(check.value)
+            : coerced.gt(check.value);
+          break;
+        case "max":
+          coerced = check.inclusive
+            ? coerced.lte(check.value)
+            : coerced.lt(check.value);
+          break;
+        case "int":
+          coerced = coerced.int();
+          break;
+      }
+    }
+    return coerced;
+  }
+
+  // ZodBoolean → z.coerce.boolean() 또는 커스텀 변환
+  if (schema instanceof z.ZodBoolean) {
+    // "true", "false", "1", "0" 처리
+    return z.preprocess((val) => {
+      if (typeof val === "string") {
+        if (val === "true" || val === "1") return true;
+        if (val === "false" || val === "0") return false;
+      }
+      return val;
+    }, z.boolean());
+  }
+
+  // ZodBigInt → z.coerce.bigint()
+  if (schema instanceof z.ZodBigInt) {
+    return z.coerce.bigint();
+  }
+
+  // ZodDate → z.coerce.date()
+  if (schema instanceof z.ZodDate) {
+    return z.coerce.date();
+  }
+
+  // ZodOptional → 내부 스키마에 coercion 적용
+  if (schema instanceof z.ZodOptional) {
+    return applyCoercion((schema as any)._def.innerType).optional();
+  }
+
+  // ZodDefault → 내부 스키마에 coercion 적용
+  if (schema instanceof z.ZodDefault) {
+    const inner = applyCoercion((schema as any)._def.innerType);
+    return inner.default((schema as any)._def.defaultValue());
+  }
+
+  // ZodNullable → 내부 스키마에 coercion 적용
+  if (schema instanceof z.ZodNullable) {
+    return applyCoercion((schema as any)._def.innerType).nullable();
+  }
+
+  // ZodArray → 배열 요소에 coercion 적용 (쿼리스트링 배열)
+  if (schema instanceof z.ZodArray) {
+    return z.array(applyCoercion((schema as any)._def.type));
+  }
+
+  // 그 외는 원본 반환
+  return schema;
+}
+
+/**
+ * Request 데이터 전체 정규화
+ * query, body, params, headers 각각에 적절한 정규화 적용
+ */
+export interface NormalizedRequestData {
+  query?: unknown;
+  body?: unknown;
+  params?: unknown;
+  headers?: unknown;
+}
+
+export interface RequestSchemas {
+  query?: ZodTypeAny;
+  body?: ZodTypeAny;
+  params?: ZodTypeAny;
+  headers?: ZodTypeAny;
+}
+
+/**
+ * Request 데이터 정규화
+ * - query/params: coerce 적용 (문자열 → 숫자 등)
+ * - body: strip/strict 모드 적용
+ * - headers: 그대로 검증
+ *
+ * @param schemas - 각 필드별 스키마
+ * @param data - 원본 데이터
+ * @param options - 정규화 옵션
+ * @returns 정규화된 데이터
+ */
+export function normalizeRequestData(
+  schemas: RequestSchemas,
+  data: NormalizedRequestData,
+  options?: NormalizeOptions
+): NormalizedRequestData {
+  const opts = { ...globalOptions, ...options };
+  const result: NormalizedRequestData = {};
+
+  // Query: coerce + strip
+  if (schemas.query && data.query !== undefined) {
+    let querySchema = schemas.query;
+
+    // coerce 적용
+    if (opts.coerceQueryParams && isZodObject(querySchema)) {
+      querySchema = createCoerceSchema(querySchema);
+    }
+
+    // strip/strict 적용
+    querySchema = normalizeSchema(querySchema, opts);
+
+    result.query = querySchema.parse(data.query);
+  }
+
+  // Params: coerce + strip
+  if (schemas.params && data.params !== undefined) {
+    let paramsSchema = schemas.params;
+
+    // coerce 적용
+    if (opts.coerceQueryParams && isZodObject(paramsSchema)) {
+      paramsSchema = createCoerceSchema(paramsSchema);
+    }
+
+    // strip/strict 적용
+    paramsSchema = normalizeSchema(paramsSchema, opts);
+
+    result.params = paramsSchema.parse(data.params);
+  }
+
+  // Body: strip/strict만 적용 (coerce 안 함 - JSON은 타입 보존)
+  if (schemas.body && data.body !== undefined) {
+    const bodySchema = normalizeSchema(schemas.body, opts);
+    result.body = bodySchema.parse(data.body);
+  }
+
+  // Headers: 검증만 (정규화 안 함)
+  if (schemas.headers && data.headers !== undefined) {
+    result.headers = schemas.headers.parse(data.headers);
+  }
+
+  return result;
+}
+
+/**
+ * 타입 유틸리티: 정규화된 데이터 타입 추론
+ */
+export type NormalizedData<T extends ZodTypeAny> = z.infer<T>;