건강 점검 + 안전한 개선 2건: Windows verify:package 수정 · HTTP 경계 환경변수 문서화

[khs0927]

점검 배경

로컬 main(c6feff0) 기준 건강 점검을 실행하고, 발견된 안전한 개선 2건을 제출합니다.

점검 결과 (실행 증거)

항목	결과	증거
단위 테스트 (vitest)	✅ 통과	npm test → 165 files / 1354 tests passed, exit 0
타입 체크 (tsc --noEmit)	✅ 통과	npm run typecheck exit 0, 오류 0건
빌드 (tsc)	✅ 통과	npm run build exit 0
패키지 검증 (verify:package)	❌ → ✅ 수정됨	Windows에서 npm pack spawn 실패(exit 1) → 본 PR로 exit 0 복구
annex runtime 검증	✅ 통과	npm run verify:annex-runtime exit 0
데드 코드 (knip)	✅ 통과	npm run dead-code exit 0
의존성 취약점	✅ 0건	npm audit → found 0 vulnerabilities
CI (GitHub Actions)	✅ 전체 성공	최근 CI·Publish·Mirror 실행 모두 success (2026-10-11)
문서-코드 정합성	✅ 통과	도구 수 자동 게이트 테스트(tool-registry.docs.test) 포함, 전체 통과
의존성 핀	✅ 양호	보안 관련 kordoc/pdfjs-dist 정확히 핀, 나머지 캐럿 범위 + overrides로 transitive 통제

참고: 이 레포는 Python이 아닌 TypeScript 프로젝트이므로 ruff 대신 tsc/vitest/knip/npm audit를 점검 도구로 사용했습니다.

개선 1: verify-package.mjs Windows 실패 수정 (버그 수정)

scripts/verify-package.mjs의 packedFiles()가 spawnSync("npm", [...])로 npm을 호출합니다. Windows에서는 npm이 .cmd 심링크라 shell 없이 spawn하면 ENOENT/EINVAL로 실패합니다.

• 영향: Windows 기여자가 npm run verify:package·npm run prepack·CLAUDE.md의 정규 경로인 로컬 npm publish를 실행할 수 없었습니다. (리눅스 CI는 정상 동작)
• 진단: spawnSync("npm", …) → status: null, error: spawnSync npm ENOENT; spawnSync("npm.cmd", …) → EINVAL. shell: true 시 정상 동작 확인.
• 수정: shell: true + 단일 명령어 문자열로 실행. 인자는 정적 리터럴(pack --dry-run --json --ignore-scripts)이라 인젝션 면이 없으며, args 배열이 아닌 단일 문자열이므로 DEP0190 경고도 발생하지 않습니다.
• 검증: 수정 후 Windows에서 npm run verify:package → package artifacts verified (314 packed files), exit 0.

개선 2: HTTP 실행 경계 환경변수 4종 문서화 (문서)

src/server/http-server.ts가 읽지만 문서에 없던 환경변수를 추가합니다.

환경변수	README(한)	README-EN	비고
ALLOWED_ORIGINS	❌→✅	이미 있음	DNS rebinding 방어와 직결된 보안 설정 — 브라우저 클라이언트 사용 시 필수
CORS_ORIGIN	❌→✅	이미 있음	명시 시 해당 출처도 Origin 검증 통과
ALLOW_QUERY_API_KEY	❌→✅	이미 있음	=0 시 ?oc= 쿼리 키 차단 (폐쇄망 권장)
ACCESS_LOG	❌→✅	❌→✅	=1 시 요청 로그, 경로만 기록(키 유출 방지)

• 한국어 README "HTTP·실행 경계 설정" 섹션에 3개 항목을, 영문 README 환경변수 표에 ACCESS_LOG 행을 추가했습니다.
• ALLOWED_ORIGINS는 설정 누락 시 브라우저 요청이 전부 차단되는데 한국어 문서에 설명이 없어, 웹 클라이언트 배포 사용자가 원인을 파악하기 어려운 점이 가장 큰 실용적 손실이었습니다.

변경 범위

• scripts/verify-package.mjs — spawn 호출 1곳 (기능 변경 없음)
• README.md — 환경변수 설명 3항목 추가 (CRLF 보존)
• README-EN.md — 환경변수 표 1행 추가

기존 동작·도구·API 변경은 없으며, 문서의 도구 수 표기 자동 게이트를 포함한 전체 테스트 1354개 재통과를 확인했습니다.

검증 증거 (본 브랜치)

npm run typecheck     → exit 0
npm test              → 165 files / 1354 tests passed, exit 0
npm run build         → exit 0
npm run verify:package → package artifacts verified (314 packed files), exit 0

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T03:16:00.519376Z	a753e3e	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a753e3e050

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Document CORS_ORIGIN as a fallback, not an added origin

When both variables are set and CORS_ORIGIN is not already in ALLOWED_ORIGINS, this sentence tells deployments that both origins will pass validation. resolveOrigin in src/server/http-server.ts:113-120 only consults CORS_ORIGIN when allowedOrigins.length === 0, so requests from that origin instead receive a 403 once the allowlist is nonempty; either union the configured origin in code or document that it is only a fallback.

Useful? React with 👍 / 👎.

[chrisryugj]

꼼꼼한 점검 감사합니다. 최신 main 기준으로 확인했고 병합합니다.

• verify-package.mjs: 인자가 정적 리터럴이라 shell: true의 인젝션 면이 없는 것을 확인했습니다. macOS에서도 npm run verify:package → package artifacts verified (314 packed files) 입니다.
• 환경변수 문서: ALLOWED_ORIGINS·ALLOW_QUERY_API_KEY·ACCESS_LOG 설명은 src/server/http-server.ts 동작과 일치합니다.
• 한 문장만 병합 후 바로잡겠습니다. 코드상 CORS_ORIGIN은 ALLOWED_ORIGINS에 더해지지 않고, ALLOWED_ORIGINS가 비어 있을 때만 허용 기준으로 쓰입니다(*면 모든 출처, 아니면 그 출처 하나). 그래서 "설정하지 않으면 브라우저 요청은 모두 차단"도 CORS_ORIGIN까지 비어 있을 때의 이야기입니다.