haechi 1.2.0 → 1.3.1

package/docs/current/shared-responsibility.md

@@ -1,6 +1,6 @@
 # Haechi Shared Responsibility
 
-- Status: Living document (tracks core 1.2.x)
+- Status: Living document (tracks core 1.3.x)
 - Date: 2026-06-10
 
 ## 1. Responsibility Matrix
@@ -9,7 +9,7 @@
 |---|---|---|
 | 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 |
+| HTTP proxy | Loopback default, remote bind guard, body/response limits, default-drop upstream header allowlist (gateway-client auth separated from upstream-provider auth) | Authentication, TLS termination, firewall, upstream auth; supply the upstream provider key intentionally (client `Authorization` is forwarded only with `auth.provider: none`; otherwise set provider key headers like `x-api-key` or list extras in `target.forwardHeaders`) |
 | 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 |
@@ -41,7 +41,16 @@
 
 Haechi's stateful controls are single-process by design. Running 2+ replicas behind a load balancer **silently weakens** them unless the operator supplies shared infrastructure:
 
-- **Rate limit** is per-process and in-memory — total throughput multiplies by the replica count. Enforce a per-identity limit at a shared front door, or inject a shared-store `rateLimiter` via `createRuntime(config, { rateLimiter })` (the seam satisfies the `allow(key, limit)` contract; see [`configuration.md` → Rate limiter injection](./configuration.md#rate-limiter-injection)). The default per-process limiter also bounds its window map (no unbounded memory growth keyed by identity).
+- **Rate limit** is per-process and in-memory — total throughput multiplies by the replica count. Enforce a per-identity limit at a shared front door, or inject a shared-store `rateLimiter` via `createRuntime(config, { rateLimiter })` (the seam satisfies the `allow(key, limit)` contract, which may return `boolean` or `Promise<boolean>`; see [`configuration.md` → Rate limiter injection](./configuration.md#rate-limiter-injection)). The [`haechi-ratelimit-redis`](https://github.com/raeseoklee/haechi/tree/main/satellites/ratelimit-redis) satellite is the reference shared-store (Redis-backed) implementation — a fixed-window counter over an injected client. The default per-process limiter also bounds its window map (no unbounded memory growth keyed by identity).
 - **Audit hash chain + anchor** are single-writer. Give each replica its **own** `audit.path` (and anchor path); never share one audit file across replicas, or the chain forks into an unverifiable state.
 - **TokenVault and the auth store** are whole-file local stores — correct for one host, but not a shared multi-writer store. For multi-replica tokenization, inject a shared `tokenVault`.
 - File locking relies on `O_EXCL` + atomic rename, which do not hold on NFS / shared filesystems — keep these stores on local disk.
+
+## 5. Gateway auth vs upstream auth (header forwarding)
+
+Haechi keeps **gateway-client authentication** and **upstream-provider authentication** separate. The proxy does NOT forward arbitrary client headers to the model upstream; it applies a default-drop allowlist (P0-CR-001):
+
+- When `auth.provider` is `bearer`/`external`/`plugin`, the client's `Authorization` is the **gateway credential** Haechi consumed and is **never forwarded** upstream. Supply the upstream provider key out-of-band — set the provider key header (`x-api-key`, `x-goog-api-key`, etc., all on the allowlist) on the client request, or front the upstream with your own credential injection.
+- When `auth.provider` is `none`, the client's `Authorization` is treated as the **upstream provider key** and is forwarded (the OpenAI-compatible pass-through pattern).
+- `Cookie`, `Set-Cookie`, `Proxy-Authorization`, and hop-by-hop headers are always dropped; any non-allowlisted header is dropped by default. Use `target.forwardHeaders` (lowercase names) to widen the allowlist for an unusual upstream — it cannot re-enable an always-dropped credential/hop-by-hop header.
+- **Operator responsibility:** confirm your upstream actually receives the credential header it needs (the gateway no longer relays the client `Authorization` under gateway auth), and treat `target.forwardHeaders` as a reviewed allowlist, not a catch-all.

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

@@ -1,6 +1,6 @@
 # Haechi Threat Model
 
-- 문서 상태: Living document(core 1.2.x 추적)
+- 문서 상태: Living document(core 1.3.x 추적)
 - 작성일: 2026-06-10
 
 ## 1. 보호 대상
@@ -33,6 +33,9 @@ Haechi가 보호하려는 주요 자산은 다음과 같습니다.
 | 위협 | 영향 | 현재 통제 |
 |---|---|---|
 | 인터넷 노출 proxy | 인증 없는 LLM gateway | non-loopback bind 기본 실패 |
+| gateway credential의 upstream 전달 | Haechi가 소비한 gateway 토큰인 클라이언트 `Authorization`, `Cookie`, `Proxy-Authorization`가 모델 제공자로 전달되어 gateway 비밀이 신뢰 경계를 넘어 유출됩니다 (P0-CR-001) | **기본 차단 upstream 헤더 허용목록.** proxy는 명시적인 제공자/어댑터 헤더 집합(`x-api-key`, `anthropic-version`, `anthropic-beta`, `x-goog-api-key`, `openai-organization`, `openai-beta`, `accept`, `accept-language`, `user-agent`, `content-type`)만 전달합니다. `Cookie`/`Set-Cookie`/`Proxy-Authorization`와 hop-by-hop 헤더는 항상 폐기됩니다. `Authorization`은 `auth.provider !== none`이면(gateway credential이므로) 폐기되고, `auth.provider: none`일 때만(upstream 제공자 키이므로) 전달됩니다. `target.forwardHeaders`는 허용목록을 추가로 넓히지만 항상 폐기되는 헤더를 다시 켤 수는 없습니다(설정 시점 fail-closed) |
+| 압축 해제된 바디에 잔존하는 압축 헤더 | Node `fetch()`가 gzip/br/deflate를 자동 해제하지만, upstream의 `content-encoding`/`content-length`를 유지한 채 전달하면 downstream 클라이언트가 평문 바이트에 `content-encoding: gzip`을 보고 "incorrect header check"로 실패합니다 (P1-CR-003) | **모든 응답 경로에서 중앙화된 `sanitizeResponseHeaders`**(pass-through, 전달/미보호, 보호, streaming): `content-encoding`, `content-length`, `transfer-encoding`, hop-by-hop 헤더를 제거하고, 완전 버퍼링된 바디에 한해 올바른 `content-length`만 다시 설정합니다 |
+| 무제한 streaming pass-through | `streaming.requestMode: "pass-through"`가 크기 제한 없이 전체 upstream 바디를 버퍼링해, 장수명·악의적 스트림이 메모리/연결 자원을 무한정 점유할 수 있었습니다 (P1-CR-004) | **진정한 경계 streaming pass-through**: upstream 바디를 도착하는 대로 실행 바이트 카운트(`responseProtection.maxBytes`)와 함께 클라이언트로 파이핑하며, 한도를 초과하면 upstream 읽기를 취소하고 클라이언트 쓰기를 종료합니다(크기 기준 fail-closed). 동일한 한도가 미보호/전달 버퍼링 읽기에도 적용됩니다(한도 초과 시 502) |
 | streaming 우회 | SSE/NDJSON 평문 유출 | `inspect` 모드는 SSE/NDJSON을 stream-filter합니다. `block`(기본값)은 거부하고, `pass-through`는 명시적으로 감사된 opt-out입니다 |
 | Ollama 암묵 streaming 우회 | `stream` 생략 시 NDJSON 평문 유출 | `/api/chat`·`/api/generate`는 `stream: false`를 명시하지 않으면 streaming으로 간주해 기본 차단합니다 |
 | 비JSON/압축/대용량 응답 | responseProtection 우회 | fail-closed response policy |
@@ -46,7 +49,8 @@ Haechi가 보호하려는 주요 자산은 다음과 같습니다.
 | 행 걸린 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 대상 |
-| 모든 정규식 규칙을 우회하는 유니코드 난독화 | card/RRN/phone/email/secret을 시각·의미상 동등한 비ASCII 유니코드 형태(전각 숫자 `４２４２…`, 전각 `＠`, 수학·원문자 영숫자)로 보내 모든 탐지 규칙을 무력화 | **매칭 전 각 string leaf의 NFKC 정규화**(WS2d)입니다. 정규화가 무변환인 경우(leaf의 약 99%) 탐지는 이전과 바이트 단위로 동일합니다. 접힘이 **위치 안정적**인 경우(모든 코드포인트가 같은 UTF-16 길이로 접히고 코드포인트별 접힘이 전체 정규화를 그대로 재구성) 정규화 사본에서 탐지하고 원본의 정확한 구간을 redact/block하며, 기록되는 값은 접힌 형태가 아니라 원본 바이트입니다. 그 외 — 길이가 달라지거나(수학 숫자·합자) 총 길이는 같지만 내부 offset을 이동시키는 수축+확장 보상 — 의 경우 offset을 원본에 매핑할 수 없으므로 탐지가 **fail closed**되어 leaf 전체를 덮는 단일 탐지로 처리합니다(leaf 전체 redact/block — 우회 시도를 과도 redact하는 것이 안전한 실패입니다). `String.prototype.normalize` 빌트인을 사용하므로 새 의존성은 없습니다. **수용된 잔여:** base64/percent-encoded 페이로드는 여전히 디코딩 후 재검사하지 않습니다(§4 참조) |
+| 모든 정규식 규칙을 우회하는 유니코드 난독화 | card/RRN/phone/email/secret을 시각·의미상 동등한 비ASCII 유니코드 형태(전각 숫자 `４２４２…`, 전각 `＠`, 수학·원문자 영숫자)로 보내 모든 탐지 규칙을 무력화 | **매칭 전 각 string leaf의 NFKC 정규화**(WS2d)입니다. 정규화가 무변환인 경우(leaf의 약 99%) 탐지는 이전과 바이트 단위로 동일합니다. 접힘이 **위치 안정적**인 경우(모든 코드포인트가 같은 UTF-16 길이로 접히고 코드포인트별 접힘이 전체 정규화를 그대로 재구성) 정규화 사본에서 탐지하고 원본의 정확한 구간을 redact/block하며, 기록되는 값은 접힌 형태가 아니라 원본 바이트입니다. 그 외 — 길이가 달라지거나(수학 숫자·합자) 총 길이는 같지만 내부 offset을 이동시키는 수축+확장 보상 — 의 경우 offset을 원본에 매핑할 수 없으므로 탐지가 **fail closed**되어 leaf 전체를 덮는 단일 탐지로 처리합니다(leaf 전체 redact/block — 우회 시도를 과도 redact하는 것이 안전한 실패입니다). `String.prototype.normalize` 빌트인을 사용하므로 새 의존성은 없습니다. **잔여는 이제 opt-in 통제입니다:** base64/percent-encoded 페이로드는 `filters.decodeAndRescan`이 활성화된 경우에만 디코딩 후 재검사합니다(다음 행 및 §4 참조) |
+| 모든 정규식 규칙을 우회하는 base64/percent-encoded 페이로드 | 전송 전 base64·percent로 인코딩된 card/RRN/secret은 모든 규칙을 통과합니다(Haechi는 NFKC 텍스트에서 매칭하지만 디코딩하지 않습니다) | **opt-in `filters.decodeAndRescan`**입니다(기본 OFF → 이전과 바이트 단위로 동일). ON일 때, 일반 NFKC 스캔 이후 base64/base64url로 **보이는** string leaf(고정 알파벳, 유효한 길이, `16…8192` 바이트 범위, 같은 leaf로 round-trip, `node:buffer` `isUtf8`로 **유효한 UTF-8** 디코딩)이거나 `%XX` 이스케이프를 포함하는 leaf(try/catch 안의 `decodeURIComponent`)를 디코딩하여 같은 규칙·validator로 재검사합니다. **offset 처리는 fail closed입니다:** 디코딩된 매칭은 인코딩된 leaf에 유효한 offset이 없으므로, 원본 인코딩 leaf 전체를 덮는 **WHOLE-LEAF** 탐지(`start:0, end:leaf.length`)를 발생시킵니다 — transform이 leaf 전체를 redact/block하며, 디코딩된 offset을 원본으로 되돌려 매핑하지 않습니다. **정밀도 가드:** 디코딩된 매칭은 **validator 기반이거나 하드 블록 타입**일 때만 발생합니다(Luhn 통과 `card`, 체크섬 `kr_rrn`/`us_ssn`, IBAN mod-97, 또는 앵커된 규칙의 `secret`/`api_key`). validator 없는 디코딩된 소프트 타입 매칭(맨 전화번호 형태 등)은 발생하지 **않으므로** 무작위 base64는 오탐하지 않습니다. 새 의존성은 없습니다(`node:buffer` Buffer + `decodeURIComponent` 빌트인). **수용된 잔여:** Haechi가 디코딩하지 않는 인코딩(gzip, hex, 중첩/이중 인코딩, 커스텀 알파벳), 그리고 양성 텍스트 안에 Luhn-유효 16자리 런으로 디코딩되도록 의도적으로 조작된 평문(이에 발생하는 것은 오탐이 아니라 올바른 동작) |
 | 인증 없는 멀티 클라이언트 접근 | 로컬 프로세스가 upstream / token round-trip 경로를 무단 사용 | 선택적 bearer auth (`auth.provider: bearer`); 없거나 잘못된 경우 → 바디 읽기 전 401; identity별 rate limit 및 model allowlist |
 | Audit tail truncation | 꼬리 audit 레코드의 무음 삭제 | 추가 전용/별도 미디어의 `audit.anchor` head-hash anchoring으로 마지막 anchor까지의 절단 탐지 (0.7) |
 | Local dev key in production | 소프트웨어 키의 운영 custody 오용 | `assertCryptoProviderConformance`를 통한 외부 `cryptoProvider` 주입; reference KMS adapter (envelope 암호화) |
@@ -87,7 +91,7 @@ Haechi는 다음을 보장하지 않습니다.
 - 법적 컴플라이언스 인증
 - 모델 hallucination, prompt injection 완전 방어
 - 외부 MCP server의 OAuth/resource binding 검증
-- base64/percent-encoded 값의 **디코딩 후** 검사 — Haechi는 NFKC 정규화 텍스트에서 매칭하지만(§3의 유니코드 난독화 행 참조) base64/URL 디코딩 후 재검사는 하지 **않습니다**. 전송 전 base64·percent로 인코딩된 값은 검사되지 않습니다. (WS2d는 디코딩-후-재검사 패스를 보류했습니다. 상시 디코딩은 오탐이 많고, recall-safe한 opt-in을 범위 내에서 precision-neutral하게 만들 수 없어 문서화된 제외로 남깁니다.)
+- base64/percent-encoded 값의 **기본** 디코딩 후 검사 — Haechi는 NFKC 정규화 텍스트에서 매칭하며(§3의 유니코드 난독화 행 참조) opt-in `filters.decodeAndRescan`(기본 OFF)을 활성화하지 않는 한 base64/URL 디코딩 후 재검사는 하지 **않습니다**. OFF이면 전송 전 base64·percent로 인코딩된 값은 검사되지 않습니다. ON이면 §3에 설명된 정밀도 가드(validator 기반 / 하드 블록 매칭만, WHOLE-LEAF fail-closed)와 함께 디코딩-후-재검사 패스가 동작합니다. WS2d는 *상시* 디코딩을 보류했고(오탐이 많고 범위 내에서 precision-neutral하지 않음), opt-in 통제는 트레이드오프를 수용하는 운영자를 위해 그 잔여를 닫습니다. 다른 인코딩(gzip/hex/중첩/커스텀 알파벳)은 여전히 범위 밖입니다.
 - URL query string 내 민감값 검사 (JSON body만 검사)
 - 마지막 anchor 이후의 audit tail truncation — `audit.anchor`(0.7)는 anchor가 추가 전용/별도 미디어에 있을 때 마지막 anchor까지의 레코드 삭제를 탐지합니다. 마지막 anchor 이후 기록된 레코드와 동일 파일시스템 anchor는 대상에서 제외됩니다
 - JSON-RPC batch 메시지 처리 (MCP stdio filter는 batch를 fail-closed로 거부)

package/docs/current/threat-model.md

@@ -1,6 +1,6 @@
 # Haechi Threat Model
 
-- Status: Living document (tracks core 1.2.x)
+- Status: Living document (tracks core 1.3.x)
 - Date: 2026-06-10
 
 ## 1. Assets Under Protection
@@ -33,6 +33,9 @@ The primary assets Haechi protects are:
 | Threat | Impact | Current Control |
 |---|---|---|
 | Internet-exposed proxy | Unauthenticated LLM gateway | Non-loopback bind fails by default |
+| Gateway credential forwarded upstream | The client `Authorization` (the gateway token Haechi consumed), `Cookie`, or `Proxy-Authorization` is forwarded to the model provider, leaking a gateway secret across the trust boundary (P0-CR-001) | **Default-drop upstream header allowlist.** The proxy forwards only an explicit provider/adapter header set (`x-api-key`, `anthropic-version`, `anthropic-beta`, `x-goog-api-key`, `openai-organization`, `openai-beta`, `accept`, `accept-language`, `user-agent`, `content-type`). `Cookie`/`Set-Cookie`/`Proxy-Authorization` and hop-by-hop headers are always dropped. `Authorization` is dropped when `auth.provider !== none` (it is the gateway credential), and forwarded only when `auth.provider: none` (it is the upstream provider key). `target.forwardHeaders` widens the allowlist additively but cannot re-enable an always-dropped header (fail-closed at config time) |
+| Decompressed body with stale compression headers | Node `fetch()` auto-decompresses gzip/br/deflate, but a forwarded response that keeps the upstream `content-encoding`/`content-length` makes a downstream client see e.g. `content-encoding: gzip` on plain bytes and fail with "incorrect header check" (P1-CR-003) | **Centralized `sanitizeResponseHeaders` on every response path** (pass-through, forwarded/unprotected, protected, streaming): strips `content-encoding`, `content-length`, `transfer-encoding`, and hop-by-hop headers; a correct `content-length` is re-set only for a fully-buffered body |
+| Unbounded streaming pass-through | `streaming.requestMode: "pass-through"` buffered the full upstream body with no size cap, so a long-lived or malicious stream could hold memory/connection resources indefinitely (P1-CR-004) | **True bounded streaming pass-through**: the upstream body is piped to the client as it arrives with a running byte cap (`responseProtection.maxBytes`); exceeding the cap cancels the upstream read and tears down the client write (fail-closed on size). The same cap applies to the unprotected/forwarded buffered-body read (502 over the cap) |
 | Streaming bypass | SSE/NDJSON plaintext leak | `inspect` mode stream-filters SSE/NDJSON; `block` (default) refuses; `pass-through` is an explicit audited opt-out |
 | 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 |
@@ -46,7 +49,8 @@ The primary assets Haechi protects are:
 | 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 |
-| Unicode-obfuscation evasion of every regex rule | A card/RRN/phone/email/secret sent in a visually/semantically equivalent non-ASCII Unicode form (full-width digits `４２４２…`, full-width `＠`, mathematical/enclosed alphanumerics) defeats every detection rule | **NFKC normalization of each string leaf before matching** (WS2d). When the normalization is a no-op (~99% of leaves) detection is byte-identical to before. When the fold is **position-stable** (every codepoint folds to the same UTF-16 length and the per-codepoint folds reconstruct the whole normalization), detection runs on the normalized copy and the exact original span is redacted/blocked (the recorded value is the original bytes, never the fold). Otherwise — a length change (mathematical digits/ligatures) **or** a compensating contraction+expansion that keeps the total length equal while shifting interior offsets — offsets cannot map back, so detection **fails closed** to a single whole-leaf detection (the entire leaf is redacted/blocked — over-redacting an evasion attempt is the safe failure). Uses the `String.prototype.normalize` builtin (no new dependency). **Accepted residual:** base64/percent-encoded payloads are still not decoded-and-rescanned (see §4) |
+| Unicode-obfuscation evasion of every regex rule | A card/RRN/phone/email/secret sent in a visually/semantically equivalent non-ASCII Unicode form (full-width digits `４２４２…`, full-width `＠`, mathematical/enclosed alphanumerics) defeats every detection rule | **NFKC normalization of each string leaf before matching** (WS2d). When the normalization is a no-op (~99% of leaves) detection is byte-identical to before. When the fold is **position-stable** (every codepoint folds to the same UTF-16 length and the per-codepoint folds reconstruct the whole normalization), detection runs on the normalized copy and the exact original span is redacted/blocked (the recorded value is the original bytes, never the fold). Otherwise — a length change (mathematical digits/ligatures) **or** a compensating contraction+expansion that keeps the total length equal while shifting interior offsets — offsets cannot map back, so detection **fails closed** to a single whole-leaf detection (the entire leaf is redacted/blocked — over-redacting an evasion attempt is the safe failure). Uses the `String.prototype.normalize` builtin (no new dependency). **Residual now an opt-in control:** base64/percent-encoded payloads are decoded-and-rescanned only when `filters.decodeAndRescan` is enabled (see the next row and §4) |
+| Base64/percent-encoded payload evades every regex rule | A card/RRN/secret base64- or percent-encoded before sending passes every rule (Haechi matches the NFKC text but does not decode) | **Opt-in `filters.decodeAndRescan`** (default OFF → byte-identical to before). When ON, after the normal NFKC scan a string leaf that LOOKS base64/base64url (anchored alphabet, valid length, within `16…8192` bytes, round-trips to the same leaf, decodes to **valid UTF-8** via `node:buffer` `isUtf8`) or contains a `%XX` escape (`decodeURIComponent` in try/catch) is decoded and rescanned with the same rules + validators. **Offset handling fails closed:** a decoded hit has no offset in the encoded leaf, so it emits a **WHOLE-LEAF** detection of the original encoded leaf (`start:0, end:leaf.length`) — the transform redacts/blocks the entire leaf; a decoded offset is never mapped back. **Precision guard:** a decoded hit only fires when it is **validator-backed or a hard-block type** (a Luhn-passing `card`, a checksum `kr_rrn`/`us_ssn`, an IBAN mod-97, or a `secret`/`api_key` on its anchored rule). A decoded soft-type-without-validator match (a bare phone-shaped run) does **not** fire, so random base64 does not false-positive. Zero new dependency (`node:buffer` Buffer + the `decodeURIComponent` builtin). **Accepted residual:** an encoding Haechi does not decode (gzip, hex, nested/double-encoding, a custom alphabet), and a deliberately contrived plaintext that decodes to a Luhn-valid 16-digit run inside benign text (firing on it is correct, not a false positive) |
 | Unauthenticated multi-client access | Any local process uses the upstream / token round-trip | Optional bearer auth (`auth.provider: bearer`); missing/invalid → 401 before body read; per-identity rate limit and model allowlist |
 | Audit tail truncation | Silent deletion of trailing audit records | `audit.anchor` head-hash anchoring on append-only/separate media detects truncation back to the last anchor (0.7) |
 | Local dev key in production | Software key misused as production custody | External `cryptoProvider` injection with `assertCryptoProviderConformance`; reference KMS adapter (envelope encryption) |
@@ -87,7 +91,7 @@ Haechi does not guarantee:
 - Legal compliance certification
 - Complete defense against model hallucination or prompt injection
 - OAuth/resource binding validation for external MCP servers
-- Inspection of base64/percent-encoded values **after decoding** — Haechi matches on the NFKC-normalized text (see the Unicode-evasion row in §3) but does **not** base64/URL-decode-and-rescan. A value that is base64- or percent-encoded before sending is not inspected. (WS2d deferred a decode-and-rescan pass: an always-on decode is false-positive-prone, and a recall-safe opt-in could not be made precision-neutral within scope; it remains a documented exclusion.)
+- Inspection of base64/percent-encoded values **after decoding** **by default** — Haechi matches on the NFKC-normalized text (see the Unicode-evasion row in §3) and does **not** base64/URL-decode-and-rescan unless the opt-in `filters.decodeAndRescan` is enabled (default OFF). With it OFF, a value that is base64- or percent-encoded before sending is not inspected. With it ON, the decode-and-rescan pass runs with the precision guard described in §3 (validator-backed / hard-block hits only, whole-leaf fail-closed). WS2d deferred an *always-on* decode (false-positive-prone, not precision-neutral within scope); the opt-in control closes that residual for operators who accept the trade-off, and other encodings (gzip/hex/nested/custom-alphabet) remain out of scope.
 - Detection of sensitive values in URL query strings (JSON body only)
 - Audit tail truncation beyond the last anchor — `audit.anchor` (0.7) detects deletion of records back to the last anchor when the anchor is on append-only/separate media; records written after the last anchor, and same-filesystem anchors, are not covered
 - JSON-RPC batch message processing (the MCP stdio filter rejects batches fail-closed)

package/examples/local-proxy-demo/README.md

@@ -0,0 +1,51 @@
+# Local end-to-end demo
+
+A self-contained, **reproducible** walkthrough of Haechi — no remote model required.
+It stands up a tiny OpenAI-compatible *stub* upstream and the **real** Haechi proxy
+in front of it (in `enforce` mode), then narrates what happens to a payload carrying
+an email, a phone number, an API key, and a card number.
+
+```bash
+node examples/local-proxy-demo/demo.mjs
+# or, from the repo root:
+npm run demo
+```
+
+What it shows, in order:
+
+1. **The model only sees protected values** — the proxy detects and transforms the
+   payload *before* forwarding, so the stub (standing in for the model) receives
+   `[TOKEN:…]` for the email, a masked phone, and `[REDACTED:api_key]` for the key.
+2. **The token round-trip** — because the email was *tokenized* (reversible), the
+   caller gets `minji.kim@example.com` back, while the masked phone and redacted
+   secret stay protected. The model's own leaked secret in its reply is
+   response-protected too.
+3. **The audit log** carries detection metadata and is hash-chained — and never any
+   plaintext email/phone/key.
+4. **Day-2 operability** — the live `/__haechi/ready` readiness probe and the
+   Prometheus `/__haechi/metrics` surface.
+5. **A card number is blocked outright** (`403`, fail-closed) — it never reaches the
+   model.
+
+Zero dependencies (only `node:` builtins + the in-repo `haechi` packages). The demo
+is programmatic for reproducibility; for the real CLI invocation see the
+[Quickstart](../../README.md#quickstart) and
+[`docs/current/configuration.md`](../../docs/current/configuration.md).
+
+## Live demo against a real model
+
+`live-demo.mjs` runs the same flow against a **real** upstream (vLLM / Ollama / any
+OpenAI-compatible server) instead of the stub. It asks the model to repeat the phone
+number it was given — and the model can only return the *masked* form, because the
+real number never reached it. This is the run recorded in the README GIF
+(`demo.tape` records the stub demo; `live-demo.tape` records this one).
+
+```bash
+HAECHI_LIVE_UPSTREAM=http://127.0.0.1:8000 \
+HAECHI_LIVE_MODEL="Qwen/Qwen3.6-35B-A3B-FP8" \
+node examples/local-proxy-demo/live-demo.mjs
+```
+
+`HAECHI_LIVE_TYPE` (default `vllm-openai`) and `HAECHI_LIVE_MODEL` override the target.
+For Qwen3-style reasoning servers the request sets `chat_template_kwargs.enable_thinking
+= false` so the reply is a terse line; non-reasoning servers ignore it.

package/examples/local-proxy-demo/demo.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Self-contained, reproducible Haechi demo — no remote model required.
+//
+// It stands up a tiny OpenAI-compatible *stub* upstream and the REAL Haechi proxy
+// in front of it, then walks through what Haechi does to a payload that carries an
+// email, a phone number, an API key, and a card:
+//   1. the model only ever sees redacted/tokenized values (proven by echoing the
+//      exact body the stub received),
+//   2. the caller gets the original email back (the token round-trip),
+//   3. the audit log carries no plaintext,
+//   4. the live /__haechi/metrics + /__haechi/ready operability surface,
+//   5. a card is blocked outright (fail-closed).
+//
+// Run:  node examples/local-proxy-demo/demo.mjs   (or: npm run demo)
+// Zero dependencies — only node: builtins and the in-repo haechi packages.
+
+import { createServer } from "node:http";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createRuntime } from "../../packages/cli/runtime.mjs";
+import { createHaechiProxy } from "../../packages/proxy/index.mjs";
+import { initLocalKeyFile } from "../../packages/crypto/index.mjs";
+
+const B = "\x1b[1m", D = "\x1b[2m", G = "\x1b[32m", Y = "\x1b[33m", C = "\x1b[36m", R = "\x1b[31m", X = "\x1b[0m";
+const rule = () => console.log(D + "─".repeat(64) + X);
+const scene = (n, t) => { console.log(); rule(); console.log(`${B}${C}  ${n}. ${t}${X}`); rule(); };
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// A minimal OpenAI-compatible stub. It records the EXACT body it receives (which is
+// whatever the proxy forwarded, i.e. the protected payload) and replies with a
+// canned assistant message that itself leaks a secret, to exercise response protection.
+function startStubUpstream() {
+  let lastReceived = null;
+  const server = createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      lastReceived = body;
+      // Echo the (already-protected) user content back so the response exercises the
+      // token round-trip, and append a leaked secret so response protection fires.
+      let echoed = "";
+      try { echoed = JSON.parse(body).messages.at(-1).content; } catch { /* ignore */ }
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({
+        id: "chatcmpl-demo",
+        object: "chat.completion",
+        choices: [{ index: 0, message: { role: "assistant",
+          content: `Noted — I will follow up. You wrote: "${echoed}" (our ref: token=DEMOleak9876543210notRealzyxwvu)` } }]
+      }));
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => resolve({ server, url: `http://127.0.0.1:${server.address().port}`, received: () => lastReceived }));
+  });
+}
+
+async function main() {
+  console.log(`\n${B}🛡  Haechi — local end-to-end demo${X}  ${D}(stub upstream, real proxy, enforce mode)${X}`);
+
+  const dir = await mkdtemp(join(tmpdir(), "haechi-demo-"));
+  const keyFile = join(dir, ".haechi", "dev.keys.json");
+  const auditPath = join(dir, ".haechi", "audit.jsonl");
+  await initLocalKeyFile(keyFile, { force: true });
+  const stub = await startStubUpstream();
+
+  const runtime = createRuntime({
+    mode: "enforce",
+    target: { type: "openai-compatible", upstream: stub.url },
+    policy: {
+      mode: "enforce",
+      presets: ["llm-redact"],
+      actions: { email: "tokenize", phone: "mask", secret: "redact", api_key: "redact", card: "block" }
+    },
+    tokenVault: { detokenizeResponses: true },
+    responseProtection: { enabled: true, mode: "enforce", failureMode: "fail-closed" },
+    keys: { keyFile },
+    audit: { path: auditPath }
+  });
+  const proxy = createHaechiProxy({ runtime, port: 0 });
+  const addr = await proxy.listen();
+  const base = `http://127.0.0.1:${addr.port}`;
+
+  // ── Scene 1 ───────────────────────────────────────────────────────────────
+  scene(1, "A prompt with an email, a phone number, and a deploy secret");
+  const userText = "Contact minji.kim@example.com or 010-1234-5678. Deploy api_key=DEMOkey0123456789notARealSecretabcdef.";
+  console.log(`${Y}you send →${X} ${userText}`);
+  await pause(700);
+  const r1 = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: "demo", messages: [{ role: "user", content: userText }] })
+  });
+  const out1 = await r1.json();
+
+  scene(2, "What the MODEL actually received (the proxy protected it first)");
+  const forwarded = JSON.parse(stub.received());
+  console.log(`${G}model sees →${X} ${forwarded.messages[0].content}`);
+  console.log(`${D}  (email → [TOKEN:…], phone → masked, secret → [REDACTED])${X}`);
+  await pause(700);
+
+  scene(3, "What YOU get back — the email token is restored (round-trip)");
+  console.log(`${G}you receive →${X} ${out1.choices[0].message.content}`);
+  console.log(`${D}  (email restored from its token; phone stays masked; keys stay redacted both ways)${X}`);
+  await pause(700);
+
+  // ── Scene 4 ───────────────────────────────────────────────────────────────
+  scene(4, "The audit log — tamper-evident, and never any plaintext");
+  const audit = (await readFile(auditPath, "utf8")).trim().split("\n");
+  const ev = JSON.parse(audit[0]);
+  console.log(`${D}detections:${X} ${ev.detections.map((d) => `${d.type}→${d.action}`).join("  ")}`);
+  console.log(`${D}leaks the email/secret/phone?${X} ${audit.join("").match(/minji\.kim@|DEMOkey0123|010-1234-5678/) ? R + "YES" + X : G + "no — clean" + X}`);
+  await pause(700);
+
+  // ── Scene 5 ───────────────────────────────────────────────────────────────
+  scene(5, "Day-2 operability — live health + Prometheus metrics");
+  const ready = await (await fetch(`${base}/__haechi/ready`)).json();
+  console.log(`${D}/__haechi/ready →${X} ${ready.ready ? G + "ready" : R + "not ready"}${X} ${D}(audit writable: ${ready.checks?.auditWritable})${X}`);
+  const metrics = await (await fetch(`${base}/__haechi/metrics`)).text();
+  for (const line of metrics.split("\n").filter((l) => /^haechi_requests_total\{|^haechi_blocks_total /.test(l)).slice(0, 4)) {
+    console.log(`${D}metric:${X} ${line}`);
+  }
+  await pause(700);
+
+  // ── Scene 6 ───────────────────────────────────────────────────────────────
+  scene(6, "A card number is blocked outright (fail-closed)");
+  const r2 = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: "demo", messages: [{ role: "user", content: "charge card 4242 4242 4242 4242 now" }] })
+  });
+  console.log(`${Y}you send →${X} "charge card 4242 4242 4242 4242 now"`);
+  console.log(`${G}proxy →${X} HTTP ${r2.status} ${r2.status === 403 ? R + B + "BLOCKED" + X : ""} ${D}(the card never reaches the model)${X}`);
+
+  console.log();
+  rule();
+  console.log(`${B}${G}  ✓ done${X}  ${D}— detection → redact/tokenize/block → forward → audit, all local.${X}`);
+  rule();
+  console.log(`${D}  config reference: haechi.config.example.json   ·   docs/current/configuration.md${X}\n`);
+
+  await proxy.close();
+  stub.server.close();
+}
+
+main().then(() => process.exit(0)).catch((e) => { console.error("demo failed:", e); process.exit(1); });

package/examples/local-proxy-demo/demo.tape

@@ -0,0 +1,19 @@
+# VHS tape for the Haechi local end-to-end demo.
+# Regenerate the README GIF with:  vhs examples/local-proxy-demo/demo.tape
+# (run from the repo root; requires vhs + ttyd + ffmpeg)
+
+Output docs/assets/haechi-demo.gif
+
+Set Shell "bash"
+Set FontSize 15
+Set Width 1180
+Set Height 840
+Set Padding 18
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 55ms
+
+Sleep 500ms
+Type "node examples/local-proxy-demo/demo.mjs"
+Sleep 600ms
+Enter
+Sleep 9s

package/examples/local-proxy-demo/live-demo.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Live end-to-end demo against a REAL upstream model (vLLM / Ollama / any
+// OpenAI-compatible server). Unlike demo.mjs (which uses a deterministic stub),
+// this proves protection against an actual model: it asks the model to repeat the
+// phone number it was given, and the model can only return the *masked* form —
+// the real number never reached it.
+//
+//   HAECHI_LIVE_UPSTREAM=http://127.0.0.1:8000 \
+//   HAECHI_LIVE_MODEL="Qwen/Qwen3.6-35B-A3B-FP8" \
+//   node examples/local-proxy-demo/live-demo.mjs
+//
+// Defaults: type=vllm-openai. HAECHI_LIVE_TYPE and HAECHI_LIVE_MODEL override.
+// Zero dependencies — only node: builtins + the in-repo haechi packages.
+
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createRuntime } from "../../packages/cli/runtime.mjs";
+import { createHaechiProxy } from "../../packages/proxy/index.mjs";
+import { initLocalKeyFile } from "../../packages/crypto/index.mjs";
+
+const B = "\x1b[1m", D = "\x1b[2m", G = "\x1b[32m", Y = "\x1b[33m", C = "\x1b[36m", R = "\x1b[31m", X = "\x1b[0m";
+const rule = () => console.log(D + "─".repeat(64) + X);
+const scene = (n, t) => { console.log(); rule(); console.log(`${B}${C}  ${n}. ${t}${X}`); rule(); };
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const UPSTREAM = process.env.HAECHI_LIVE_UPSTREAM;
+const TYPE = process.env.HAECHI_LIVE_TYPE || "vllm-openai";
+const MODEL = process.env.HAECHI_LIVE_MODEL || "Qwen/Qwen3.6-35B-A3B-FP8";
+if (!UPSTREAM) {
+  console.error("Set HAECHI_LIVE_UPSTREAM (e.g. http://127.0.0.1:8000) to a reachable OpenAI-compatible server.");
+  console.error("For a no-backend reproducible run, use:  npm run demo");
+  process.exit(2);
+}
+
+async function chat(base, content, extra = {}) {
+  const t0 = Date.now();
+  const res = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST", headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: MODEL, max_tokens: 128, temperature: 0,
+      // Qwen3 reasoning models: ask for a direct answer (no chain-of-thought) so
+      // the demo gets a terse content reply. Ignored by non-reasoning servers.
+      chat_template_kwargs: { enable_thinking: false },
+      messages: [{ role: "user", content }], ...extra })
+  });
+  const body = await res.json();
+  return { status: res.status, ms: Date.now() - t0, text: body.choices?.[0]?.message?.content ?? body.error?.message ?? "(no content)" };
+}
+
+async function main() {
+  console.log(`\n${B}🛡  Haechi — LIVE end-to-end demo${X}  ${D}(real model: ${MODEL} via ${TYPE}, enforce mode)${X}`);
+
+  const dir = await mkdtemp(join(tmpdir(), "haechi-live-"));
+  const keyFile = join(dir, ".haechi", "dev.keys.json");
+  const auditPath = join(dir, ".haechi", "audit.jsonl");
+  await initLocalKeyFile(keyFile, { force: true });
+
+  const runtime = createRuntime({
+    mode: "enforce",
+    target: { type: TYPE, upstream: UPSTREAM },
+    policy: { mode: "enforce", presets: ["llm-redact"], actions: { email: "tokenize", phone: "mask", secret: "redact", api_key: "redact", card: "block" } },
+    tokenVault: { detokenizeResponses: true },
+    responseProtection: { enabled: true, mode: "enforce", failureMode: "fail-closed" },
+    keys: { keyFile }, audit: { path: auditPath }
+  });
+  const proxy = createHaechiProxy({ runtime, port: 0 });
+  const addr = await proxy.listen();
+  const base = `http://127.0.0.1:${addr.port}`;
+
+  // ── Scene 1 ────────────────────────────────────────────────────────────────
+  scene(1, "Ask a REAL model to repeat the phone number you give it");
+  const prompt = "Reply in one short line: repeat the phone number you were given. Phone: 010-1234-5678, email minji.kim@example.com";
+  console.log(`${Y}you send →${X} ${prompt}`);
+  await pause(700);
+  const r1 = await chat(base, prompt);
+
+  scene(2, "Haechi detected + protected the prompt BEFORE it left your machine");
+  const events = (await readFile(auditPath, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
+  const ev = events.find((e) => Array.isArray(e.detections) && e.detections.length) ?? events[0];
+  console.log(`${D}detections:${X} ${(ev.detections ?? []).map((d) => `${G}${d.type}→${d.action}${X}`).join("  ")}`);
+  console.log(`${D}the model only ever saw:${X} email → ${C}[TOKEN:…]${X},  phone → ${C}01*********78${X}`);
+  await pause(700);
+
+  scene(3, "The real model replies — it can only return the MASKED phone");
+  console.log(`${G}${MODEL.split("/").pop()} →${X} ${B}${r1.text}${X}   ${D}(${r1.ms} ms)${X}`);
+  console.log(`${D}  your real number 010-1234-5678 never reached the model — it cannot reveal it.${X}`);
+  await pause(700);
+
+  // ── Scene 4 ────────────────────────────────────────────────────────────────
+  scene(4, "The audit log — hash-chained, and never any plaintext");
+  const auditRaw = await readFile(auditPath, "utf8");
+  console.log(`${D}leaks the real email/phone?${X} ${/minji\.kim@example|010-1234-5678/.test(auditRaw) ? R + "YES" + X : G + "no — clean" + X}`);
+  await pause(700);
+
+  // ── Scene 5 ────────────────────────────────────────────────────────────────
+  scene(5, "Day-2 operability — live readiness + Prometheus metrics");
+  const ready = await (await fetch(`${base}/__haechi/ready`)).json();
+  console.log(`${D}/__haechi/ready →${X} ${ready.ready ? G + "ready" : R + "not ready"}${X}`);
+  const metrics = await (await fetch(`${base}/__haechi/metrics`)).text();
+  for (const line of metrics.split("\n").filter((l) => /^haechi_requests_total\{/.test(l)).slice(0, 3)) {
+    console.log(`${D}metric:${X} ${line}`);
+  }
+  await pause(700);
+
+  // ── Scene 6 ────────────────────────────────────────────────────────────────
+  scene(6, "A card number is blocked before it ever reaches the model");
+  const r2 = await chat(base, "charge card 4242 4242 4242 4242 now");
+  console.log(`${Y}you send →${X} "charge card 4242 4242 4242 4242 now"`);
+  console.log(`${G}proxy →${X} HTTP ${r2.status} ${r2.status === 403 ? R + B + "BLOCKED" + X : ""} ${D}(no upstream call made)${X}`);
+
+  console.log();
+  rule();
+  console.log(`${B}${G}  ✓ live${X}  ${D}— a real model, and your PII never left the gateway in the clear.${X}`);
+  rule();
+  console.log();
+
+  await proxy.close();
+}
+
+main().then(() => process.exit(0)).catch((e) => { console.error("live demo failed:", e); process.exit(1); });

package/examples/local-proxy-demo/live-demo.tape

@@ -0,0 +1,25 @@
+# VHS tape for the Haechi LIVE demo (real upstream model).
+# Regenerate the README GIF with:
+#   HAECHI_LIVE_UPSTREAM is set below via Env so it stays out of the recording.
+#   vhs examples/local-proxy-demo/live-demo.tape    (run from the repo root)
+
+Output docs/assets/haechi-demo.gif
+
+Set Shell "bash"
+Set FontSize 15
+Set Width 1180
+Set Height 840
+Set Padding 18
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 55ms
+
+# Point these at a reachable OpenAI-compatible server before recording. Using Env
+# (not the typed command) keeps the upstream URL out of the captured GIF.
+Env HAECHI_LIVE_UPSTREAM "http://127.0.0.1:8000"
+Env HAECHI_LIVE_MODEL "Qwen/Qwen3.6-35B-A3B-FP8"
+
+Sleep 500ms
+Type "node examples/local-proxy-demo/live-demo.mjs"
+Sleep 600ms
+Enter
+Sleep 9s

package/haechi.config.example.json

@@ -50,7 +50,8 @@
   "filters": {
     "customRules": [],
     "minConfidence": 0,
-    "allowlist": []
+    "allowlist": [],
+    "decodeAndRescan": false
   },
   "keys": {
     "provider": "local",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Self-hosted AI context enforcement across LLM, MCP, vLLM, Ollama, and agent traffic — a stable, zero-dependency security gateway.",
   "license": "Apache-2.0",
   "type": "module",
@@ -76,11 +76,13 @@
     "checksums": "node scripts/release-checksums.mjs",
     "bench:payload": "node scripts/bench-payload.mjs",
     "bench:detection": "node scripts/bench-detection.mjs",
+    "bench:throughput": "node scripts/bench-throughput.mjs",
     "scan:detection": "node scripts/bench-detection.mjs --gate",
     "check:peer-ranges": "node scripts/check-satellite-peer-ranges.mjs",
     "release:preflight": "node scripts/release-preflight.mjs && node scripts/check-satellite-peer-ranges.mjs",
     "release:preflight:npm": "node scripts/release-preflight.mjs --require-npm-auth && node scripts/check-satellite-peer-ranges.mjs",
     "haechi": "node packages/cli/bin/haechi.mjs",
+    "demo": "node examples/local-proxy-demo/demo.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"