@withwiz/toolkit 0.1.0

package/dist/utils/error-processor.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ErrorProcessor - 중앙 집중식 에러 처리
+ *
+ * API 라우트와 미들웨어에서 발생하는 모든 에러를 일관되게 처리합니다.
+ * 5자리 HTTP 확장 에러 코드 체계를 사용합니다.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import type { ISerializedError } from '@withwiz/error/app-error';
+export type ProcessedError = ISerializedError;
+/**
+ * 에러 핸들링 옵션
+ */
+export interface IErrorHandlerOptions {
+    /** 커스텀 에러 핸들러 함수 */
+    customErrorHandler?: (error: unknown, request: NextRequest) => NextResponse;
+    /** 커스텀 응답 보존 여부 (기본값: false) */
+    preserveCustomResponses?: boolean;
+    /** 에러 로깅 레벨 (기본값: 'error') */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    /** 민감한 정보 마스킹 여부 (기본값: true) */
+    maskSensitiveInfo?: boolean;
+}
+/**
+ * 중앙 에러 처리기
+ */
+export declare class ErrorProcessor {
+    /**
+     * 에러를 처리하여 표준화된 응답으로 변환
+     */
+    static process(error: unknown): ProcessedError;
+    /**
+     * Zod 검증 에러 처리
+     */
+    private static handleZodError;
+    /**
+     * Prisma 에러 추출 및 처리
+     */
+    private static extractPrismaError;
+    /**
+     * 에러를 NextResponse로 변환
+     */
+    static toResponse(error: unknown, requestPath?: string): NextResponse;
+    /**
+     * 에러 핸들러 래퍼 함수 (간단한 버전)
+     * try-catch 블록을 대체하여 사용
+     */
+    static withErrorHandling<T extends (...args: unknown[]) => Promise<NextResponse>>(handler: T): T;
+}
+/**
+ * 에러 핸들링 미들웨어 (고급 버전)
+ * 로깅, 민감 정보 마스킹 등 추가 기능 제공
+ */
+export declare function withErrorHandling<T extends unknown[], TRequest extends NextRequest = NextRequest>(handler: (request: TRequest, ...args: T) => Promise<NextResponse>, options?: IErrorHandlerOptions): (request: TRequest, ...args: T) => Promise<NextResponse>;
+/**
+ * Prisma 에러 처리 헬퍼
+ */
+export declare function handlePrismaError(error: unknown): NextResponse;
+/**
+ * 비즈니스 로직 에러를 위한 헬퍼들
+ */
+export declare function throwBusinessRuleError(message?: string, code?: number): never;
+export declare function throwNotFoundError(message?: string, code?: number): never;
+export declare function throwConflictError(message?: string, code?: number): never;
+export declare function throwForbiddenError(message?: string, code?: number): never;
+export declare function throwUnauthorizedError(message?: string, code?: number): never;
+export declare function throwValidationError(message?: string, code?: number): never;
+export declare function throwBadRequestError(message?: string, code?: number): never;
+export declare const processError: typeof ErrorProcessor.process;
+export declare const errorToResponse: typeof ErrorProcessor.toResponse;
+export default ErrorProcessor;

package/dist/utils/error-processor.js

@@ -0,0 +1,34 @@
+import {
+  ErrorProcessor,
+  errorToResponse,
+  error_processor_default,
+  handlePrismaError,
+  processError,
+  throwBadRequestError,
+  throwBusinessRuleError,
+  throwConflictError,
+  throwForbiddenError,
+  throwNotFoundError,
+  throwUnauthorizedError,
+  throwValidationError,
+  withErrorHandling
+} from "../chunk-XPASCCUA.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  ErrorProcessor,
+  error_processor_default as default,
+  errorToResponse,
+  handlePrismaError,
+  processError,
+  throwBadRequestError,
+  throwBusinessRuleError,
+  throwConflictError,
+  throwForbiddenError,
+  throwNotFoundError,
+  throwUnauthorizedError,
+  throwValidationError,
+  withErrorHandling
+};

package/dist/utils/format-number.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 숫자를 포맷팅하여 표시합니다.
+ * - 999,999 이하: 그대로 표시 (예: 999,999)
+ * - 1,000,000 ~ 9,999,999: 그대로 표시 (예: 1,234,567)
+ * - 10,000,000 이상: 줄여서 표시 (예: 10.5M)
+ *
+ * @param num - 포맷팅할 숫자
+ * @returns 포맷팅된 문자열
+ */
+export declare function formatNumber(num: number | string | null | undefined): string;
+/**
+ * 차트용 숫자 포맷팅 함수
+ *
+ * @param num - 포맷팅할 숫자
+ * @returns 포맷팅된 문자열
+ */
+export declare function formatChartNumber(num: number | null | undefined): string;

package/dist/utils/format-number.js

@@ -0,0 +1,9 @@
+import {
+  formatChartNumber,
+  formatNumber
+} from "../chunk-TDZJ6SAI.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  formatChartNumber,
+  formatNumber
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @withwiz/utils
+ *
+ * 범용 유틸리티 모듈
+ * 프로젝트 독립적인 재사용 가능한 유틸리티 함수들
+ */
+export * from './sanitizer';
+export { ErrorProcessor, withErrorHandling, handlePrismaError, throwBusinessRuleError, throwNotFoundError, throwConflictError, throwForbiddenError, throwUnauthorizedError, throwValidationError, throwBadRequestError, processError, errorToResponse, } from './error-processor';
+export type { IErrorHandlerOptions, ProcessedError } from './error-processor';
+export * from './csv-export';
+export * from './cors';
+export * from './api-helpers';
+export * from './type-guards';

package/dist/utils/index.js

@@ -0,0 +1,160 @@
+import {
+  removeEventHandlers,
+  sanitizeArray,
+  sanitizeHtml,
+  sanitizeInput,
+  sanitizeObjectFields,
+  sanitizeUrl
+} from "../chunk-SR65BF6X.js";
+import {
+  isApiErrorResponse,
+  isApiSuccessResponse,
+  isArray,
+  isBoolean,
+  isDateParseable,
+  isDefined,
+  isEmpty,
+  isEmptyArray,
+  isEmptyObject,
+  isEmptyString,
+  isFunction,
+  isIPAddress,
+  isIPv4,
+  isIPv6,
+  isISODateString,
+  isJSONSerializable,
+  isNotNull,
+  isNumber,
+  isObject,
+  isPresent,
+  isSortOrder,
+  isString,
+  isValidDate,
+  isValidEmail,
+  isValidJSON,
+  isValidUrl
+} from "../chunk-EUQATJLI.js";
+import {
+  getAllowedOrigins,
+  getCorsConfig,
+  initCorsConfig,
+  isOriginAllowed,
+  setCorsHeaders,
+  withCORS,
+  withPublicCORS,
+  withRestrictedCORS
+} from "../chunk-GCZOXUDV.js";
+import {
+  boolFormatter,
+  createCsvHeader,
+  createSimpleCsvResponse,
+  createStreamingCsvResponse,
+  dateFormatter,
+  escapeCsvField,
+  rowToCsv
+} from "../chunk-BKGVSC6S.js";
+import {
+  ErrorProcessor,
+  errorToResponse,
+  handlePrismaError,
+  processError,
+  throwBadRequestError,
+  throwBusinessRuleError,
+  throwConflictError,
+  throwForbiddenError,
+  throwNotFoundError,
+  throwUnauthorizedError,
+  throwValidationError,
+  withErrorHandling
+} from "../chunk-XPASCCUA.js";
+import {
+  createPaginatedResponse,
+  getReferer,
+  getSearchParam,
+  getUserAgent,
+  parseBooleanParam,
+  parseFilters,
+  parseNumberParam,
+  parsePagination,
+  parseRequestBody,
+  parseSort,
+  requireAdmin,
+  validateAndParse
+} from "../chunk-2KAPUVIS.js";
+import "../chunk-MLGO3HLS.js";
+import "../chunk-Y3OTJH2S.js";
+import "../chunk-EZR55KV2.js";
+import "../chunk-ORMEWXMH.js";
+export {
+  ErrorProcessor,
+  boolFormatter,
+  createCsvHeader,
+  createPaginatedResponse,
+  createSimpleCsvResponse,
+  createStreamingCsvResponse,
+  dateFormatter,
+  errorToResponse,
+  escapeCsvField,
+  getAllowedOrigins,
+  getCorsConfig,
+  getReferer,
+  getSearchParam,
+  getUserAgent,
+  handlePrismaError,
+  initCorsConfig,
+  isApiErrorResponse,
+  isApiSuccessResponse,
+  isArray,
+  isBoolean,
+  isDateParseable,
+  isDefined,
+  isEmpty,
+  isEmptyArray,
+  isEmptyObject,
+  isEmptyString,
+  isFunction,
+  isIPAddress,
+  isIPv4,
+  isIPv6,
+  isISODateString,
+  isJSONSerializable,
+  isNotNull,
+  isNumber,
+  isObject,
+  isOriginAllowed,
+  isPresent,
+  isSortOrder,
+  isString,
+  isValidDate,
+  isValidEmail,
+  isValidJSON,
+  isValidUrl,
+  parseBooleanParam,
+  parseFilters,
+  parseNumberParam,
+  parsePagination,
+  parseRequestBody,
+  parseSort,
+  processError,
+  removeEventHandlers,
+  requireAdmin,
+  rowToCsv,
+  sanitizeArray,
+  sanitizeHtml,
+  sanitizeInput,
+  sanitizeObjectFields,
+  sanitizeUrl,
+  setCorsHeaders,
+  throwBadRequestError,
+  throwBusinessRuleError,
+  throwConflictError,
+  throwForbiddenError,
+  throwNotFoundError,
+  throwUnauthorizedError,
+  throwValidationError,
+  validateAndParse,
+  withCORS,
+  withErrorHandling,
+  withPublicCORS,
+  withRestrictedCORS
+};

package/dist/utils/input-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 입력 검증 유틸리티
+ *
+ * XSS, SQL Injection, Path Traversal 등 보안 위협을 방어합니다.
+ */
+/**
+ * URL 검증 옵션
+ */
+export interface URLValidationOptions {
+    allowedSchemes?: string[];
+    maxLength?: number;
+    requireProtocol?: boolean;
+}
+/**
+ * URL 안전성 검증
+ *
+ * @param url - 검증할 URL
+ * @param options - 검증 옵션
+ * @returns 검증 결과 { valid: boolean, error?: string, sanitized?: string }
+ */
+export declare function validateURL(url: string, options?: URLValidationOptions): {
+    valid: boolean;
+    error?: string;
+    sanitized?: string;
+};
+/**
+ * XSS 방지: HTML 특수 문자 이스케이프
+ *
+ * @param input - 이스케이프할 문자열
+ * @returns 이스케이프된 문자열
+ */
+export declare function escapeHTML(input: string): string;
+/**
+ * XSS 패턴 탐지
+ *
+ * @param input - 검증할 문자열
+ * @returns XSS 패턴 발견 시 true
+ */
+export declare function detectXSS(input: string): boolean;
+/**
+ * Path Traversal 공격 탐지
+ *
+ * @param input - 검증할 경로
+ * @returns Path Traversal 패턴 발견 시 true
+ */
+export declare function detectPathTraversal(input: string): boolean;
+/**
+ * SQL Injection 패턴 탐지
+ *
+ * @param input - 검증할 문자열
+ * @returns SQL Injection 패턴 발견 시 true
+ */
+export declare function detectSQLInjection(input: string): boolean;
+/**
+ * 입력 문자열 정제
+ *
+ * @param input - 정제할 문자열
+ * @param options - 정제 옵션
+ * @returns 정제된 문자열
+ */
+export declare function sanitizeInput(input: string, options?: {
+    maxLength?: number;
+    allowHTML?: boolean;
+    trim?: boolean;
+}): string;
+/**
+ * 파일 이름 검증
+ *
+ * @param filename - 검증할 파일 이름
+ * @returns 검증 결과
+ */
+export declare function validateFilename(filename: string): {
+    valid: boolean;
+    error?: string;
+    sanitized?: string;
+};
+/**
+ * 종합 입력 검증
+ *
+ * @param input - 검증할 입력
+ * @param type - 입력 타입
+ * @returns 검증 결과
+ */
+export declare function validateInput(input: string, type: 'text' | 'url' | 'filename' | 'html'): {
+    valid: boolean;
+    error?: string;
+    sanitized?: string;
+};

package/dist/utils/input-validation.js

@@ -0,0 +1,223 @@
+import "../chunk-ORMEWXMH.js";
+
+// src/utils/input-validation.ts
+var DANGEROUS_URL_SCHEMES = [
+  "javascript:",
+  "data:",
+  "file:",
+  "vbscript:",
+  "about:",
+  "chrome:",
+  "chrome-extension:",
+  "moz-extension:",
+  "ms-its:",
+  "ms-itss:",
+  "its:",
+  "mk:",
+  "view-source:"
+];
+var ALLOWED_URL_SCHEMES = [
+  "http:",
+  "https:",
+  "ftp:",
+  "ftps:",
+  "mailto:",
+  "tel:",
+  "sms:"
+];
+function validateURL(url, options = {}) {
+  const {
+    allowedSchemes = ALLOWED_URL_SCHEMES,
+    maxLength = 2048,
+    requireProtocol = true
+  } = options;
+  if (!url || typeof url !== "string") {
+    return { valid: false, error: "URL is required" };
+  }
+  if (url.length > maxLength) {
+    return { valid: false, error: `URL exceeds maximum length of ${maxLength}` };
+  }
+  const trimmedUrl = url.trim();
+  const hasProtocol = /^[a-z][a-z0-9+.-]*:/i.test(trimmedUrl);
+  if (requireProtocol && !hasProtocol) {
+    return { valid: false, error: "URL must include a protocol (http:// or https://)" };
+  }
+  const urlLower = trimmedUrl.toLowerCase();
+  for (const scheme of DANGEROUS_URL_SCHEMES) {
+    if (urlLower.startsWith(scheme)) {
+      return { valid: false, error: `Dangerous URL scheme detected: ${scheme}` };
+    }
+  }
+  if (hasProtocol) {
+    const scheme = trimmedUrl.split(":")[0].toLowerCase() + ":";
+    if (!allowedSchemes.includes(scheme)) {
+      return { valid: false, error: `URL scheme not allowed: ${scheme}` };
+    }
+  }
+  try {
+    const urlToParse = hasProtocol ? trimmedUrl : `https://${trimmedUrl}`;
+    const parsed = new URL(urlToParse);
+    if (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") {
+      if (process.env.NODE_ENV === "production") {
+        return { valid: false, error: "Internal URLs are not allowed" };
+      }
+    }
+    return {
+      valid: true,
+      sanitized: parsed.toString()
+    };
+  } catch (error) {
+    return { valid: false, error: "Invalid URL format" };
+  }
+}
+function escapeHTML(input) {
+  if (typeof input !== "string") {
+    return "";
+  }
+  return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;").replace(/\//g, "&#x2F;");
+}
+function detectXSS(input) {
+  if (typeof input !== "string") {
+    return false;
+  }
+  const xssPatterns = [
+    /<script[^>]*>.*?<\/script>/gi,
+    /javascript:/gi,
+    /on\w+\s*=/gi,
+    // onclick=, onerror= 등
+    /<iframe/gi,
+    /<object/gi,
+    /<embed/gi,
+    /<applet/gi,
+    /<meta/gi,
+    /<link/gi,
+    /<style/gi,
+    /eval\s*\(/gi,
+    /expression\s*\(/gi,
+    /vbscript:/gi,
+    /data:text\/html/gi
+  ];
+  return xssPatterns.some((pattern) => pattern.test(input));
+}
+function detectPathTraversal(input) {
+  if (typeof input !== "string") {
+    return false;
+  }
+  const traversalPatterns = [
+    /\.\./g,
+    // ../
+    /\.\\/g,
+    // .\
+    /%2e%2e/gi,
+    // URL 인코딩된 ..
+    /%252e/gi,
+    // 이중 URL 인코딩
+    /\\/g,
+    // 백슬래시
+    /\/\//g
+    // 이중 슬래시
+  ];
+  return traversalPatterns.some((pattern) => pattern.test(input));
+}
+function detectSQLInjection(input) {
+  if (typeof input !== "string") {
+    return false;
+  }
+  const sqlPatterns = [
+    /(\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|EXEC|EXECUTE|UNION|DECLARE)\b)/gi,
+    /--/g,
+    // SQL 주석
+    /\/\*/g,
+    // SQL 블록 주석
+    /;.*?/g,
+    // 세미콜론 (쿼리 구분)
+    /'\s*(OR|AND)\s*'?\d/gi,
+    // ' OR 1=1
+    /\bxp_\w+/gi,
+    // SQL Server 확장 프로시저
+    /\bsp_\w+/gi
+    // SQL Server 저장 프로시저
+  ];
+  return sqlPatterns.some((pattern) => pattern.test(input));
+}
+function sanitizeInput(input, options = {}) {
+  const { maxLength = 1e4, allowHTML = false, trim = true } = options;
+  if (typeof input !== "string") {
+    return "";
+  }
+  let sanitized = input;
+  if (trim) {
+    sanitized = sanitized.trim();
+  }
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.substring(0, maxLength);
+  }
+  if (!allowHTML) {
+    sanitized = escapeHTML(sanitized);
+  }
+  sanitized = sanitized.replace(/\0/g, "");
+  sanitized = sanitized.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+  return sanitized;
+}
+function validateFilename(filename) {
+  if (!filename || typeof filename !== "string") {
+    return { valid: false, error: "Filename is required" };
+  }
+  if (detectPathTraversal(filename)) {
+    return { valid: false, error: "Path traversal detected in filename" };
+  }
+  const dangerousExtensions = [
+    ".exe",
+    ".bat",
+    ".cmd",
+    ".com",
+    ".pif",
+    ".scr",
+    ".vbs",
+    ".js",
+    ".sh",
+    ".php",
+    ".asp",
+    ".aspx",
+    ".jsp"
+  ];
+  const ext = filename.toLowerCase().substring(filename.lastIndexOf("."));
+  if (dangerousExtensions.includes(ext)) {
+    return { valid: false, error: `Dangerous file extension: ${ext}` };
+  }
+  const sanitized = filename.replace(/[^a-zA-Z0-9._-]/g, "_").replace(/\.{2,}/g, ".").substring(0, 255);
+  return { valid: true, sanitized };
+}
+function validateInput(input, type) {
+  switch (type) {
+    case "url":
+      return validateURL(input);
+    case "filename":
+      return validateFilename(input);
+    case "text":
+      if (detectXSS(input)) {
+        return { valid: false, error: "XSS pattern detected" };
+      }
+      if (detectSQLInjection(input)) {
+        return { valid: false, error: "SQL Injection pattern detected" };
+      }
+      return { valid: true, sanitized: sanitizeInput(input) };
+    case "html":
+      if (detectXSS(input)) {
+        return { valid: false, error: "Dangerous HTML pattern detected" };
+      }
+      return { valid: true, sanitized: input };
+    default:
+      return { valid: false, error: "Unknown input type" };
+  }
+}
+export {
+  detectPathTraversal,
+  detectSQLInjection,
+  detectXSS,
+  escapeHTML,
+  sanitizeInput,
+  validateFilename,
+  validateInput,
+  validateURL
+};

package/dist/utils/ip-utils.d.ts

@@ -0,0 +1,15 @@
+export declare function isPrivateIP(ip: string): boolean;
+export declare function isIPv6(ip: string): boolean;
+export declare function normalizeIP(ip: string): string;
+/**
+ * 클라이언트 IP 주소 추출 (서버에서만 사용)
+ *
+ * Cloudflare 환경 최적화:
+ * 1. CF-Connecting-IP: Cloudflare가 설정하는 실제 클라이언트 IP (가장 신뢰)
+ * 2. True-Client-IP: Cloudflare Enterprise에서 사용
+ * 3. X-Real-IP: Nginx 등 신뢰할 수 있는 리버스 프록시
+ * 4. X-Forwarded-For: 첫 번째 IP가 실제 클라이언트 (Cloudflare가 추가)
+ * 5. X-Client-IP: 일부 프록시에서 사용
+ */
+export declare function extractClientIp(headers: Headers): string | null;
+export declare function isValidIP(ip: string): boolean;