@clazic/kordoc 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chrisryugj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# kordoc
+
+**모두 파싱해버리겠다.**
+
+[![npm version](https://img.shields.io/npm/v/kordoc.svg)](https://www.npmjs.com/package/kordoc)
+[![license](https://img.shields.io/npm/l/kordoc.svg)](https://github.com/chrisryugj/kordoc/blob/main/LICENSE)
+
+HWP, HWPX, PDF, XLSX, DOCX — 관공서에서 쏟아지는 모든 문서를 파싱하고, 비교하고, 분석하고, 생성합니다.
+
+[English](./README-EN.md)
+
+![kordoc 데모](./demo.gif)
+
+---
+
+## 💡 kordoc으로 무엇을 할 수 있나요?
+
+단순한 텍스트 추출을 넘어, **공문서 처리를 위한 모든 과정**을 자동화합니다.
+
+*   **📄 어떤 문서든 마크다운으로**: `HWP`, `HWPX`, `PDF`, `XLSX`, `DOCX` 파일을 즉시 `Markdown`으로 변환합니다. AI(LLM)가 문서를 읽고 분석하기 가장 좋은 상태로 만들어줍니다.
+*   **📊 복잡한 표(Table) 완벽 재현**: 선이 없는 PDF나 복잡하게 병합된 HWP 표도 구조를 분석하여 정확한 마크다운 테이블로 복원합니다.
+*   **🔍 신구대조표 자동 생성**: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (HWP와 HWPX 간의 비교도 가능!)
+*   **📝 마크다운을 다시 HWPX로**: AI가 작성한 내용을 다시 보고서 양식(`HWPX`)으로 되돌려줍니다. 이제 복사-붙여넣기 노가다에서 해방되세요.
+*   **🤖 AI 에이전트 연동 (MCP)**: `Claude`, `Cursor`와 같은 도구에서 직접 `kordoc`을 호출해 문서를 읽고 코딩할 수 있습니다.
+
+---
+
+## v2.0 변경사항
+
+- **🔓 배포용(열람 제한) HWP 파싱 지원** — 관공서에서 배포용으로 잠근 HWP 파일도 이제 파싱됩니다. AES-128 ECB 복호화, 순수 JS 구현. [rhwp](https://github.com/edwardkim/rhwp)(MIT) 알고리즘 포팅.
+- **손상된 HWP 파일 복구** — 표준 CFB 모듈이 거부하는 파일을 직접 FAT/디렉토리 파싱으로 복구. rhwp LenientCfbReader 포팅.
+- **HWP5 각주/미주/하이퍼링크 추출** — 각주 본문 텍스트 연결, 하이퍼링크 URL 추출 및 XSS 살균.
+- **HWPX 표 병합 밀림 수정** — colspan/rowspan 그리드 계산 버그 수정.
+- **보안 강화** — CFB 섹터 크기 검증, sanitizeHref 3중 경로 일관 적용.
+
+<details>
+<summary>v1.8.0 변경사항</summary>
+
+- **XLSX 파서 추가** — Excel 스프레드시트 파싱. 공유 문자열, 병합 셀, 다중 시트 지원. 시트별 heading + table 블록 생성.
+- **DOCX 파서 추가** — Word 문서 파싱. 스타일 기반 heading, 번호 매기기(리스트), 각주, 하이퍼링크, 이미지 추출, vMerge/gridSpan 테이블 병합.
+- **파싱 품질 대폭 개선** — PDF/HWPX/HWP5/XLSX 전 포맷 품질 점수 73→93점.
+- **프로덕션 리뷰 17건 수정** — CLI `--no-header-footer` 플래그 반전 버그, MCP XLSX/DOCX 확장자 허용, ZIP bomb 보호 공유 유틸화, href XSS 살균 강화, PDF timeout 타이머 정리, HWP5 BinData O(n) 최적화, cluster indexOf O(n²)→O(n), SSRF IPv6 차단 등.
+
+</details>
+
+<details>
+<summary>v1.7.x 변경사항</summary>
+
+- **이미지 추출 (HWP/HWPX)** — ZIP 엔트리와 HWP5 BinData 스트림에서 바이너리 이미지 추출.
+- **부분 파싱 (Graceful Degradation)** — 개별 페이지 실패가 전체 파싱을 중단하지 않음.
+- **진행률 콜백** — `onProgress` 콜백. CLI에서 `[3/15 pages]` 형태 표시.
+- **파일 경로 직접 입력** — `parse("path/to/file.hwp")` 문자열 오버로드.
+- **PDF 머리글/바닥글 필터링** — `removeHeaderFooter` 옵션.
+- **보안 강화** — ZIP bomb 추적, SSRF 방지, XSS 방어, 널바이트 감지, PDF 타임아웃.
+- **pdfjs-dist v5 호환** — constructPath 연산자 형식 변경 대응.
+
+</details>
+
+<details>
+<summary>v1.6.1 수정사항</summary>
+
+- **HWP5 테이블 셀 오프셋 수정** — LIST_HEADER 파싱 시 2바이트 오프셋 밀림으로 rowAddr를 colSpan으로 잘못 읽던 치명적 버그 수정. 3열 테이블이 6열로 뻥튀기되던 문제 해결. colAddr/rowAddr 기반 직접 배치로 병합 테이블 정확도 향상.
+- **HWP5 TAB 제어문자 수정** — TAB(0x0009) 인라인 컨트롤의 14바이트 확장 데이터 스킵 누락으로 `࣐Ā` 쓰레기 문자가 출력되던 버그 수정.
+
+</details>
+
+<details>
+<summary>v1.6.0 기능</summary>
+
+- **클러스터 기반 테이블 감지 (PDF)** — 선 없는 PDF에서 텍스트 정렬 패턴으로 테이블 구조 추론. baseline 그룹핑 + X좌표 클러스터링으로 2열 이상 테이블 감지. 선 기반 감지가 실패한 경우의 중간 계층 fallback.
+- **한국어 특수 테이블 감지** — `구분/항목/종류/기준` 등 한국 공문서 key-value 패턴을 자동으로 2열 테이블로 변환.
+- **한국어 어절 끊김 복원** — PDF 셀 내 한글 문자별 렌더링으로 인한 미세 갭 처리 개선. 셀 줄바꿈 병합 임계값 8자로 확장, 1글자 조사 자동 연결.
+- **빈 테이블 필터링** — 장식용 선에서 생긴 빈 테이블 자동 제거.
+
+</details>
+
+<details>
+<summary>v1.5.0 기능</summary>
+
+- **선 기반 테이블 감지 (PDF)** — OpenDataLoader 핵심 알고리즘 포팅. PDF 그래픽 명령에서 수평/수직 선을 추출하고, 교차점으로 그리드 구성, bbox overlap으로 텍스트→셀 매핑. colspan/rowspan 자동 감지. 선 없는 PDF는 기존 휴리스틱 fallback.
+- **IRBlock v2** — 6가지 블록 타입: `heading`, `paragraph`, `table`, `list`, `image`, `separator`. 새 필드: `bbox`, `style`, `pageNumber`, `level`, `href`, `footnoteText`.
+- **ParseResult v2** — `outline` (문서 구조), `warnings` (스킵된 요소, 숨김 텍스트) 필드 추가.
+- **PDF 개선** — XY-Cut 읽기 순서, 폰트 크기 기반 헤딩 감지, hidden text 필터링 (프롬프트 인젝션 방어), 모든 블록에 바운딩 박스.
+- **HWP5 개선** — CHAR_SHAPE 파싱, 스타일 기반 헤딩 감지, OLE/이미지 스킵 경고.
+- **HWPX 개선** — header.xml 스타일 파싱, 하이퍼링크/각주 추출.
+- **리스트 감지** — 테이블 뒤 번호 문단을 ordered list 블록으로 자동 변환.
+- **MCP 서버** — parse_document 응답에 `outline`, `warnings` 포함.
+
+</details>
+
+<details>
+<summary>v1.4.x 기능</summary>
+
+- **문서 비교 (Diff)** — IR 레벨 블록 비교로 신구대조표 생성. HWP↔HWPX 크로스 포맷 지원.
+- **양식 인식** — 공문서 테이블에서 label-value 쌍 자동 추출. 성명, 소속, 전화번호 등.
+- **구조화 파싱** — `IRBlock[]`과 `DocumentMetadata`에 직접 접근. 마크다운 넘어선 데이터 활용.
+- **페이지 범위** — `parse(buffer, { pages: "1-3" })` — 필요한 페이지만 빠르게.
+- **Markdown → HWPX** — 역변환. AI가 생성한 내용을 바로 공문서로.
+- **OCR 연동** — 이미지 기반 PDF도 텍스트 추출 (Tesseract, Claude Vision 등 프로바이더 직접 제공).
+- **Watch 모드** — `kordoc watch ./수신함 -d ./변환결과 --webhook https://...`
+- **MCP 7개 도구** — parse_document, detect_format, parse_metadata, parse_pages, parse_table, compare_documents, parse_form
+- **에러 코드** — `"ENCRYPTED"`, `"ZIP_BOMB"`, `"IMAGE_BASED_PDF"` 등 구조화된 에러 핸들링
+
+</details>
+
+---
+
+## 설치
+
+```bash
+npm install kordoc
+
+# PDF 파싱이 필요하면 (선택)
+npm install pdfjs-dist
+```
+
+## 빠른 시작
+
+### 문서 파싱
+
+```typescript
+import { parse } from "kordoc"
+import { readFileSync } from "fs"
+
+const buffer = readFileSync("사업계획서.hwpx")
+const result = await parse(buffer.buffer)
+
+if (result.success) {
+  console.log(result.markdown)       // 마크다운 텍스트
+  console.log(result.blocks)         // IRBlock[] 구조화 데이터
+  console.log(result.metadata)       // { title, author, createdAt, ... }
+}
+```
+
+### 문서 비교 (신구대조표)
+
+```typescript
+import { compare } from "kordoc"
+
+const diff = await compare(구버전Buffer, 신버전Buffer)
+// diff.stats → { added: 3, removed: 1, modified: 5, unchanged: 42 }
+// diff.diffs → BlockDiff[] (테이블은 셀 단위 diff 포함)
+```
+
+HWP vs HWPX 크로스 포맷 비교도 가능합니다.
+
+### 양식 필드 추출
+
+```typescript
+import { parse, extractFormFields } from "kordoc"
+
+const result = await parse(buffer)
+if (result.success) {
+  const form = extractFormFields(result.blocks)
+  // form.fields → [{ label: "성명", value: "홍길동", row: 0, col: 0 }, ...]
+  // form.confidence → 0.85
+}
+```
+
+### HWPX 생성 (역변환)
+
+```typescript
+import { markdownToHwpx } from "kordoc"
+
+const hwpxBuffer = await markdownToHwpx("# 제목\n\n본문 텍스트\n\n| 이름 | 직급 |\n| --- | --- |\n| 홍길동 | 과장 |")
+writeFileSync("출력.hwpx", Buffer.from(hwpxBuffer))
+```
+
+### 페이지 범위 지정
+
+```typescript
+const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
+const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지
+```
+
+### OCR (이미지 PDF)
+
+```typescript
+const result = await parse(buffer, {
+  ocr: async (pageImage, pageNumber, mimeType) => {
+    return await myOcrService.recognize(pageImage)
+  }
+})
+```
+
+## CLI
+
+```bash
+npx kordoc 사업계획서.hwpx                          # 터미널 출력
+npx kordoc 보고서.hwp -o 보고서.md                  # 파일 저장
+npx kordoc *.pdf -d ./변환결과/                     # 일괄 변환
+npx kordoc 검토서.hwpx --format json               # JSON (blocks + metadata 포함)
+npx kordoc 보고서.hwpx --pages 1-3                  # 페이지 범위
+npx kordoc watch ./수신함 -d ./변환결과              # 폴더 감시 모드
+npx kordoc watch ./문서 --webhook https://api/hook  # 웹훅 알림
+```
+
+## MCP 서버 (Claude / Cursor / Windsurf)
+
+```json
+{
+  "mcpServers": {
+    "kordoc": {
+      "command": "npx",
+      "args": ["-y", "kordoc-mcp"]
+    }
+  }
+}
+```
+
+**7개 도구:**
+
+| 도구 | 설명 |
+|------|------|
+| `parse_document` | HWP/HWPX/PDF/XLSX/DOCX → 마크다운 (메타데이터 포함) |
+| `detect_format` | 매직 바이트로 포맷 감지 |
+| `parse_metadata` | 메타데이터만 빠르게 추출 |
+| `parse_pages` | 특정 페이지 범위만 파싱 |
+| `parse_table` | N번째 테이블만 추출 |
+| `compare_documents` | 두 문서 비교 (크로스 포맷) |
+| `parse_form` | 양식 필드를 JSON으로 추출 |
+
+## API
+
+### 핵심 함수
+
+| 함수 | 설명 |
+|------|------|
+| `parse(buffer, options?)` | 포맷 자동 감지 → Markdown + IRBlock[] |
+| `parseHwpx(buffer, options?)` | HWPX 전용 |
+| `parseHwp(buffer, options?)` | HWP 5.x 전용 |
+| `parsePdf(buffer, options?)` | PDF 전용 |
+| `parseXlsx(buffer, options?)` | XLSX 전용 |
+| `parseDocx(buffer, options?)` | DOCX 전용 |
+| `detectFormat(buffer)` | `"hwpx" \| "hwp" \| "pdf" \| "xlsx" \| "docx" \| "unknown"` |
+
+### 고급 함수
+
+| 함수 | 설명 |
+|------|------|
+| `compare(bufferA, bufferB, options?)` | IR 레벨 문서 비교 |
+| `extractFormFields(blocks)` | IRBlock[]에서 양식 필드 인식 |
+| `markdownToHwpx(markdown)` | Markdown → HWPX 역변환 |
+| `blocksToMarkdown(blocks)` | IRBlock[] → Markdown 문자열 |
+
+### 타입
+
+```typescript
+import type {
+  ParseResult, ParseSuccess, ParseFailure, FileType,
+  IRBlock, IRTable, IRCell, CellContext,
+  DocumentMetadata, ParseOptions, ErrorCode,
+  DiffResult, BlockDiff, CellDiff, DiffChangeType,
+  FormField, FormResult,
+  OcrProvider, WatchOptions,
+} from "kordoc"
+```
+
+## 지원 포맷
+
+| 포맷 | 엔진 | 특징 |
+|------|------|------|
+| **HWPX** (한컴 2020+) | ZIP + XML DOM | 매니페스트, 중첩 테이블, 병합 셀, 손상 ZIP 복구 |
+| **HWP 5.x** (한컴 레거시) | OLE2 + CFB | 배포용 복호화, 손상 CFB 복구, 각주/하이퍼링크, 21종 제어문자, 이미지 추출 |
+| **PDF** | pdfjs-dist | 선 기반 테이블, XY-Cut 읽기 순서, 헤딩 감지, OCR |
+| **XLSX** (Excel) | ZIP + XML DOM | 공유 문자열, 병합 셀, 다중 시트, 수식 표시 |
+| **DOCX** (Word) | ZIP + XML DOM | 스타일 heading, 번호 매기기, 각주, 이미지 추출 |
+
+## 보안
+
+프로덕션급 보안 강화: ZIP bomb 방지, XXE/Billion Laughs 방지, 압축 폭탄 방지, 경로 순회 차단, MCP 에러 정제, 파일 크기 제한(500MB). 자세한 내용은 [SECURITY.md](./SECURITY.md) 참조.
+
+## 만든 사람
+
+대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다.
+5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.
+
+## 라이선스
+
+[MIT](./LICENSE)
+
+이 프로젝트는 아래 오픈소스를 포함합니다:
+- **rhwp** (MIT, edwardkim) — HWP5 배포용 복호화 및 lenient CFB 파싱 알고리즘
+- **OpenDataLoader PDF** (Apache 2.0, Hancom Inc.) — PDF 테이블 감지 알고리즘
+- **cfb** (Apache 2.0, SheetJS) — HWP5 OLE2 컨테이너 파싱
+- **pdfjs-dist** (Apache 2.0, Mozilla) — PDF 텍스트 추출
+- **JSZip** (MIT, Stuart Knightley 외) — ZIP 기반 포맷 파싱
+
+자세한 내용은 [NOTICE](./NOTICE) 파일을 참조하세요.

package/dist/chunk-MOL7MDBG.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+// src/page-range.ts
+function parsePageRange(spec, maxPages) {
+  const result = /* @__PURE__ */ new Set();
+  if (maxPages <= 0) return result;
+  if (Array.isArray(spec)) {
+    for (const n of spec) {
+      const page = Math.round(n);
+      if (page >= 1 && page <= maxPages) result.add(page);
+    }
+    return result;
+  }
+  if (typeof spec !== "string" || spec.trim() === "") return result;
+  const parts = spec.split(",");
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const rangeMatch = trimmed.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (rangeMatch) {
+      const start = Math.max(1, parseInt(rangeMatch[1], 10));
+      const end = Math.min(maxPages, parseInt(rangeMatch[2], 10));
+      for (let i = start; i <= end; i++) result.add(i);
+    } else {
+      const page = parseInt(trimmed, 10);
+      if (!isNaN(page) && page >= 1 && page <= maxPages) result.add(page);
+    }
+  }
+  return result;
+}
+
+export {
+  parsePageRange
+};
+//# sourceMappingURL=chunk-MOL7MDBG.js.map

package/dist/chunk-MOL7MDBG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/page-range.ts"],"sourcesContent":["/** 페이지/섹션 범위 파싱 유틸리티 */\n\n/**\n * 페이지 범위 지정을 1-based Set<number>로 변환.\n *\n * @param spec - [1,2,3] 또는 \"1-3\" 또는 \"1,3,5-7\"\n * @param maxPages - 최대 페이지 수 (클램핑 상한)\n * @returns 1-based 페이지 번호 Set\n */\nexport function parsePageRange(spec: number[] | string, maxPages: number): Set<number> {\n  const result = new Set<number>()\n  if (maxPages <= 0) return result\n\n  if (Array.isArray(spec)) {\n    for (const n of spec) {\n      const page = Math.round(n)\n      if (page >= 1 && page <= maxPages) result.add(page)\n    }\n    return result\n  }\n\n  if (typeof spec !== \"string\" || spec.trim() === \"\") return result\n\n  const parts = spec.split(\",\")\n  for (const part of parts) {\n    const trimmed = part.trim()\n    if (!trimmed) continue\n\n    const rangeMatch = trimmed.match(/^(\\d+)\\s*-\\s*(\\d+)$/)\n    if (rangeMatch) {\n      const start = Math.max(1, parseInt(rangeMatch[1], 10))\n      const end = Math.min(maxPages, parseInt(rangeMatch[2], 10))\n      for (let i = start; i <= end; i++) result.add(i)\n    } else {\n      const page = parseInt(trimmed, 10)\n      if (!isNaN(page) && page >= 1 && page <= maxPages) result.add(page)\n    }\n  }\n\n  return result\n}\n"],"mappings":";;;AASO,SAAS,eAAe,MAAyB,UAA+B;AACrF,QAAM,SAAS,oBAAI,IAAY;AAC/B,MAAI,YAAY,EAAG,QAAO;AAE1B,MAAI,MAAM,QAAQ,IAAI,GAAG;AACvB,eAAW,KAAK,MAAM;AACpB,YAAM,OAAO,KAAK,MAAM,CAAC;AACzB,UAAI,QAAQ,KAAK,QAAQ,SAAU,QAAO,IAAI,IAAI;AAAA,IACpD;AACA,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,SAAS,YAAY,KAAK,KAAK,MAAM,GAAI,QAAO;AAE3D,QAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,aAAW,QAAQ,OAAO;AACxB,UAAM,UAAU,KAAK,KAAK;AAC1B,QAAI,CAAC,QAAS;AAEd,UAAM,aAAa,QAAQ,MAAM,qBAAqB;AACtD,QAAI,YAAY;AACd,YAAM,QAAQ,KAAK,IAAI,GAAG,SAAS,WAAW,CAAC,GAAG,EAAE,CAAC;AACrD,YAAM,MAAM,KAAK,IAAI,UAAU,SAAS,WAAW,CAAC,GAAG,EAAE,CAAC;AAC1D,eAAS,IAAI,OAAO,KAAK,KAAK,IAAK,QAAO,IAAI,CAAC;AAAA,IACjD,OAAO;AACL,YAAM,OAAO,SAAS,SAAS,EAAE;AACjC,UAAI,CAAC,MAAM,IAAI,KAAK,QAAQ,KAAK,QAAQ,SAAU,QAAO,IAAI,IAAI;AAAA,IACpE;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/chunk-PKIJLEV6.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+// src/utils.ts
+var VERSION = true ? "2.1.0" : "0.0.0-dev";
+function toArrayBuffer(buf) {
+  if (buf.byteOffset === 0 && buf.byteLength === buf.buffer.byteLength) {
+    return buf.buffer;
+  }
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+var KordocError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KordocError";
+  }
+};
+function sanitizeError(err) {
+  if (err instanceof KordocError) return err.message;
+  return "\uBB38\uC11C \uCC98\uB9AC \uC911 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4";
+}
+function isPathTraversal(name) {
+  if (name.includes("\0")) return true;
+  const normalized = name.replace(/\\/g, "/");
+  return normalized.includes("..") || normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized);
+}
+function precheckZipSize(buffer, maxUncompressedSize = 100 * 1024 * 1024, maxEntries = 500) {
+  try {
+    const data = new DataView(buffer);
+    const len = buffer.byteLength;
+    let eocdOffset = -1;
+    for (let i = len - 22; i >= Math.max(0, len - 65557); i--) {
+      if (data.getUint32(i, true) === 101010256) {
+        eocdOffset = i;
+        break;
+      }
+    }
+    if (eocdOffset < 0) return { totalUncompressed: 0, entryCount: 0 };
+    const entryCount = data.getUint16(eocdOffset + 10, true);
+    if (entryCount > maxEntries) {
+      throw new KordocError(`ZIP \uC5D4\uD2B8\uB9AC \uC218 \uCD08\uACFC: ${entryCount} (\uCD5C\uB300 ${maxEntries})`);
+    }
+    const cdSize = data.getUint32(eocdOffset + 12, true);
+    const cdOffset = data.getUint32(eocdOffset + 16, true);
+    if (cdOffset + cdSize > len) return { totalUncompressed: 0, entryCount };
+    let totalUncompressed = 0;
+    let pos = cdOffset;
+    for (let i = 0; i < entryCount && pos + 46 <= cdOffset + cdSize; i++) {
+      if (data.getUint32(pos, true) !== 33639248) break;
+      totalUncompressed += data.getUint32(pos + 24, true);
+      const nameLen = data.getUint16(pos + 28, true);
+      const extraLen = data.getUint16(pos + 30, true);
+      const commentLen = data.getUint16(pos + 32, true);
+      pos += 46 + nameLen + extraLen + commentLen;
+    }
+    if (totalUncompressed > maxUncompressedSize) {
+      throw new KordocError(`ZIP \uBE44\uC555\uCD95 \uD06C\uAE30 \uCD08\uACFC: ${(totalUncompressed / 1024 / 1024).toFixed(1)}MB (\uCD5C\uB300 ${maxUncompressedSize / 1024 / 1024}MB)`);
+    }
+    return { totalUncompressed, entryCount };
+  } catch (err) {
+    if (err instanceof KordocError) throw err;
+    return { totalUncompressed: 0, entryCount: 0 };
+  }
+}
+var SAFE_HREF_RE = /^(?:https?:|mailto:|tel:|#)/i;
+function sanitizeHref(href) {
+  const trimmed = href.trim();
+  if (!trimmed || !SAFE_HREF_RE.test(trimmed)) return null;
+  return trimmed;
+}
+function classifyError(err) {
+  if (!(err instanceof Error)) return "PARSE_ERROR";
+  const msg = err.message;
+  if (msg.includes("\uC554\uD638\uD654")) return "ENCRYPTED";
+  if (msg.includes("DRM")) return "DRM_PROTECTED";
+  if (msg.includes("ZIP bomb") || msg.includes("ZIP \uBE44\uC555\uCD95 \uD06C\uAE30 \uCD08\uACFC") || msg.includes("ZIP \uC5D4\uD2B8\uB9AC \uC218 \uCD08\uACFC")) return "ZIP_BOMB";
+  if (msg.includes("bomb") || msg.includes("\uD06C\uAE30 \uCD08\uACFC") || msg.includes("\uC555\uCD95 \uD574\uC81C")) return "DECOMPRESSION_BOMB";
+  if (msg.includes("\uC774\uBBF8\uC9C0 \uAE30\uBC18")) return "IMAGE_BASED_PDF";
+  if (msg.includes("\uC139\uC158") && (msg.includes("\uCC3E\uC744 \uC218 \uC5C6") || msg.includes("\uC5C6\uC74C"))) return "NO_SECTIONS";
+  if (msg.includes("\uC2DC\uADF8\uB2C8\uCC98") || msg.includes("\uBCF5\uAD6C\uD560 \uC218 \uC5C6")) return "CORRUPTED";
+  return "PARSE_ERROR";
+}
+
+export {
+  VERSION,
+  toArrayBuffer,
+  KordocError,
+  sanitizeError,
+  isPathTraversal,
+  precheckZipSize,
+  sanitizeHref,
+  classifyError
+};
+//# sourceMappingURL=chunk-PKIJLEV6.js.map

package/dist/chunk-PKIJLEV6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts"],"sourcesContent":["/** kordoc 공용 유틸리티 */\n\n/** 빌드 타임에 tsup define으로 주입되는 버전 */\ndeclare const __KORDOC_VERSION__: string\nexport const VERSION: string = typeof __KORDOC_VERSION__ !== \"undefined\" ? __KORDOC_VERSION__ : \"0.0.0-dev\"\n\n/**\n * Node.js Buffer → ArrayBuffer 변환\n * pool Buffer의 공유 ArrayBuffer 문제를 안전하게 처리.\n * offset=0이고 전체 ArrayBuffer를 차지하면 복사 없이 직접 반환.\n */\nexport function toArrayBuffer(buf: Buffer): ArrayBuffer {\n  if (buf.byteOffset === 0 && buf.byteLength === buf.buffer.byteLength) {\n    return buf.buffer as ArrayBuffer\n  }\n  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer\n}\n\n/**\n * kordoc 내부 에러 클래스 — 사용자에게 노출해도 안전한 메시지만 포함.\n * MCP 에러 정제에서 instanceof로 판별하여 allowlist 패턴 매칭 없이 안전하게 통과.\n */\nexport class KordocError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = \"KordocError\"\n  }\n}\n\n/**\n * 에러 메시지 정제 — KordocError는 그대로, 나머지는 일반 메시지로 대체.\n * 파일시스템 경로, 스택 트레이스 등 내부 정보 노출 방지.\n */\nexport function sanitizeError(err: unknown): string {\n  if (err instanceof KordocError) return err.message\n  return \"문서 처리 중 오류가 발생했습니다\"\n}\n\n/**\n * ZIP 엔트리 경로의 경로 순회 여부 판별.\n * 백슬래시 정규화, .., 절대경로, Windows 드라이브 문자 모두 차단.\n */\nexport function isPathTraversal(name: string): boolean {\n  if (name.includes(\"\\x00\")) return true\n  const normalized = name.replace(/\\\\/g, \"/\")\n  return normalized.includes(\"..\") || normalized.startsWith(\"/\") || /^[A-Za-z]:/.test(normalized)\n}\n\n// ─── ZIP 안전 로딩 (ZIP bomb 방지) ────────────────────\n\n/**\n * ZIP bomb 사전 검사 — Central Directory에서 비압축 합계와 엔트리 수 확인.\n * HWPX/XLSX/DOCX 등 모든 ZIP 기반 포맷에서 공통 사용.\n */\nexport function precheckZipSize(\n  buffer: ArrayBuffer,\n  maxUncompressedSize = 100 * 1024 * 1024,\n  maxEntries = 500,\n): { totalUncompressed: number; entryCount: number } {\n  try {\n    const data = new DataView(buffer)\n    const len = buffer.byteLength\n    // EOCD 시그니처 역방향 스캔\n    let eocdOffset = -1\n    for (let i = len - 22; i >= Math.max(0, len - 65557); i--) {\n      if (data.getUint32(i, true) === 0x06054b50) { eocdOffset = i; break }\n    }\n    if (eocdOffset < 0) return { totalUncompressed: 0, entryCount: 0 }\n\n    const entryCount = data.getUint16(eocdOffset + 10, true)\n    if (entryCount > maxEntries) {\n      throw new KordocError(`ZIP 엔트리 수 초과: ${entryCount} (최대 ${maxEntries})`)\n    }\n\n    const cdSize = data.getUint32(eocdOffset + 12, true)\n    const cdOffset = data.getUint32(eocdOffset + 16, true)\n    if (cdOffset + cdSize > len) return { totalUncompressed: 0, entryCount }\n\n    let totalUncompressed = 0\n    let pos = cdOffset\n    for (let i = 0; i < entryCount && pos + 46 <= cdOffset + cdSize; i++) {\n      if (data.getUint32(pos, true) !== 0x02014b50) break\n      totalUncompressed += data.getUint32(pos + 24, true)\n      const nameLen = data.getUint16(pos + 28, true)\n      const extraLen = data.getUint16(pos + 30, true)\n      const commentLen = data.getUint16(pos + 32, true)\n      pos += 46 + nameLen + extraLen + commentLen\n    }\n\n    if (totalUncompressed > maxUncompressedSize) {\n      throw new KordocError(`ZIP 비압축 크기 초과: ${(totalUncompressed / 1024 / 1024).toFixed(1)}MB (최대 ${maxUncompressedSize / 1024 / 1024}MB)`)\n    }\n\n    return { totalUncompressed, entryCount }\n  } catch (err) {\n    if (err instanceof KordocError) throw err\n    return { totalUncompressed: 0, entryCount: 0 }\n  }\n}\n\n/** 하이퍼링크 URL 살균 — javascript: 등 XSS 위험 스킴 차단 */\nconst SAFE_HREF_RE = /^(?:https?:|mailto:|tel:|#)/i\nexport function sanitizeHref(href: string): string | null {\n  const trimmed = href.trim()\n  if (!trimmed || !SAFE_HREF_RE.test(trimmed)) return null\n  return trimmed\n}\n\n// ─── 에러 분류 ──────────────────────────────────────\n\nimport type { ErrorCode } from \"./types.js\"\n\n/** 에러를 구조화된 ErrorCode로 분류 — KordocError 메시지 패턴 매칭 */\nexport function classifyError(err: unknown): ErrorCode {\n  if (!(err instanceof Error)) return \"PARSE_ERROR\"\n  const msg = err.message\n  if (msg.includes(\"암호화\")) return \"ENCRYPTED\"\n  if (msg.includes(\"DRM\")) return \"DRM_PROTECTED\"\n  if (msg.includes(\"ZIP bomb\") || msg.includes(\"ZIP 비압축 크기 초과\") || msg.includes(\"ZIP 엔트리 수 초과\")) return \"ZIP_BOMB\"\n  if (msg.includes(\"bomb\") || msg.includes(\"크기 초과\") || msg.includes(\"압축 해제\")) return \"DECOMPRESSION_BOMB\"\n  if (msg.includes(\"이미지 기반\")) return \"IMAGE_BASED_PDF\"\n  if (msg.includes(\"섹션\") && (msg.includes(\"찾을 수 없\") || msg.includes(\"없음\"))) return \"NO_SECTIONS\"\n  if (msg.includes(\"시그니처\") || msg.includes(\"복구할 수 없\")) return \"CORRUPTED\"\n  return \"PARSE_ERROR\"\n}\n"],"mappings":"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","names":[]}