haechi 0.3.2

package/docs/current/initial-plan-ai-llm-mcp-encryption.md

@@ -0,0 +1,214 @@
+# Initial Plan: AI/LLM/MCP-Specific Encryption Solution
+
+- Status: Draft 0.1
+- Date: 2026-06-08
+- Product: Haechi
+
+## 1. Strategic Direction
+
+An encryption solution purpose-built for AI, LLM, and MCP occupies a sharper market position than generic transport encryption. Most general-purpose API encryption products stop at HTTP payload protection, but AI systems introduce new categories of sensitive data: prompts, contexts, tool calls, resources, retrieval snippets, artifacts, and streaming events.
+
+MCP and A2A in particular blur security boundaries as the agent and tool ecosystem expands. Haechi can step into that boundary and become the product that turns "what information can be revealed in plaintext to which agent, tool, model, or provider" into an enforceable policy.
+
+The initial direction is an open-source / self-hosted security project, not a SaaS offering. The primary goal is therefore not a sellable control plane, but rather a clearly designed core interface, a replaceable reference engine, conformance tests, and published real-world MCP/LLM usage examples.
+
+## 2. Core Hypotheses
+
+| ID | Hypothesis | Validation Method |
+|---|---|---|
+| HYP-001 | Enterprises want to reduce plaintext prompt/tool output in LLM gateway logs. | AI gateway PoC |
+| HYP-002 | MCP server developers want a common module for safely exposing tool input/output and resource content. | MCP server sample |
+| HYP-003 | Agent-to-agent systems require per-task/context/artifact decryption authorization. | A2A adapter PoC |
+| HYP-004 | Separating "information the model must see" from "information the system only stores or forwards" increases the value of an encryption product. | Selective reveal demo |
+| HYP-005 | Security teams and OSS adopters want to control KMS/HSM, audit, policy, and redaction outside the agent framework. | OSS adopter / security reviewer interview |
+| HYP-006 | Enterprises treat PII filtering as a fundamental control on par with encryption when adopting LLM/MCP. | Korean PII filtering PoC |
+| HYP-007 | Global customers require per-region privacy profiles and control over data residency / model provider region. | Regional profile PoC |
+| HYP-008 | Customers require custom filtering that lets them register internal identifiers and confidential terms. | Custom rule DSL PoC |
+| HYP-009 | OSS adopters prefer a small, composable core where crypto, policy, filtering, and audit implementations are swappable over a fully integrated SaaS. | Plugin API PoC + conformance tests |
+| HYP-010 | Even a security tool will not spread if adoption is painful. A 5-minute local demo, 30-minute MCP/LLM PoC, and 1-day custom filter PoC must all be achievable. | Quickstart usability test |
+
+## 3. Priority Use Cases
+
+### 3.1 MCP Tool-Call Protection
+
+- The MCP client creates a tool call.
+- The Haechi policy evaluates tool name, arguments schema, tenant, user, and agent ID.
+- Sensitive arguments are protected via tokenization or envelope encryption.
+- The MCP server decrypts only in an authorized context.
+- Tool results are returned to the agent after default redaction.
+
+### 3.2 MCP Resource Protection
+
+- Resource URIs and content classifications are mapped to policy.
+- Resource content is encrypted with a tenant/resource scope key.
+- The LLM receives a redacted summary or reference token instead of the original content.
+- The audit log retains only the resource URI hash, policy ID, key ID, and decision ID.
+
+### 3.3 LLM Gateway Prompt Protection
+
+- System, developer, user, and tool messages are extracted from the HTTP request.
+- PII, secrets, credentials, source code, and customer data are detected.
+- A decision of reveal, redact, tokenize, or block is made before forwarding to the provider.
+- The plaintext exposure scope per provider and the audit events are recorded.
+
+### 3.4 PII Filtering
+
+- Filtering targets include prompts, MCP tool arguments, resource content, RAG snippets, and generated artifacts.
+- Structured identifiers such as Korean national ID numbers, alien registration numbers, and card numbers are detected first using deterministic rules and checksums.
+- Email addresses, phone numbers, postal addresses, account numbers, API keys, access tokens, and secrets are detected using rules and a pattern library.
+- Names, organizations, medical/health information, biometric data, and sensitive inferred information are detected using dictionary lookups, NER, and pluggable classifiers.
+- Detection results are handled according to policy: mask, redact, tokenize, encrypt, block, or human review.
+- Filtering audit logs retain only entity type, rule ID, confidence, action, and decision ID — never the original text.
+
+### 3.5 A2A Task/Artifact Protection
+
+- AgentCard discovery results are verified.
+- Task ID, context ID, source agent, and target agent are included in AAD.
+- Artifacts are encrypted with a task-scoped key.
+- Decryption attempts on an artifact from a different task, context, or agent are rejected.
+
+### 3.6 gRPC Streaming Protection
+
+- Service, method, and message type are used as policy context.
+- Stream/session keys and chunk nonces are kept separate.
+- Cancellation, retry, redelivery, and partial delivery are recorded as audit events.
+- Metadata leakage is checked separately.
+
+## 4. Architecture Draft
+
+```text
+AI App / Agent Runtime / MCP Host
+        |
+        v
+Haechi SDK / CLI / Local Proxy / Sidecar
+        |
+        +-- Core Pipeline
+        |      +-- normalize protocol message
+        |      +-- classify/filter
+        |      +-- decide policy
+        |      +-- encrypt/tokenize/redact
+        |      +-- emit safe audit
+        |
+        +-- Pluggable Providers
+        |      +-- CryptoProvider
+        |      +-- KeyProvider
+        |      +-- PolicyEngine
+        |      +-- FilterEngine
+        |      +-- TokenVault
+        |      +-- AuditSink
+        |
+        +-- Reference Engines
+        |      +-- JSON/YAML policy
+        |      +-- local key provider
+        |      +-- envelope crypto
+        |      +-- Korean/global PII filters
+        |      +-- JSONL audit
+        |
+        +-- MCP Adapter
+        +-- LLM HTTP Adapter
+        +-- gRPC Adapter
+        +-- A2A Adapter
+        |
+        v
+MCP Server / LLM Provider / Remote Agent / Tool API
+```
+
+## 5. Design Principles
+
+- **Protocol-aware**: Understands MCP methods, A2A tasks, gRPC methods, and LLM message roles — not just raw byte streams.
+- **Context-bound**: Ciphertext is bound to tenant, user, agent, model, task, context, tool, and resource.
+- **Selective reveal**: Only the minimum information the model needs is exposed in plaintext.
+- **Observability-safe**: Traces and replays contain no sensitive data by default.
+- **Provider-neutral**: Not locked into any specific LLM vendor.
+- **Fail-closed**: Payloads with a sensitive classification are blocked if policy evaluation fails.
+- **OSS-first**: Operates as a library, CLI, local proxy, or self-hosted sidecar — no hosted SaaS required.
+- **Pluggable by default**: The interface and test contract for crypto, key, policy, filtering, and audit matter more than the default implementation.
+- **Reference implementation is replaceable**: The default implementation is a baseline for learning and PoC; it must be replaceable to fit any user environment.
+- **Test fixtures as API**: Plugin authors must be able to verify compatibility using fixtures and conformance tests.
+- **Easy adoption**: Attachable to existing applications with minimal change cost via proxy, middleware, SDK wrapper, sidecar, or preset policy.
+- **Progressive hardening**: Start with dry-run / report-only to review detection results, then enforce redact / tokenize / encrypt / block incrementally.
+
+## 6. Initial Technology Stack Proposal
+
+| Area | Proposal |
+|---|---|
+| SDK | TypeScript/Node, Python |
+| Policy | JSON/YAML + JSON Schema |
+| Crypto format | JWE JSON Serialization or compact envelope |
+| KMS | Vault or AWS KMS |
+| MCP | Streamable HTTP proxy, stdio wrapper |
+| LLM adapter | OpenAI-compatible HTTP schema first |
+| Redaction | Deterministic detector + pluggable classifier |
+| Privacy filtering | Korean PII rules + checksum validators + custom entity rules |
+| Audit | JSON Lines + optional hash chain |
+| Tests | Golden fixtures, tamper/replay/cross-context negative tests |
+| Plugin contract | TypeScript interface + JSON Schema manifest + conformance test |
+| Distribution | GitHub repository, package examples, local CLI, SECURITY.md |
+| Developer UX | `haechi init`, preset policy, dry-run/report-only, copy-paste middleware |
+
+## 7. MVP Milestones
+
+| Phase | Deliverable | Completion Criteria |
+|---|---|---|
+| M0 | Developer quickstart | `haechi init`, local key, sample policy, dry-run, and MCP/LLM demo run in under 5 minutes |
+| M1 | MCP proxy skeleton | initialize/tools/call/resource read flow observable |
+| M2 | Policy engine | Per-method/tool/resource allow/block/redact/encrypt decisions |
+| M3 | PII filtering | Korean PII fixtures and secret fixtures detected and handled |
+| M4 | Global privacy profiles | EU-GDPR, US-CCPA-CPRA, US-HIPAA/PCI fixtures and region-deny |
+| M5 | Custom filter DSL | regex/dictionary/path-scope/action override with fixture tests |
+| M6 | Envelope crypto | Context-bound encrypt/decrypt with tamper tests |
+| M7 | KMS adapter | Local provider + one of Vault/AWS KMS |
+| M8 | LLM HTTP adapter | Chat/completion message redaction/encryption policy |
+| M9 | Audit | Verified no plaintext exposure of prompt/tool/resource/PII |
+| M10 | Security negative tests | Replay, wrong context, wrong agent, wrong tool, log leakage |
+| M11 | Crypto envelope hardening | Canonical AAD, nonce/replay cache, key lifecycle, signed policy |
+| M12 | Protocol security contracts | Per-adapter auth/lifecycle/metadata scrub contracts for MCP/A2A/gRPC/LLM |
+| M13 | OSS modular packages | `core`, `crypto`, `policy`, `filter`, `mcp`, `llm`, `audit`, `examples` package boundaries |
+| M14 | Plugin examples | Custom `PolicyEngine`, `FilterEngine`, and `AuditSink` examples with conformance tests |
+| M15 | Build-blocking QA gate | Plaintext leak, policy conflict, KMS fault, region-deny, DSL fuzzing, and plugin capability violation all fail CI |
+
+## 8. Top Risks
+
+| Risk | Description | Mitigation |
+|---|---|---|
+| Models cannot process ciphertext | Semantic information the LLM must act on ultimately requires reveal. | Selective reveal, tokenization, TEE roadmap |
+| MCP/A2A spec churn | The protocols are still evolving rapidly. | Adapter isolation, spec version field |
+| Tool-call log leakage | Agent frameworks may write separate logs. | Framework-specific log hook, redaction test |
+| Confusion with prompt injection | Encryption does not replace prompt injection defense. | Separate prompt security gate |
+| Difficulty protecting embeddings | Encrypting embeddings breaks similarity search. | Prioritize source text protection; separate embedding policy |
+| PII filter false positives/negatives | False positives degrade work quality; false negatives cause PII leakage. | Confidence threshold, human review, fixture tests |
+| PII exposure within the filter itself | Using an external classifier may re-expose PII during filtering. | Local-first detector, classifier privacy policy |
+| Global regulatory divergence | GDPR, CCPA, HIPAA, APPI, PDPA, and LGPD differ in definitions, rights, and transfer conditions. | Regional profile abstraction |
+| Cross-border transfer violations | External LLM provider regions may cause EU/UK/BR transfer restriction violations. | Region-aware provider allowlist |
+| Custom rule malfunction | Incorrect regex or allowlist can cause missed blocks or operational outages. | Validate/test/approve/rollback lifecycle |
+| Custom dictionary leakage | A customer's dictionary may itself be a trade secret. | Dictionary encryption, access audit |
+| Adoption difficulty | If installation and configuration are painful, OSS adoption and real-world use both fail. | 5-minute quickstart, dry-run, preset, minimal config, copy-paste examples |
+| AAD/nonce/replay vulnerabilities | Context-bound encryption can be bypassed without canonicalization and a replay cache. | Crypto envelope spec, stream sequencing tests |
+| Policy distribution tampering | Stale policy, client-supplied source labels, or unsigned rule packages can bypass hard-blocks. | Signed policy bundle, fail-closed validation |
+| Observability leakage | Plaintext prompt/tool output may appear in trace baggage, metric labels, exceptions, or crash dumps. | Telemetry sentinel tests |
+| Over-abstraction | Too many interfaces too early delays a working demo. | Implement core pipeline, MCP proxy, and filter/crypto reference first |
+| Plugin safety | A user-written plugin could send plaintext externally or bypass audit. | Capability manifest, fail-closed loading, conformance/negative tests |
+| OSS maintenance burden | More documentation and examples make security updates and compatibility management harder. | Narrow MVP, semantic versioning, compatibility matrix |
+| Compliance misrepresentation | OSS documentation may be mistaken for regulatory compliance assurance. | Non-compliance disclaimer in README and SECURITY.md |
+
+## 9. Next Documentation Work
+
+- AI threat model
+- MCP adapter SRS
+- LLM gateway policy schema
+- A2A task/artifact encryption design
+- Redaction/tokenization policy spec
+- Privacy filtering policy spec
+- Custom filtering DSL spec
+- Global privacy compliance matrix
+- Crypto envelope spec
+- Audit event schema
+- Expert gap review backlog
+- OSS modular architecture
+- Easy adoption guide and quickstart
+- Plugin API and conformance test spec
+- Protocol security contract spec
+- Self-hosted usage and shared responsibility note
+- Optional enterprise procurement evidence pack
+- Security test spec and red-team corpus
+- RAG/vector and agent memory protection design

package/docs/current/mvp-0.1-implementation-scope.ko.md

@@ -0,0 +1,79 @@
+# MVP 0.1 구현 범위
+
+- 문서 상태: Draft 0.1
+- 작성일: 2026-06-09
+- 관련 제품: Haechi
+
+## 1. 결론
+
+MVP 0.1은 넓은 protocol coverage보다 "쉽게 붙이고 바로 확인할 수 있는 로컬 보안 레이어"를 완성하는 데 집중한다.
+
+0.1의 성공 기준은 다음이다.
+
+1. 사용자가 `haechi init`으로 local key, sample policy, audit path를 생성한다.
+2. 사용자가 `haechi protect`로 OpenAI-compatible JSON payload를 보호해 본다.
+3. 사용자가 `haechi proxy`로 기존 LLM HTTP 호출을 local proxy에 붙여 본다.
+4. 사용자가 `haechi report`로 평문 없는 audit summary를 확인한다.
+5. 테스트가 개인정보/secret 탐지, redaction, block, encryption, audit plaintext leak 방지를 검증한다.
+
+## 2. 0.1 포함 범위
+
+| 영역 | 포함 |
+|---|---|
+| Runtime | Node.js ESM, no external runtime dependency |
+| Config | JSON config, preset policy |
+| CLI | `init`, `protect`, `report`, `proxy` |
+| Core | security context, filter -> policy -> transform -> audit pipeline |
+| Filter | email, phone, Korean RRN-like id, card-like number, API key/secret, custom regex |
+| Policy | dry-run, redact, mask, encrypt, block |
+| Crypto | local AES-256-GCM envelope encryption using Node `crypto` |
+| Key | local software key file |
+| Audit | JSON Lines audit event without raw payload |
+| Adapter | OpenAI-compatible request body traversal |
+| Proxy | local HTTP JSON proxy with upstream forwarding |
+| Tests | Node built-in test runner |
+
+## 3. 0.1 제외 범위
+
+| 제외 | 이유 | 다음 단계 |
+|---|---|---|
+| Python SDK | 0.1 quickstart에는 Node CLI만으로 충분 | 0.2 |
+| Vault/AWS KMS | 외부 설정이 필요해 5분 demo를 방해 | 0.2 adapter |
+| MCP stdio wrapper | process/env handling이 별도 보안 검토 필요 | 0.2 |
+| Full MCP protocol proxy | 0.1은 HTTP JSON payload 보호 검증 우선 | 0.2 |
+| A2A/gRPC production adapter | protocol contract 선행 필요 | 0.3 |
+| TokenVault | reveal/purge governance가 별도 설계 필요 | 0.2 |
+| Signed policy bundle | 0.1은 local config validation 우선 | 0.2 |
+| SBOM/signing | release 단계 작업 | 0.2 |
+
+## 4. Quickstart 흐름
+
+```bash
+npm test
+node packages/cli/bin/haechi.mjs init --force
+node packages/cli/bin/haechi.mjs protect examples/llm-prompt-filtering/input.json --config haechi.config.json
+node packages/cli/bin/haechi.mjs report --audit .haechi/audit.jsonl
+node packages/cli/bin/haechi.mjs proxy --config haechi.config.json
+```
+
+## 5. 구현 원칙
+
+- 외부 dependency 없이 시작한다.
+- JSON 설정을 사용한다. YAML은 0.2 이후로 미룬다.
+- 암호 primitive는 직접 만들지 않고 Node `crypto`의 AES-256-GCM을 사용한다.
+- default mode는 `dry-run`이다.
+- enforcement mode에서도 audit에는 원문을 남기지 않는다.
+- 적용 실패 시 원문 유출보다 요청 차단을 우선한다.
+- provider boundary는 코드 구조로 남기되, 0.1에서는 과한 plugin loader를 만들지 않는다.
+
+## 6. 0.1 완료 기준
+
+| 기준 | 완료 조건 |
+|---|---|
+| CLI | `init`, `protect`, `report`, `proxy`가 동작 |
+| 보안 | audit JSONL에 sentinel 원문이 남지 않음 |
+| 개인정보 | email/phone/secret/card-like/RRN-like fixture 탐지 |
+| 정책 | dry-run/redact/mask/encrypt/block fixture 통과 |
+| 암호 | AAD 변조 시 복호화 실패 |
+| 적용성 | example payload를 CLI로 보호하고 audit report 확인 |
+| 검증 | `npm test` 통과 |

package/docs/current/mvp-0.1-implementation-scope.md

@@ -0,0 +1,79 @@
+# MVP 0.1 Implementation Scope
+
+- Status: Draft 0.1
+- Date: 2026-06-09
+- Target version: Haechi
+
+## 1. Summary
+
+MVP 0.1 focuses on delivering a local security layer that is easy to attach and immediately verifiable, rather than broad protocol coverage.
+
+The success criteria for 0.1 are:
+
+1. The user runs `haechi init` to generate a local key, sample policy, and audit path.
+2. The user runs `haechi protect` to protect an OpenAI-compatible JSON payload.
+3. The user runs `haechi proxy` to route an existing LLM HTTP call through a local proxy.
+4. The user runs `haechi report` to view an audit summary containing no plaintext.
+5. Tests verify PII/secret detection, redaction, blocking, encryption, and prevention of plaintext leakage in the audit log.
+
+## 2. 0.1 Included Scope
+
+| Area | Included |
+|---|---|
+| Runtime | Node.js ESM, no external runtime dependency |
+| Config | JSON config, preset policy |
+| CLI | `init`, `protect`, `report`, `proxy` |
+| Core | security context, filter -> policy -> transform -> audit pipeline |
+| Filter | email, phone, Korean RRN-like id, card-like number, API key/secret, custom regex |
+| Policy | dry-run, redact, mask, encrypt, block |
+| Crypto | local AES-256-GCM envelope encryption using Node `crypto` |
+| Key | local software key file |
+| Audit | JSON Lines audit event without raw payload |
+| Adapter | OpenAI-compatible request body traversal |
+| Proxy | local HTTP JSON proxy with upstream forwarding |
+| Tests | Node built-in test runner |
+
+## 3. 0.1 Excluded Scope
+
+| Excluded | Reason | Next Step |
+|---|---|---|
+| Python SDK | Node CLI alone is sufficient for the 0.1 quickstart | 0.2 |
+| Vault/AWS KMS | Requires external setup, which breaks the 5-minute demo | 0.2 adapter |
+| MCP stdio wrapper | process/env handling requires a separate security review | 0.2 |
+| Full MCP protocol proxy | 0.1 prioritizes validating HTTP JSON payload protection | 0.2 |
+| A2A/gRPC production adapter | Requires prior protocol contract definition | 0.3 |
+| TokenVault | reveal/purge governance requires separate design | 0.2 |
+| Signed policy bundle | 0.1 prioritizes local config validation | 0.2 |
+| SBOM/signing | Release-phase work | 0.2 |
+
+## 4. Quickstart Flow
+
+```bash
+npm test
+node packages/cli/bin/haechi.mjs init --force
+node packages/cli/bin/haechi.mjs protect examples/llm-prompt-filtering/input.json --config haechi.config.json
+node packages/cli/bin/haechi.mjs report --audit .haechi/audit.jsonl
+node packages/cli/bin/haechi.mjs proxy --config haechi.config.json
+```
+
+## 5. Implementation Principles
+
+- Start with no external dependencies.
+- Use JSON configuration. Defer YAML support to 0.2 or later.
+- Do not implement crypto primitives directly; use AES-256-GCM from Node `crypto`.
+- Default mode is `dry-run`.
+- Even in enforcement mode, do not write raw input to the audit log.
+- On processing failure, prefer blocking the request over leaking plaintext.
+- Preserve provider boundaries in the code structure, but do not build an elaborate plugin loader in 0.1.
+
+## 6. 0.1 Completion Criteria
+
+| Criterion | Done When |
+|---|---|
+| CLI | `init`, `protect`, `report`, and `proxy` are functional |
+| Security | No sentinel plaintext remains in the audit JSONL |
+| PII | email/phone/secret/card-like/RRN-like fixtures are detected |
+| Policy | dry-run/redact/mask/encrypt/block fixtures pass |
+| Crypto | Decryption fails when AAD is tampered with |
+| Applicability | Example payload can be protected via CLI and verified in the audit report |
+| Verification | `npm test` passes |