humanize-helper

menu.io.kr/humanize 의 로컬 헬퍼. 방문자 본인 PC에서 도는 작은 HTTP 데몬으로, 브라우저가 직접 붙어 본인 로그인된 claude 구독을 claude -p로 구동해 윤문한다. 우리 서버(Vercel)는 이 트래픽을 보지 않는다 — 윤문 텍스트는 PC 밖으로 나가지 않는다.

선결 조건

• Claude Code(claude) 설치 + 로그인된 구독 (Max 권장). 설치 스크립트가 없으면 자동 설치한다.
• ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN 미설정(있으면 구독이 아니라 API 종량 과금으로 샌다 — 헬퍼가 감지해 차단). claude -p는 구독 사용량 한도에서 차감된다(2026-06 기준, support.claude.com/articles/15036540).
• 브라우저: Chrome / Edge 데스크톱(loopback). Safari·크로스기기는 지원하지 않는다.
• tmux·ctc·Python·Node 불필요(단일 바이너리).

설치 (비개발자 원클릭)

# macOS / Linux
curl -fsSL https://menu.io.kr/install/humanize.sh | bash

# Windows (PowerShell)
irm https://menu.io.kr/install/humanize.ps1 | iex

curl/irm 으로 받은 파일은 macOS 격리·Windows MOTW가 안 붙어 Gatekeeper/SmartScreen 경고 없이 실행된다(코드서명 인증서 불필요). 스크립트가 claude·헬퍼를 설치하고, 로그인 시 자동 실행을 등록하고, 브라우저를 열어 자동 페어링한다.

개발자용:

pnpm bridge:build && pnpm bridge      # 레포에서 (node)
npx -y @ddalkkak/humanize-bridge      # 배포 후 (Node 필요)

동작

기동하면 브라우저가 자동으로 열리고 토큰을 URL 프래그먼트(#hb=<port>.<token>)에 담아 자동 페어링된다. Chrome의 "로컬 네트워크 접근 허용"만 한 번 누르면 연결 완료. 이후 페이지에서 글을 붙여넣고 실행하면, 브라우저가 127.0.0.1의 헬퍼로 직접 보내고 헬퍼가 claude -p로 윤문해 돌려준다.

환경변수

| 변수 | 기본 | 설명 | |---|---|---| | HUMANIZE_BRIDGE_PORT | 8770 | 시작 포트. 사용 중이면 +4까지 스캔(8770–8774). | | HUMANIZE_BRIDGE_TOKEN | 랜덤 | 고정 토큰(자동 실행 시 무중단 재연결). 미설정이면 시작마다 새로 발급. | | HUMANIZE_BRIDGE_ORIGINS | — | 쉼표구분 추가 허용 Origin. 기본 허용은 menu.io.kr 뿐. | | HUMANIZE_BRIDGE_DEV | — | 1이면 localhost:3000/127.0.0.1:3000을 추가 허용(우리 dev 전용). end-user 빌드엔 절대 켜지 않는다 — /pair가 토큰을 내주므로 :3000의 임의 로컬 웹이 토큰을 탈취할 수 있다. | | HUMANIZE_BRIDGE_MAX_TURNS | 60 | 롤링 5시간 윈도당 최대 호출 수(구독 소진 방지). | | HUMANIZE_BRIDGE_MIN_INTERVAL_MS | 1500 | 호출 최소 간격. | | HUMANIZE_BRIDGE_PAGE | https://menu.io.kr/humanize | 자동으로 열 페이지(자동 페어링 링크 베이스). | | HUMANIZE_BRIDGE_NO_OPEN | — | 1이면 브라우저 자동 열기 비활성(자동 실행 시 사용). | | HUMANIZE_MODEL | opus | 윤문 품질용 모델 별칭. |

보안 모델

호출마다 사용자의 5시간윈도 구독을 소비하므로 다음으로 보호한다:

• 127.0.0.1 전용 바인딩 — 외부 노출 안 함.
• Host 헤더 핀 — 정확히 loopback:port만(DNS 리바인딩 방어).
• Origin 허용목록 — 기본 menu.io.kr만(+ HUMANIZE_BRIDGE_ORIGINS). dev origin은 HUMANIZE_BRIDGE_DEV=1로만 추가.
• /pair 토큰 부트스트랩 — Host핀+Origin게이트를 통과한 요청에만 현재 토큰을 무턴 발급(복붙 없이 자동 페어링). 토큰은 곧 /humanize 접근권이므로 허용 origin을 좁게 유지하는 게 전제다(그래서 dev origin을 기본에서 뺀다).
• application/json 강제 — simple POST CSRF 차단.
• Bearer 토큰 — constant-time 비교, 콘솔에만 출력(파일·로그에 안 남김).
• 레이트리밋 + 5시간 턴 예산(영속) — 직렬 해머링(구독 소진) 차단. 사용량을 설치 단위 안정 ID로 디스크에 영속해 재시작으로 한도를 리셋하는 우회까지 막는다.
• 입출력 위생 — 입력·출력에서 숨김/포맷 유니코드(제로폭·양방향·소프트하이픈·한글필러·태그 등) 제거 + NFC. 인젝션 은닉·마커 분할·표시 왜곡 차단(출력 검증 assertNoLeak의 백스톱).
• 본문 32KB cap, 단일 세션 락, ANTHROPIC_API_KEY/TOKEN/BASE_URL env strip(claude -p가 구독으로만 돌게).

빌드

pnpm build              # tsc → dist (node/npx)
pnpm build:binary       # 현재 OS용 단일 바이너리 → dist/humanize-helper
pnpm build:binary:all   # 릴리스 4종(darwin-arm64/x64, linux-x64, windows-x64) → dist/release

릴리스는 dist/release/* 를 GitHub Releases에 업로드하면 설치 스크립트가 latest에서 받아간다.