haechi 0.3.2

package/docs/current/risk-register-release-gate.md

@@ -0,0 +1,154 @@
+# Haechi Risk Register and Release Gates
+
+- Status: Draft 0.3
+- Date: 2026-06-10
+- Target version: 0.3.2
+- Branch: `irae/risk-resolution`
+
+## 1. Current Assessment
+
+0.3.2 resolves the additional security and operational risks identified during the full 0.3.1 code review, meeting the bar for developer preview. Publishing to GitHub and distributing on npm as a developer preview are permitted. Actual npm publish must pass the following external operator gates: npm account authentication, package ownership, and successful execution of the GitHub release workflow.
+
+| Category | Judgment | Rationale |
+|---|---|---|
+| GitHub public | Allowed | Security limitations, threat model, shared responsibility, and developer preview language are documented |
+| GitHub release/tag | Allowed | Must be presented as developer preview, not production-ready |
+| npm developer preview | Conditionally allowed | Requires passing `npm run release:preflight`, then running `release:preflight:npm` and a provenance publish from an authenticated account |
+| npm stable | On hold | Stable label prohibited until 1.0 API stability, production KMS/HSM/Vault reference adapter, and stream-aware enforcement are in place |
+| Production use | Prohibited | 0.3.2 is a self-hosted developer preview; production auth/authz/key custody is the user's responsibility |
+
+## 2. Release Gates
+
+| Gate | Target | Criteria | Current Status |
+|---|---|---|---|
+| G0 | GitHub source publication | Tests pass, security limitations documented, no plaintext audit leak | Pass |
+| G1 | GitHub pre-release | P0 code risks resolved, no production-ready language | Pass |
+| G2 | npm developer preview | P0 resolved, preflight/SBOM/provenance paths ready, npm auth confirmed | Conditional Pass |
+| G3 | npm stable | P1 production reference, stream-aware enforcement, API stability hardened | Blocked |
+
+## 3. P0 Distribution-Blocking Risk Status
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P0-REL-001 | npm authentication/authorization unresolved | External Gate | Gated via `release:preflight:npm`, GitHub release workflow, and `npm publish --provenance --access public`. Actual authentication requires an operator |
+| P0-REL-002 | Proxy exposed to external network | Resolved | Non-loopback bind fails by default; `--allow-remote-bind` must be specified explicitly |
+| P0-REL-003 | Streaming request handling unclear | Resolved | `stream: true` defaults to 501 fail-closed; `streaming.requestMode: "pass-through"` must be set explicitly |
+| P0-REL-004 | `responseProtection` failure mode unclear | Resolved | Non-JSON, invalid JSON, compressed, and oversized responses are fail-closed; explicit allow policies are separated |
+| P0-REL-005 | Local dev key misunderstood as production key | Resolved | `init`, README, and SECURITY warn that the dev-only key is not a production key provider |
+| P0-REL-006 | npm package trust overstated | Resolved | package description, README, and SECURITY updated to reflect experimental developer preview status |
+
+## 4. P1 Security Design Risk Status
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P1-SEC-001 | KMS/HSM/Vault not supported | Resolved for OSS core | `createRuntime(config, { cryptoProvider })` external crypto provider injection; fails closed if no external provider is supplied |
+| P1-SEC-002 | TokenVault permission model insufficient | Resolved | `revealPolicy: "disabled"` is the default; `--allow-dev-reveal`, metadata export, retention/purge timestamps added |
+| P1-SEC-003 | Audit integrity insufficient | Resolved | JSONL audit SHA-256 hash chain and `verifyAuditChain` |
+| P1-SEC-004 | No plugin runtime | Resolved by gating | Dynamic runtime is rejected; only `manifest-only` plugins pass |
+| P1-SEC-005 | Policy conflict handling insufficient | Resolved | Downgrading a stronger action (e.g., preset block) to a weaker one fails closed on conflict |
+| P1-SEC-006 | Regex-based filter accuracy limited | Resolved for preview | KR RRN checksum, Luhn, and unsafe custom regex restrictions added. ML/classifier plugin is in the stable backlog |
+| P1-SEC-007 | AAD/replay/stream extension insufficient | Resolved for preview | AAD hash mismatch is explicit; streaming is blocked by default. Stream sequence/replay cache required when stream support is introduced |
+| P1-SEC-008 | MCP security contract incomplete | Resolved for preview | JSON-RPC 2.0 required, method allowlist, params/result protection toggles. OAuth resource binding is the responsibility of the external MCP layer |
+
+## 5. P1 Operational/Deployment Risk Status
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P1-OPS-001 | No CI | Resolved | `.github/workflows/ci.yml` |
+| P1-OPS-002 | No SBOM/provenance | Resolved | `npm run sbom`, `.github/workflows/npm-publish.yml`, `publishConfig.provenance` |
+| P1-OPS-003 | No real vLLM/Ollama/llama.cpp integration tests | Resolved for preview | Env-gated optional local inference integration tests added. CI skips when no external model server is present |
+| P1-OPS-004 | Performance/large payload not measured | Resolved for preview | Request/response byte limits, `npm run bench:payload` |
+| P1-OPS-005 | npm ownership unconfirmed | External Gate | `npm run release:preflight:npm` from an authenticated npm account required; post-publish `npm view haechi version` needed |
+
+## 5.1 Additional Security Review Risk Resolution Status
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P1-SEC-009 | Proxy absolute-form request target could bypass upstream or enable SSRF | Resolved | Absolute/protocol-relative request targets are rejected as `haechi_invalid_proxy_target`; upstream URL combines only path and search with the fixed upstream |
+| P1-SEC-010 | `responseProtection.maxBytes` checked after full buffering, enabling memory DoS | Resolved | Upstream body is read via stream reader with a byte cap; excess immediately triggers cancel/fail-closed. `failureMode: "allow"` cannot bypass the hard byte cap |
+| P1-SEC-011 | Concurrent writes to audit hash chain could cause sequence/previousHash collision | Resolved | JSONL audit sink serializes hash-chain record building and append via per-sink write queue and lock file |
+| P1-SEC-012 | PII/secrets in JSON object keys could be exposed in audit paths or token metadata | Resolved | Detection `pathText` records `key_<hash>` structured paths instead of raw key names |
+| P1-SEC-013 | Concurrent tokenization/purge in local TokenVault could cause lost updates | Resolved | Vault mutation queue, lock file, and atomic write via temp-file-then-rename applied |
+| P1-SEC-014 | No audit record for `streaming.requestMode: "pass-through"` and `responseProtection.failureMode: "allow"` bypass decisions | Resolved | Decision audit records `streaming_request_pass_through` and `response_unprotected_allowed/blocked` without raw payload |
+| P1-SEC-015 | MCP `allowedMethods` element type validation insufficient | Resolved | Config validation strengthened to allow only non-empty strings |
+| P1-OPS-006 | GitHub Actions major-tag pinning could allow supply-chain drift | Resolved | `checkout`, `setup-node`, and `upload-artifact` pinned to verified commit SHAs |
+
+## 5.2 Second Full Code Review Risk Resolution Status (0.3.2)
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P0-SEC-016 | Ollama `/api/chat` and `/api/generate` default to streaming when `stream` is omitted, allowing streaming block bypass | Resolved | `streamingDefault` introduced in protocol adapter; requests without explicit `stream: false` are treated as streaming and default to 501 fail-closed |
+| P1-SEC-017 | Token reveal/purge not recorded in audit | Resolved | `auditSink` injected into local TokenVault; `reveal_allowed/denied/failed`, `purge`, and `purge_expired` decision audits recorded (no plaintext) |
+| P1-SEC-018 | Privacy profile could silently weaken user-specified policies | Resolved | `applyPrivacyProfile` compares ACTION_STRENGTH and only allows strengthening |
+| P1-SEC-019 | Decrypt ignores envelope `kid`; `init --force` destroys existing keys, permanently losing vault/ciphertext | Resolved | Key selection based on `kid`; `--force` now performs rotation that preserves existing keys as `retired` |
+| P1-SEC-020 | Policy bundle signing reuses the AES encryption key as an HMAC key, violating key separation | Resolved | Domain-separated signing key derived with `haechi:policy-bundle:signing:v1` |
+| P1-SEC-021 | `retentionDays` only blocks reveal but does not delete expired data | Resolved | Expired tokens are automatically pruned on vault mutation; `purgeExpired()` and `haechi token-purge --expired` added |
+| P1-SEC-022 | No upstream fetch timeout, enabling connection exhaustion | Resolved | `limits.upstreamTimeoutMs` (default 120000) and `504 haechi_upstream_timeout` |
+| P1-SEC-023 | JSON numbers (card numbers) and PII/secrets in object keys not detected or transformed | Resolved | Number leaves and object keys included in detection/transform scope (keys are renamed on enforce) |
+| P1-OPS-007 | Stale lock file causes permanent audit/vault write failure | Resolved | Stale locks older than 30 seconds are automatically stolen and reacquired |
+| P1-OPS-008 | Audit append re-reads the entire file on every write (O(n²)) | Resolved | File tail-chunk read for O(1) append |
+| P2-SEC-024 | Unknown `target.type` silently falls back to openai-compatible | Resolved | Unknown type fails closed at config validation |
+| P2-SEC-025 | Short-value masking exposes most of the value (4 of 5 characters) | Resolved | Values of 8 characters or fewer are fully masked |
+| P2-SEC-026 | Assignment-secret redaction removes the key name as well | Resolved | Lookbehind pattern replaces only the secret value |
+| P2-SEC-027 | MCP notifications receive error responses in violation of the JSON-RPC spec; batch handling unspecified | Resolved | Notifications are dropped; batch is explicitly rejected fail-closed |
+| P2-SEC-028 | Proxy internal error messages exposed to clients | Resolved | Unexpected errors return a generic message; details go to stderr |
+| P2-DOC-005 | Default dry-run + responseProtection off could be mistaken for "protection active" | Resolved | Proxy startup and `protect` output explicitly warn when enforcement is inactive |
+
+Base64/encoded-value decode inspection, query-string inspection, and audit tail truncation detection are explicitly excluded and documented in the threat model (0.4+ backlog).
+
+## 6. P2 Product/Documentation Risk Status
+
+| ID | Risk | Status | Resolution evidence |
+|---|---|---|---|
+| P2-DOC-001 | Separate threat model document missing | Resolved | `docs/current/threat-model.md` |
+| P2-DOC-002 | Shared responsibility documentation insufficient | Resolved | `docs/current/shared-responsibility.md` |
+| P2-DOC-003 | Region/privacy profile not implemented | Resolved for baseline | `haechi/privacy-profiles`, `privacy.profile` applied at runtime |
+| P2-DOC-004 | No API stability policy | Resolved | `docs/current/api-stability.md` |
+
+## 7. npm Developer Preview Pre-Distribution Checklist
+
+Current external npm gate check results:
+
+- `npm whoami`: `raeseoklee`
+- `npm view haechi version`: `E404 Not Found`
+
+The `haechi` name appears to be available, but package ownership is confirmed only after the first successful publish from an authenticated account. `release:preflight:npm` verifies authentication and blocks duplicate publish of `haechi@<current version>`; E404 before the first publish is treated as a passing condition.
+
+1. `npm run release:preflight`
+2. `npm run sbom`
+3. `npm run bench:payload`
+4. `npm run release:preflight:npm`
+5. Create GitHub release
+6. GitHub Actions `Publish npm Developer Preview` succeeds
+7. Confirm actual published version with `npm view haechi version`
+
+## 8. Remaining Non-Blocking Backlog
+
+| Version | Goal | Remaining scope |
+|---|---|---|
+| 0.4.0 | Token round-trip and adoption | Request-scoped response detokenization, deterministic tokenization (derived key), `haechi mcp-wrap` (bidirectional stdio), `haechi audit-verify`/`haechi status`, injection detection type (default allow), PII-safe `identity` field and `authProvider` contract reserved. See `docs/current/release-0.4-implementation-scope.md` |
+| 0.5.0 | Streaming hardening | SSE/NDJSON stream inspection, stream sequence AAD, replay cache, stronger remote deployment guide |
+| 0.6.0 | Auth and operational controls | Built-in bearer auth, per-client policy scope, model allowlist/rate budget, Vault/AWS KMS reference adapter, external append-only audit sink, signed release artifacts, npm org (`@haechi/*`) acquisition |
+| 0.7.0 | Observability | npm workspaces migration, `@haechi/dashboard` read-only audit viewer (hash chain integrity display, summary/search/timeline) |
+| 1.0.0 | Stable API contract | Migration policy, long-term audit schema, plugin sandbox/runtime conformance, and dynamic loading of external auth/classifier packages that pass allowlist/manifest |
+
+Dynamic npm package loading is prohibited until the 1.0 plugin sandbox. External providers in 0.4–0.7 are supported only via `createRuntime(config, providers)` programmatic injection.
+
+## 9. Current Permitted Use
+
+0.3.2 is intended for use in the following contexts:
+
+- Local development environments
+- Sample payload validation
+- OpenAI-compatible/vLLM/Ollama/llama.cpp proxy PoC
+- Policy/filter/audit pipeline review
+- GitHub code review and security design discussion
+- npm developer preview
+
+0.3.2 is not intended for the following uses:
+
+- Production LLM gateway
+- Proxy directly exposed to the internet
+- Processing real customer/patient/payment/authentication data
+- Compliance evidence or legal conformance proof
+- npm stable package

package/docs/current/shared-responsibility.ko.md

@@ -0,0 +1,38 @@
+# Haechi Shared Responsibility
+
+- 문서 상태: Draft 0.1
+- 작성일: 2026-06-10
+- 기준 버전: 0.3.2
+
+## 1. 책임 매트릭스
+
+| 영역 | Haechi 제공 | 사용자/운영자 책임 |
+|---|---|---|
+| 로컬 개발 | CLI, default config, dev key 생성 | dev key를 운영/공유 환경에 재사용하지 않음 |
+| 정책 집행 | redact/mask/tokenize/encrypt/block pipeline | 규제/조직 정책에 맞는 action 선택 |
+| HTTP proxy | loopback 기본, remote bind guard, body/response limit | 인증, TLS termination, firewall, upstream auth |
+| Streaming | 기본 차단 | pass-through 사용 시 보호 미적용 위험 수용 |
+| TokenVault | 암호화 저장, reveal 기본 차단, purge | reveal 승인 절차, DSAR/retention 운영 |
+| Audit | 평문 제거, hash chain | append-only storage, backup, 보존 기간, 외부 서명 |
+| Key custody | local dev key, external crypto provider contract | KMS/HSM/Vault adapter 구현, rotation, access review |
+| Plugin | manifest validation, dynamic runtime 차단 | plugin code review, sandbox 제공 전 실행 금지 |
+| MCP | JSON-RPC/method allowlist | MCP server auth, resource consent, env secret allowlist |
+| Privacy profile | KR/EU/US baseline actions | 법률 검토, data residency, cross-border transfer evidence |
+
+## 2. 금지되는 기본 사용
+
+- `--allow-remote-bind`를 네트워크 통제 없이 사용
+- `.haechi/dev.keys.json`을 운영 데이터에 사용
+- `streaming.requestMode: "pass-through"`를 보호 적용으로 오해
+- `responseProtection.failureMode: "allow"`를 민감 데이터 경로에 사용
+- `token-reveal --allow-dev-reveal`를 운영 복원 절차로 사용
+
+## 3. 운영 전환 체크리스트
+
+1. 외부 crypto provider 또는 KMS/HSM/Vault adapter를 연결한다.
+2. proxy 앞단에 인증, TLS, firewall, rate limit을 둔다.
+3. responseProtection을 켜고 fail-closed를 유지한다.
+4. streaming endpoint는 별도 stream-aware gateway가 준비되기 전 차단한다.
+5. audit sink를 append-only 또는 외부 서명 저장소로 보낸다.
+6. TokenVault reveal 승인/보존/삭제 절차를 문서화한다.
+7. privacy profile은 법률 검토 결과로 보정한다.

package/docs/current/shared-responsibility.md

@@ -0,0 +1,38 @@
+# Haechi Shared Responsibility
+
+- Status: Draft 0.1
+- Date: 2026-06-10
+- Target version: 0.3.2
+
+## 1. Responsibility Matrix
+
+| Area | Haechi provides | User/operator responsibility |
+|---|---|---|
+| Local development | CLI, default config, dev key generation | Do not reuse dev keys in production or shared environments |
+| Policy enforcement | redact/mask/tokenize/encrypt/block pipeline | Select actions appropriate to regulatory and organizational policy |
+| HTTP proxy | Loopback default, remote bind guard, body/response limits | Authentication, TLS termination, firewall, upstream auth |
+| Streaming | Blocked by default | Accept the risk of no protection when using pass-through |
+| TokenVault | Encrypted storage, reveal blocked by default, purge | Reveal approval workflow, DSAR/retention operations |
+| Audit | Plaintext removal, hash chain | Append-only storage, backup, retention period, external signing |
+| Key custody | Local dev key, external crypto provider contract | KMS/HSM/Vault adapter implementation, rotation, access review |
+| Plugin | Manifest validation, dynamic runtime blocked | Plugin code review, do not execute before sandbox is available |
+| MCP | JSON-RPC/method allowlist | MCP server auth, resource consent, env secret allowlist |
+| Privacy profile | KR/EU/US baseline actions | Legal review, data residency, cross-border transfer evidence |
+
+## 2. Prohibited default usage
+
+- Using `--allow-remote-bind` without network controls
+- Using `.haechi/dev.keys.json` with production data
+- Treating `streaming.requestMode: "pass-through"` as an applied protection
+- Using `responseProtection.failureMode: "allow"` on sensitive data paths
+- Using `token-reveal --allow-dev-reveal` as a production recovery procedure
+
+## 3. Production transition checklist
+
+1. Connect an external crypto provider or KMS/HSM/Vault adapter.
+2. Place authentication, TLS, a firewall, and rate limiting in front of the proxy.
+3. Enable responseProtection and keep it fail-closed.
+4. Block streaming endpoints until a dedicated stream-aware gateway is ready.
+5. Send the audit sink to an append-only or externally signed storage backend.
+6. Document the TokenVault reveal approval, retention, and deletion procedures.
+7. Calibrate privacy profiles based on legal review findings.

package/docs/current/threat-model.ko.md

@@ -0,0 +1,68 @@
+# Haechi Threat Model
+
+- 문서 상태: Draft 0.1
+- 작성일: 2026-06-10
+- 기준 버전: 0.3.2
+
+## 1. 보호 대상
+
+Haechi가 보호하려는 주요 자산은 다음이다.
+
+| 자산 | 예시 | 보호 목표 |
+|---|---|---|
+| Prompt/context payload | chat messages, tool arguments, MCP params | 모델/도구/로그로 이동하기 전 정책 집행 |
+| Tool/resource result | MCP result, local inference response | 응답 내 PII/secret 재유출 차단 |
+| TokenVault record | tokenized PII mapping | 저장 시 암호화, reveal 기본 차단 |
+| Audit event | detection metadata, decision summary | 평문 비포함, hash chain 무결성 |
+| Crypto envelope | encrypted segments | canonical AAD binding, key provider 교체성 |
+| Plugin manifest | custom provider/filter declaration | capability disclosure, dynamic runtime 차단 |
+
+## 2. 신뢰 경계
+
+| 경계 | 신뢰 수준 | 기본 통제 |
+|---|---|---|
+| CLI local process | 개발자 로컬 신뢰 | dev key 경고, dry-run 기본값 |
+| HTTP proxy listener | 비신뢰 client 입력 | loopback bind 기본, remote bind 명시 플래그 |
+| Upstream model/tool server | 비신뢰 또는 부분 신뢰 | request/response protection, uninspectable response fail-closed |
+| Streaming response | 현재 비검사 영역 | `stream: true` 기본 차단 |
+| MCP stdio peer | 부분 신뢰 | JSON-RPC 2.0 요구, method allowlist |
+| Local filesystem | 부분 신뢰 | local key/token vault 0600, audit hash chain |
+| External provider/plugin | 비신뢰 | provider method contract, plugin manifest-only gate |
+
+## 3. 주요 위협과 통제
+
+| 위협 | 영향 | 현재 통제 |
+|---|---|---|
+| 인터넷 노출 proxy | 인증 없는 LLM gateway | non-loopback bind 기본 실패 |
+| streaming 우회 | SSE/NDJSON 평문 유출 | streaming request 기본 실패 |
+| Ollama 암묵 streaming 우회 | `stream` 생략 시 NDJSON 평문 유출 | `/api/chat`·`/api/generate`는 `stream: false` 명시 없으면 streaming으로 간주해 기본 차단 |
+| 비JSON/압축/대용량 응답 | responseProtection 우회 | fail-closed response policy |
+| token reveal 남용 | tokenized PII 복원 | revealPolicy 기본 disabled, reveal/purge 결정 audit 기록 |
+| audit 변조 | 감사 증거 신뢰 저하 | SHA-256 hash chain |
+| policy 약화 override | block preset 무력화 | unsafe downgrade conflict 차단, privacy profile은 강화만 가능 |
+| ReDoS custom regex | CPU 고갈 | nested quantifier/backreference 제한 |
+| plugin runtime 착각 | 동적 코드 실행 위험 | manifest-only runtime만 허용 |
+| MCP tool method 오남용 | 예상 밖 tool/resource 접근 | allowedMethods 기반 거부 |
+| key custody 오해 | local dev key 운영 사용 | external crypto provider injection, dev key 경고 |
+| 행 걸린 upstream | proxy 연결 고갈 | `limits.upstreamTimeoutMs` 기본 120s, 초과 시 504 fail |
+| signing/encryption 키 혼용 | key separation 위반 | policy bundle 서명 키를 domain-separated 파생 키로 분리 |
+| JSON number/object key 은닉 | 카드번호 등 비문자열 leaf 미탐지 | number leaf와 object key도 detection/transform 대상 |
+
+## 4. 명시적 제외
+
+0.3.2는 다음을 보장하지 않는다.
+
+- 운영 KMS/HSM/Vault adapter 자체 제공
+- internet-facing gateway 인증/인가
+- SSE/NDJSON stream inspection
+- 법적 컴플라이언스 인증
+- 모델 hallucination, prompt injection 완전 방어
+- 외부 MCP server의 OAuth/resource binding 검증
+- base64/URL-encoded 값, 유니코드 난독화 값의 디코딩 후 검사
+- URL query string 내 민감값 검사 (JSON body만 검사)
+- audit hash chain의 tail truncation(꼬리 절단) 탐지 — 체인은 변조/재정렬은 탐지하지만 마지막 N개 레코드 삭제는 외부 보존 사본 없이는 탐지 불가
+- JSON-RPC batch 메시지 처리 (MCP stdio filter는 batch를 fail-closed로 거부)
+
+## 5. 남은 운영 전제
+
+운영 사용자는 Haechi 외부에서 네트워크 접근 제어, upstream 인증, secret injection, key custody, 로그 보존, DSAR/삭제 요청 처리, 법적 transfer 근거를 책임져야 한다.

package/docs/current/threat-model.md

@@ -0,0 +1,68 @@
+# Haechi Threat Model
+
+- Status: Draft 0.1
+- Date: 2026-06-10
+- Target version: 0.3.2
+
+## 1. Assets Under Protection
+
+The primary assets Haechi protects are:
+
+| Asset | Examples | Protection Goal |
+|---|---|---|
+| Prompt/context payload | chat messages, tool arguments, MCP params | Policy enforcement before data reaches model/tool/logs |
+| Tool/resource result | MCP result, local inference response | Prevent re-leakage of PII/secrets in responses |
+| TokenVault record | tokenized PII mapping | Encrypted at rest, reveal blocked by default |
+| Audit event | detection metadata, decision summary | No plaintext content, hash chain integrity |
+| Crypto envelope | encrypted segments | Canonical AAD binding, swappable key provider |
+| Plugin manifest | custom provider/filter declaration | Capability disclosure, dynamic runtime blocked |
+
+## 2. Trust Boundaries
+
+| Boundary | Trust Level | Default Controls |
+|---|---|---|
+| CLI local process | Developer local trust | Dev key warning, dry-run default |
+| HTTP proxy listener | Untrusted client input | Loopback bind by default, remote bind requires explicit flag |
+| Upstream model/tool server | Untrusted or partially trusted | Request/response protection, uninspectable response fail-closed |
+| Streaming response | Currently uninspected | `stream: true` blocked by default |
+| MCP stdio peer | Partially trusted | JSON-RPC 2.0 required, method allowlist |
+| Local filesystem | Partially trusted | Local key/token vault at 0600, audit hash chain |
+| External provider/plugin | Untrusted | Provider method contract, plugin manifest-only gate |
+
+## 3. Key Threats and Controls
+
+| Threat | Impact | Current Control |
+|---|---|---|
+| Internet-exposed proxy | Unauthenticated LLM gateway | Non-loopback bind fails by default |
+| Streaming bypass | SSE/NDJSON plaintext leak | Streaming requests fail by default |
+| Ollama implicit streaming bypass | NDJSON plaintext leak when `stream` is omitted | `/api/chat` and `/api/generate` are treated as streaming unless `stream: false` is explicit; blocked by default |
+| Non-JSON / compressed / oversized response | responseProtection bypass | Fail-closed response policy |
+| Token reveal abuse | Restoration of tokenized PII | `revealPolicy` disabled by default; reveal/purge decisions recorded in audit |
+| Audit tampering | Degraded trust in audit evidence | SHA-256 hash chain |
+| Policy-weakening override | Neutralizing block presets | Unsafe downgrade conflicts blocked; privacy profile can only strengthen |
+| ReDoS via custom regex | CPU exhaustion | Nested quantifier/backreference restrictions |
+| Plugin runtime confusion | Dynamic code execution risk | Manifest-only runtime permitted |
+| MCP tool method misuse | Unexpected tool/resource access | Rejected based on `allowedMethods` |
+| Key custody misunderstanding | Local dev key used in production | External crypto provider injection, dev key warning |
+| Hung upstream | Proxy connection exhaustion | `limits.upstreamTimeoutMs` default 120 s; 504 fail on timeout |
+| Signing/encryption key conflation | Key separation violation | Policy bundle signing key isolated as a domain-separated derived key |
+| JSON number / object key concealment | Undetected non-string leaves such as card numbers | Number leaves and object keys included in detection/transform scope |
+
+## 4. Explicit Exclusions
+
+0.3.2 does not guarantee:
+
+- A production KMS/HSM/Vault adapter
+- Authentication/authorization for internet-facing gateways
+- SSE/NDJSON stream inspection
+- Legal compliance certification
+- Complete defense against model hallucination or prompt injection
+- OAuth/resource binding validation for external MCP servers
+- Inspection of base64/URL-encoded values or unicode-obfuscated values after decoding
+- Detection of sensitive values in URL query strings (JSON body only)
+- Audit hash chain tail truncation detection — the chain detects tampering and reordering, but deletion of the last N records cannot be detected without an externally preserved copy
+- JSON-RPC batch message processing (the MCP stdio filter rejects batches fail-closed)
+
+## 5. Remaining Operational Assumptions
+
+Production users are responsible for the following outside of Haechi: network access control, upstream authentication, secret injection, key custody, log retention, handling DSAR/deletion requests, and establishing a legal transfer basis.

package/examples/llm-prompt-filtering/input.json

@@ -0,0 +1,13 @@
+{
+  "model": "demo-model",
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are a helpful assistant."
+    },
+    {
+      "role": "user",
+      "content": "Please summarize this customer note. Email: minji.kim@example.com, phone: 010-1234-5678, token: sk_demo_1234567890abcdef1234567890abcdef."
+    }
+  ]
+}

package/examples/plugins/custom-filter.plugin.json

@@ -0,0 +1,29 @@
+{
+  "haechiPlugin": {
+    "id": "example-custom-filter",
+    "version": "0.1.0",
+    "kind": "filter-engine",
+    "runtime": "manifest-only",
+    "entrypoint": "./manifest-only",
+    "compatibility": {
+      "haechiCore": ">=0.2.0 <0.3.0"
+    },
+    "capabilities": {
+      "readsPlaintext": true,
+      "writesPlaintext": false,
+      "networkEgress": false,
+      "fileWrite": false,
+      "auditWrite": false,
+      "externalSecrets": false
+    },
+    "dataHandling": {
+      "storesPayload": false,
+      "retention": "none",
+      "logsRawPayload": false
+    },
+    "tests": {
+      "conformance": "./fixtures/conformance.json",
+      "negative": "./fixtures/negative.json"
+    }
+  }
+}

package/haechi.config.example.json

@@ -0,0 +1,70 @@
+{
+  "mode": "dry-run",
+  "target": {
+    "type": "llm-http",
+    "adapter": "openai-compatible",
+    "upstream": "http://127.0.0.1:9999"
+  },
+  "proxy": {
+    "host": "127.0.0.1",
+    "port": 1016
+  },
+  "responseProtection": {
+    "enabled": false,
+    "mode": "enforce",
+    "failureMode": "fail-closed",
+    "allowNonJson": false,
+    "allowCompressed": false,
+    "maxBytes": 1048576
+  },
+  "streaming": {
+    "requestMode": "block"
+  },
+  "limits": {
+    "maxRequestBytes": 1048576,
+    "upstreamTimeoutMs": 120000
+  },
+  "policy": {
+    "mode": "dry-run",
+    "presets": [
+      "korean-pii",
+      "secrets-only",
+      "llm-redact"
+    ],
+    "defaultAction": "redact",
+    "actions": {
+      "card": "block"
+    }
+  },
+  "filters": {
+    "customRules": []
+  },
+  "keys": {
+    "provider": "local",
+    "keyFile": ".haechi/dev.keys.json"
+  },
+  "audit": {
+    "sink": "jsonl",
+    "path": ".haechi/audit.jsonl"
+  },
+  "tokenVault": {
+    "provider": "local",
+    "path": ".haechi/token-vault.json",
+    "revealPolicy": "disabled",
+    "retentionDays": 30
+  },
+  "privacy": {
+    "profile": null
+  },
+  "mcp": {
+    "allowedMethods": [
+      "initialize",
+      "tools/call",
+      "resources/read",
+      "prompts/get"
+    ],
+    "protectParams": true,
+    "protectResults": true,
+    "requireJsonRpc": true
+  }
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "haechi",
+  "version": "0.3.2",
+  "description": "Experimental developer preview for self-hosted AI context enforcement across LLM, MCP, vLLM, Ollama, and agent traffic.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raeseoklee/haechi.git"
+  },
+  "homepage": "https://github.com/raeseoklee/haechi#readme",
+  "bugs": {
+    "url": "https://github.com/raeseoklee/haechi/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "llm",
+    "mcp",
+    "ai-security",
+    "privacy",
+    "redaction",
+    "tokenization",
+    "ollama",
+    "vllm",
+    "llama-cpp"
+  ],
+  "bin": {
+    "haechi": "packages/cli/bin/haechi.mjs"
+  },
+  "exports": {
+    ".": "./packages/core/index.mjs",
+    "./audit": "./packages/audit/index.mjs",
+    "./core": "./packages/core/index.mjs",
+    "./crypto": "./packages/crypto/index.mjs",
+    "./filter": "./packages/filter/index.mjs",
+    "./mcp-stdio": "./packages/mcp-stdio/index.mjs",
+    "./plugin": "./packages/plugin/index.mjs",
+    "./policy": "./packages/policy/index.mjs",
+    "./policy-bundle": "./packages/policy-bundle/index.mjs",
+    "./privacy-profiles": "./packages/privacy-profiles/index.mjs",
+    "./protocol-adapters": "./packages/protocol-adapters/index.mjs",
+    "./proxy": "./packages/proxy/index.mjs",
+    "./runtime": "./packages/cli/runtime.mjs",
+    "./token-vault": "./packages/token-vault/index.mjs"
+  },
+  "files": [
+    "README.md",
+    "SECURITY.md",
+    "LICENSE",
+    "haechi.config.example.json",
+    "packages/",
+    "examples/",
+    "docs/current/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:dry": "npm pack --dry-run",
+    "scan:stale-names": "node scripts/stale-name-scan.mjs",
+    "sbom": "node scripts/generate-sbom.mjs",
+    "bench:payload": "node scripts/bench-payload.mjs",
+    "release:preflight": "node scripts/release-preflight.mjs",
+    "release:preflight:npm": "node scripts/release-preflight.mjs --require-npm-auth",
+    "haechi": "node packages/cli/bin/haechi.mjs",
+    "demo:init": "node packages/cli/bin/haechi.mjs init --force",
+    "demo:protect": "node packages/cli/bin/haechi.mjs protect examples/llm-prompt-filtering/input.json --config haechi.config.json",
+    "demo:report": "node packages/cli/bin/haechi.mjs report --audit .haechi/audit.jsonl"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}