haechi 0.9.0 → 1.0.0

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

@@ -2,7 +2,7 @@
 
 - 문서 상태: Draft 0.1
 - 작성일: 2026-06-10
-- 기준 버전: 0.9.0
+- 기준 버전: 1.0.0
 
 ## 1. 보호 대상
 
@@ -65,6 +65,14 @@ Haechi가 보호하려는 주요 자산은 다음이다.
 | 토큰 엔드포인트 POST(및 Vault `fetch`)를 통한 broker SSRF — cloud metadata (0.9) | discovery와 request 사이에 `169.254.169.254`로 DNS-rebind되는 `token_endpoint`(또는 운영자 제공 `VAULT_ADDR`)가 instance-metadata 자격증명을 유출 | 모든 egress(discovery GET, 공유 verifier 경유 JWKS GET, token-exchange POST, end-session redirect, `haechi-crypto-kms` Vault `fetch`)가 **request 직전**(post-DNS) `lookup` 후 `isBlockedAddress` 재검사를 `redirect: "error"`·bounded body·timeout과 함께 수행. 운영자 신뢰 엔드포인트에 한함 |
 | audit/로그로의 token/secret leak (broker) (0.9) | ID/access/refresh token, `client_secret`, `code`, `state`, `nonce`, raw `sub`가 audit 로그나 client 응답에 기록됨 | broker는 모든 audit 이벤트를 자체 allowlist로 projection해 `subjectHash`/`issuerHash`/`sessionIdHash`(keyed-HMAC) + `provider`/`reasonCode`/timestamp만 방출; core `FORBIDDEN_KEYS`를 broker token/claim key까지 확장; access token은 **폐기**(저장·사용 안 함). 실질적 잔여 없음 |
 | KMS backend egress (Vault HTTP, GCP/Azure SDK) (0.9) | `haechi-crypto-kms` Vault/GCP/Azure backend가 key material이나 provider/key-path 상세를 유출하거나 의도치 않은 엔드포인트에 도달 | optional-peer + injected-client 모델과 **faithful-mock conformance**(cross-key·corrupted-blob 거부, HMAC determinism/domain-separation); Vault `fetch`는 위 satellite-local SSRF 가드 수행; 모든 backend는 provider 오류를 generic fail-closed 오류로 매핑하고 provider/key-ARN 상세를 audit에 기록하지 않음. live-backend 검증은 CI 외부 |
+| 동적 로딩된 악의적/침해된 signed plugin (1.0) | signed `authProvider` plugin이 worker sandbox에 로딩된 뒤 실행 중 host를 악용 | `canonicalize({pluginId, kind, version, capabilities, coreVersionRange, entrySha256, notBefore, notAfter})`에 대한 Ed25519 서명, **trust-anchor-only** 키 해석(`signerKeyId`가 allowlist된 anchor가 아니면 verify 이전 거부; 알고리즘은 Ed25519로 고정), pin + `pluginId`별 version-floor + revocation denylist(`revokedSignerKeyIds`/`revokedEntrySha256`) + validity-window 집행, `assertAuthProviderConformance` 정합성 게이트, `node:worker_threads` memory/crash 격리 + per-call timeout-terminate, 전체 lifecycle audit(`plugin.load.*`/`authenticate.deny`/`worker.terminated`). 전체 게이트는 매 respawn마다 재실행. **수용된 잔여:** signed plugin 자신의 `fs`/`fetch`/`process.env`는 차단되지 않으며(`networkEgress: false`는 선언일 뿐 1.0에서 집행 통제 아님) 정당하게 받은 credential을 exfiltrate할 수 있음 — 오직 signing/vetting 신뢰 모델로만 통제됨. 진짜 capability 집행(child-process + Node permission model)은 1.x 경로 |
+| plugin으로의 PII/secret leak (1.0) | request body·crypto 키·token vault·raw claim이 worker 경계를 넘어 유출 | host는 worker에 **credential slice만** 전달(`Authorization` 헤더 / bearer token — request body 절대 안 보냄, crypto 키 절대 안 보냄); wire는 MessagePort 위 평문 JSON 문자열; **null-prototype, own-key-allowlist claims sanitizer**가 `__proto__`/`constructor`/`prototype`을 제거하고 크기를 bound한 뒤 **host**가 `buildExternalIdentity`로 keyed-HMAC identity를 구성(HMAC 키는 worker에 들어가지 않음). **수용된 잔여:** auth plugin이 정당하게 검증하는 credential은 그 plugin에 보임(위 행 참조) |
+| 경계 간 object/proto smuggling (1.0) | 악의적 claims object가 host prototype을 오염시키거나 raw 값을 경계 너머로 밀반입 | JSON-string wire만 사용(structured-clone 없음, `SharedArrayBuffer`/transferables 없음 → shared-memory·object-graph 채널 없음) + `buildExternalIdentity` 이전 null-proto own-key-allowlist sanitizer. 실질적 잔여 없음 |
+| plugin entry의 swap / TOCTOU (1.0) | 서명 검사 후 실행 전에 검증된 entry 바이트가 swap됨(예: symlink 경로 재해석) | 서명이 `entrySha256`을 바인딩; loader는 entry를 **메모리로** 읽어 hash·verify하고 **메모리 내 검증된 소스에서** Worker를 spawn(`eval: true`)하며 검증 후 경로를 재해석하지 않고 symlink entry를 거부. 실질적 잔여 없음 |
+| signer-key confusion / downgrade / rollback / malicious update (1.0) | confused-deputy가 검증 키/알고리즘을 바꾸거나, 신뢰 signer가 같은 anchor로 새/old-vulnerable entry를 조용히 배포 | trust-anchor-only 해석 + Ed25519 알고리즘 고정(alg agility 없음, HS/RS confusion 없음; signer 집합은 별도 curated 목록이며 AES rotation 키 파일이 아님) + pin(`version`/`entrySha256`/`manifestSha256`) + `pluginId`별 version-floor + revocation denylist. **잔여:** 운영자가 anchor/pin을 curate해야 함 |
+| Plugin DoS (1.0) | 버그 있거나 악의적인 signed plugin이 hang/runaway하거나 host를 flood | call별 필수 양의 `timeoutMs`(timeout 시 host가 **worker를 terminate**하고 `null` 반환, lazily respawn), heap `resourceLimits`, `maxPendingCalls`(초과 → deny), `maxMessageBytes`(초과 → deny), single-occupancy worker(per-call terminate가 sibling을 죽일 수 없음). **잔여:** signed plugin이 timeout 내에서 할당된 CPU를 소진할 수 있음(CPU/fd/socket은 1.0에서 bound 안 됨) |
+| 감사되지 않는 code-load (1.0) | tamper-evident 기록 없이 third-party 코드를 로딩/실행 | 모든 load/deny/terminate 결정이 chained audit 이벤트 — `plugin.load.accepted`/`plugin.load.refused{reason}`/`plugin.authenticate.deny{reason}`/`plugin.worker.terminated{cause}`(ids/hashes/counts만); `FORBIDDEN_KEYS`를 확장(`claims`, `subject`, `issuer`, `credential`, `authorization`, `signature`, `entry`, 추가로 `scopes`/`labels`)해 defense-in-depth 적용, audit identity는 frozen 5 키 `{id, type, subjectHash, issuerHash, provider}`로 projection. — |
+| conformance test/prod 괴리 (1.0) | signed plugin이 고정된 conformance 테스트를 감지해 정상 행동한 뒤 운영에서 오작동 | `assertAuthProviderConformance`는 **load별 예측 불가 randomized vectors**를 사용하고, load-bearing하게 **host가 매 call마다 PII-safety를 재검증**(`buildExternalIdentity` + sanitizer가 요청별 실행)하며 load 시점에만 검증하지 않음. **잔여:** conformance-pass가 신뢰성을 함의하지 않음 — 악의적 plugin이 통과 후 오작동 가능(conformance가 아니라 signing+vetting 게이트로 통제) |
 
 ## 4. 명시적 제외
 
@@ -86,6 +94,11 @@ Haechi가 보호하려는 주요 자산은 다음이다.
 - refresh-token rotation / silent renewal / 장수명 broker 세션 — 0.9 세션은 absolute-TTL + idle-timeout만; `offline_access`는 제거되고 access token은 폐기 (0.9)
 - Dashboard write action(reveal, purge, policy edit) — `haechi-dashboard`는 읽기 전용으로 `POST`/`DELETE` surface 없음; mutation은 reveal governance 하의 CLI에 유지 (0.9)
 - OIDC broker의 `at_hash`/`c_hash` 검증 — broker가 access token을 사용하지 않으므로 정확히 범위 외 (0.9)
+- 악의적 signed plugin에 대한 capability *집행*(`fs`/`net`/`process.env` 차단) — Node permission model 하의 child-process 격리가 필요; 1.0 worker 격리는 memory/crash 격리 + data-minimization만 제공 (1.0)
+- signed `authProvider` plugin이 정당하게 받는 credential의 봉쇄 — de-facto network egress가 있어 exfiltrate 가능; 오직 signing/vetting 신뢰 모델로만 통제 (1.0)
+- classifier/filter 및 crypto plugin 로딩 — 1.0에서 동적 로딩 가능한 plugin kind는 `authProvider`뿐; 다른 kind는 injection-only 유지 (1.0)
+- unsigned dev/loader 경로 — unsigned plugin loader는 없음; 개발은 `createRuntime(config, providers)` 주입 사용 (1.0)
+- live revocation feed / CRL — revocation은 다음 load/restart에 적용(global/per-plugin kill-switch가 live plugin을 즉시 force-drop); live CRL은 1.x (1.0)
 
 ## 5. 남은 운영 전제
 

package/docs/current/threat-model.md

@@ -2,7 +2,7 @@
 
 - Status: Draft 0.1
 - Date: 2026-06-10
-- Target version: 0.9.0
+- Target version: 1.0.0
 
 ## 1. Assets Under Protection
 
@@ -65,6 +65,14 @@ The primary assets Haechi protects are:
 | Broker SSRF to cloud metadata via the token-endpoint POST (and Vault `fetch`) (0.9) | A `token_endpoint` (or operator-supplied `VAULT_ADDR`) that DNS-rebinds to `169.254.169.254` between discovery and request exfiltrates instance-metadata credentials | Every egress (discovery GET, JWKS GET via the shared verifier, token-exchange POST, end-session redirect, and the `haechi-crypto-kms` Vault `fetch`) runs a `lookup`-then-`isBlockedAddress` re-check **immediately before the request** (post-DNS), with `redirect: "error"`, a bounded response body, and a timeout. Operator-trusted endpoints only |
 | Token/secret leak into audit/logs (broker) (0.9) | An ID/access/refresh token, `client_secret`, `code`, `state`, `nonce`, or raw `sub` is written to the audit log or a client response | The broker projects every audit event through its own allowlist and emits only `subjectHash`/`issuerHash`/`sessionIdHash` (keyed-HMAC) + `provider`/`reasonCode`/timestamp; core's `FORBIDDEN_KEYS` is extended to cover the broker token/claim keys; the access token is **discarded** (never stored or used). None material |
 | KMS backend egress (Vault HTTP, GCP/Azure SDK) (0.9) | A `haechi-crypto-kms` Vault/GCP/Azure backend leaks key material or provider/key-path detail, or reaches an unintended endpoint | Optional-peer + injected-client model with **faithful-mock conformance** (cross-key + corrupted-blob rejection, HMAC determinism/domain-separation); the Vault `fetch` runs the satellite-local SSRF guard above; all backends map provider errors to a generic fail-closed error and never write provider/key-ARN detail to audit. Live-backend validation is out of CI |
+| Malicious/compromised signed plugin loaded dynamically (1.0) | A signed `authProvider` plugin is loaded into the worker sandbox and abuses the host once running | Ed25519 signature over `canonicalize({pluginId, kind, version, capabilities, coreVersionRange, entrySha256, notBefore, notAfter})`, **trust-anchor-only** key resolution (refuse before verify if `signerKeyId` is not an allowlisted anchor; algorithm pinned to Ed25519), pin + per-`pluginId` version-floor + revocation denylist (`revokedSignerKeyIds`/`revokedEntrySha256`) + validity-window enforcement, `assertAuthProviderConformance` correctness gate, `node:worker_threads` memory/crash isolation + per-call timeout-terminate, and full lifecycle audit (`plugin.load.*`/`authenticate.deny`/`worker.terminated`). The full gate re-runs on every respawn. **Accepted residual:** a signed plugin's own `fs`/`fetch`/`process.env` is NOT blocked — `networkEgress: false` is a declaration, not an enforced control in 1.0 — and the plugin CAN exfiltrate the credential it legitimately receives; this is gated only by the signing/vetting trust model. True capability enforcement (child-process + Node permission model) is the 1.x path |
+| PII/secret leak to a plugin (1.0) | The request body, crypto key, token vault, or a raw claim leaks across the worker boundary | The host sends the worker **only the credential slice** (the `Authorization` header / bearer token — never the request body, never the crypto key); the wire is a plain JSON string over the MessagePort; a **null-prototype, own-key-allowlist claims sanitizer** strips `__proto__`/`constructor`/`prototype` and bounds size before the **host** builds the keyed-HMAC identity via `buildExternalIdentity` (the HMAC key never enters the worker). **Accepted residual:** the credential the auth plugin legitimately validates is visible to it (see the row above) |
+| Cross-boundary object/proto smuggling (1.0) | A hostile claims object pollutes the host prototype or smuggles a raw value back across the boundary | JSON-string wire only (no structured-clone, no `SharedArrayBuffer`/transferables → no shared-memory or object-graph channel) + the null-proto own-key-allowlist sanitizer before `buildExternalIdentity`. None material |
+| Swap / TOCTOU on the plugin entry (1.0) | The verified entry bytes are swapped (e.g. a symlinked path re-resolved) after signature check but before execution | The signature binds `entrySha256`; the loader reads the entry **into memory**, hashes, verifies, and spawns the Worker **from the in-memory verified source** (`eval: true`), never re-resolving the path after verification, and refuses a symlinked entry. None material |
+| Signer-key confusion / downgrade / rollback / malicious update (1.0) | A confused-deputy swaps the verification key/algorithm, or a trusted signer silently ships a new or old-vulnerable entry under the same anchor | Trust-anchor-only resolution + pinned Ed25519 algorithm (no alg agility, no HS/RS confusion; the signer set is a separate curated list, never the AES rotation key file) + pin (`version`/`entrySha256`/`manifestSha256`) + per-`pluginId` version-floor + revocation denylist. **Residual:** the operator must curate anchors/pins |
+| Plugin DoS (1.0) | A buggy or hostile signed plugin hangs, runs away, or floods the host | Required positive `timeoutMs` per call (on timeout the host **terminates the worker** and returns `null`, respawning lazily), heap `resourceLimits`, `maxPendingCalls` (excess → deny), `maxMessageBytes` (oversized → deny), single-occupancy worker (a per-call terminate can never kill a sibling). **Residual:** a signed plugin can burn its allotted CPU within the timeout (CPU/fd/socket are not bounded in 1.0) |
+| Unaudited code-load (1.0) | Loading or executing third-party code without a tamper-evident record | Every load/deny/terminate decision is a chained audit event — `plugin.load.accepted`/`plugin.load.refused{reason}`/`plugin.authenticate.deny{reason}`/`plugin.worker.terminated{cause}` (ids/hashes/counts only); `FORBIDDEN_KEYS` is extended (`claims`, `subject`, `issuer`, `credential`, `authorization`, `signature`, `entry`, plus `scopes`/`labels`) as defense-in-depth, and the audit identity is projected to the frozen 5 keys `{id, type, subjectHash, issuerHash, provider}`. — |
+| Conformance test/prod divergence (1.0) | A signed plugin detects a fixed conformance test and behaves, then misbehaves in production | `assertAuthProviderConformance` uses **unpredictable per-load randomized vectors**, and — load-bearing — the **host re-validates PII-safety on every call** (`buildExternalIdentity` + the sanitizer run per request), not just at load. **Residual:** conformance-pass does not imply trustworthiness — a malicious plugin can pass then misbehave (covered by the signing+vetting gate, not by conformance) |
 
 ## 4. Explicit Exclusions
 
@@ -86,6 +94,11 @@ The primary assets Haechi protects are:
 - Refresh-token rotation / silent renewal / long-lived broker sessions — 0.9 sessions are absolute-TTL + idle-timeout only; `offline_access` is stripped and the access token is discarded (0.9)
 - Dashboard write actions (reveal, purge, policy edits) — `haechi-dashboard` is read-only with no `POST`/`DELETE` surface; mutation stays in the CLI under reveal governance (0.9)
 - `at_hash`/`c_hash` validation in the OIDC broker — out of scope precisely because the broker never uses the access token (0.9)
+- Capability *enforcement* against a malicious signed plugin (blocking `fs`/`net`/`process.env`) — needs child-process isolation under the Node permission model; 1.0 worker isolation is memory/crash isolation + data-minimization only (1.0)
+- Containment of the credential a signed `authProvider` plugin legitimately receives — it has de-facto network egress and can exfiltrate it; gated only by the signing/vetting trust model (1.0)
+- Classifier/filter and crypto plugin loading — `authProvider` is the only dynamically loadable plugin kind in 1.0; other kinds stay injection-only (1.0)
+- An unsigned dev/loader path — there is no unsigned plugin loader; development uses `createRuntime(config, providers)` injection (1.0)
+- A live revocation feed / CRL — revocation takes effect at the next load/restart (a global/per-plugin kill-switch force-drops a live plugin immediately); a live CRL is 1.x (1.0)
 
 ## 5. Remaining Operational Assumptions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "Experimental developer preview for self-hosted AI context enforcement across LLM, MCP, vLLM, Ollama, and agent traffic.",
   "license": "Apache-2.0",
   "type": "module",
@@ -72,8 +72,9 @@
     "sbom": "node scripts/generate-sbom.mjs",
     "checksums": "node scripts/release-checksums.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",
+    "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: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",

package/packages/audit/index.mjs

@@ -15,7 +15,19 @@ const FORBIDDEN_KEYS = new Set([
   // elsewhere, and the broker already self-guards them via its own allowlist
   // projection.
   "access_token", "id_token", "refresh_token", "code", "code_verifier",
-  "client_secret", "state", "nonce"
+  "client_secret", "state", "nonce",
+  // Plugin/claims surface (1.0): a dynamically-loaded auth plugin's lifecycle
+  // events carry only ids/hashes/counts, but this additive membership is
+  // defense-in-depth so a future plugin event can never leak a raw claim, the
+  // received credential/authorization, the signer's signature, or the entry
+  // source into the chained log.
+  "claims", "subject", "issuer", "credential", "authorization", "signature", "entry",
+  // The frozen 1.0 audit-identity contract is exactly {id,type,subjectHash,
+  // issuerHash,provider} — scopes/labels are NOT part of it. This additive
+  // guard ensures that even if a future code path passes an un-projected
+  // identity object, scopes/labels (which can carry attacker-controlled plugin
+  // claim values) can never enter the hash-chained audit record.
+  "scopes", "labels"
 ]);
 
 export function createJsonlAuditSink({ path, anchor = null }) {

package/packages/auth/index.mjs

@@ -212,4 +212,177 @@ export function createBearerAuthProvider({ path, cryptoProvider }) {
   };
 }
 
+// Conformance suite for any authProvider — the CORRECTNESS gate the plugin
+// loader runs before wiring a (sandboxed) auth plugin. It is NOT a malice screen
+// (a signed plugin can detect a fixed test and behave, so vectors are randomized
+// per run and the host re-validates PII-safety per call); it asserts the
+// enumerated security behaviors of the authProvider contract:
+//   - missing credential -> null
+//   - malformed credential -> null
+//   - expired / not-yet-valid credential (clock via injected now) -> null
+//   - an internal throw surfaces to the caller as null (never propagates)
+//   - a returned identity MUST carry subjectHash AND issuerHash, and MUST NOT
+//     contain any field whose value equals the raw input subject or issuer
+//   - deny is DETERMINISTIC for identical input
+//   - a valid credential -> a well-formed PII-safe identity
+//
+// vectors lets a caller supply the request builders / raw values; by default a
+// randomized-per-run vector set is generated so a plugin cannot hardcode the
+// test. Mirrors assertCryptoProviderConformance's check/assert/failures shape.
+export async function assertAuthProviderConformance(provider, { now = Date.now(), vectors } = {}) {
+  const failures = [];
+  const check = async (name, fn) => {
+    try {
+      await fn();
+    } catch (error) {
+      failures.push(`${name}: ${error.message}`);
+    }
+  };
+  const assert = (condition, message) => {
+    if (!condition) {
+      throw new Error(message);
+    }
+  };
+
+  if (typeof provider?.authenticate !== "function") {
+    throw new Error("authProvider must implement authenticate()");
+  }
+
+  const v = vectors ?? randomAuthVectors(now);
+
+  // A contract-conformant authProvider must never throw into the caller. We wrap
+  // every call so a throw becomes an explicit failure in the relevant check
+  // rather than aborting the whole suite — except the dedicated throw-vector
+  // check below, which asserts the provider itself swallowed the throw.
+  const callRaw = (request) => provider.authenticate(request);
+  const callSafe = async (request) => {
+    try {
+      return await provider.authenticate(request);
+    } catch (error) {
+      return { __threw: true, error };
+    }
+  };
+
+  await check("missing credential -> null", async () => {
+    const result = await callSafe(v.missing.request);
+    assert(!result?.__threw, "authenticate threw on a missing credential (must return null)");
+    assert(result === null, "missing credential must deny with null");
+  });
+
+  await check("malformed credential -> null", async () => {
+    const result = await callSafe(v.malformed.request);
+    assert(!result?.__threw, "authenticate threw on a malformed credential (must return null)");
+    assert(result === null, "malformed credential must deny with null");
+  });
+
+  await check("expired credential -> null", async () => {
+    const result = await callSafe(v.expired.request);
+    assert(!result?.__threw, "authenticate threw on an expired credential (must return null)");
+    assert(result === null, "expired credential must deny with null");
+  });
+
+  await check("not-yet-valid credential -> null", async () => {
+    const result = await callSafe(v.notYetValid.request);
+    assert(!result?.__threw, "authenticate threw on a not-yet-valid credential (must return null)");
+    assert(result === null, "not-yet-valid credential must deny with null");
+  });
+
+  await check("an internal throw surfaces to the caller as null (never propagates)", async () => {
+    let propagated = false;
+    let result;
+    try {
+      result = await callRaw(v.throwing.request);
+    } catch {
+      propagated = true;
+    }
+    assert(!propagated, "authenticate propagated an internal throw (must catch and deny with null)");
+    assert(result === null, "an internal error must deny with null, not a non-null identity");
+  });
+
+  await check("deny is deterministic for identical input", async () => {
+    const a = await callSafe(v.malformed.request);
+    const b = await callSafe(v.malformed.request);
+    assert(!a?.__threw && !b?.__threw, "authenticate threw while checking determinism");
+    assert(a === b, "deny is not deterministic for identical input (expected null both times)");
+    assert(a === null, "expected a deterministic null deny");
+  });
+
+  await check("valid credential -> a well-formed, PII-safe identity", async () => {
+    const identity = await callSafe(v.valid.request);
+    assert(!identity?.__threw, "authenticate threw on a valid credential");
+    assert(identity && typeof identity === "object", "a valid credential must return an identity object");
+    assert(typeof identity.subjectHash === "string" && identity.subjectHash.length > 0,
+      "identity must carry a non-empty subjectHash");
+    assert(typeof identity.issuerHash === "string" && identity.issuerHash.length > 0,
+      "identity must carry a non-empty issuerHash");
+    // PII-safety: no field value may equal the raw input subject or issuer.
+    assertNoRawPii(identity, v.valid.subject, v.valid.issuer, assert);
+
+    // Determinism for the accept path too: identical valid input -> identical
+    // identity (a non-deterministic identity breaks audit correlation).
+    const again = await callSafe(v.valid.request);
+    assert(!again?.__threw, "authenticate threw on a repeated valid credential");
+    assert(JSON.stringify(again) === JSON.stringify(identity),
+      "accept is not deterministic for identical valid input");
+  });
+
+  if (failures.length > 0) {
+    return { ok: false, failures };
+  }
+  return { ok: true, failures: [] };
+}
+
+// Recursively assert no value in the identity equals the raw subject/issuer. The
+// keyed-HMAC subjectHash/issuerHash are derived from these, so an equality
+// against the raw value would mean a PII leak (or an un-hashed passthrough).
+function assertNoRawPii(value, subject, issuer, assert, path = "identity") {
+  if (typeof value === "string") {
+    assert(value !== subject, `${path} contains the raw subject (PII leak)`);
+    assert(value !== issuer, `${path} contains the raw issuer (PII leak)`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertNoRawPii(item, subject, issuer, assert, `${path}[${i}]`));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      assertNoRawPii(item, subject, issuer, assert, `${path}.${key}`);
+    }
+  }
+}
+
+function randomAuthVectors(now) {
+  const nowMs = typeof now === "number" ? now : Date.parse(now);
+  // Per-run random so a plugin cannot hardcode the expected test values.
+  const nonce = randomBytes(8).toString("hex");
+  const subject = `subj-${randomBytes(6).toString("hex")}`;
+  const issuer = `iss-${randomBytes(6).toString("hex")}`;
+  const validToken = `valid.${nonce}.${randomBytes(8).toString("hex")}`;
+  const expiredToken = `expired.${nonce}.${randomBytes(8).toString("hex")}`;
+  const notYetToken = `notyet.${nonce}.${randomBytes(8).toString("hex")}`;
+  const malformedToken = `~malformed~${nonce}`;
+  const throwToken = `throw.${nonce}`;
+
+  const bearer = (token) => ({ headers: { authorization: `Bearer ${token}` } });
+  // The valid credential encodes the random subject/issuer so any provider that
+  // echoes/leaks them into the returned identity is caught by assertNoRawPii.
+  // The credential is structured as "valid.<nonce>.<randHex>.<subject>.<issuer>"
+  // so a provider COULD extract them — but it MUST then keyed-hash them (not echo
+  // them raw) for the PII-safety assertion to pass. This makes the default-vector
+  // PII check non-vacuous: a leaking provider fails without custom vectors.
+  const validTokenWithPii = `${validToken}.${subject}.${issuer}`;
+  return {
+    nowMs,
+    subject,
+    issuer,
+    missing: { request: { headers: {} } },
+    malformed: { request: bearer(malformedToken), token: malformedToken },
+    expired: { request: bearer(expiredToken), token: expiredToken },
+    notYetValid: { request: bearer(notYetToken), token: notYetToken },
+    throwing: { request: bearer(throwToken), token: throwToken },
+    valid: { request: bearer(validTokenWithPii), token: validTokenWithPii, subject, issuer }
+  };
+}
+
 export { DEFAULT_ALLOWED_LABEL_KEYS };

package/packages/cli/runtime.mjs

@@ -10,8 +10,22 @@ import { loadVerifiedPolicyBundleFileSync } from "../policy-bundle/index.mjs";
 import { createProtocolAdapter } from "../protocol-adapters/index.mjs";
 import { applyPrivacyProfile, getPrivacyProfile } from "../privacy-profiles/index.mjs";
 import { createBearerAuthProvider } from "../auth/index.mjs";
+import { createSandboxedAuthProviderSync } from "../plugin/index.mjs";
 import { DEFAULT_PROXY_PORT } from "../proxy/index.mjs";
 
+// Capability keys an operator may allowlist for a plugin. Mirrors the plugin
+// manifest's declared-capability set plus the authProvider-specific
+// readsCredentials. Inlined (not imported) to keep the dependency one-way.
+const KNOWN_PLUGIN_CAPABILITIES = new Set([
+  "readsPlaintext",
+  "writesPlaintext",
+  "networkEgress",
+  "fileWrite",
+  "auditWrite",
+  "externalSecrets",
+  "readsCredentials"
+]);
+
 export const DEFAULT_CONFIG_PATH = "haechi.config.json";
 
 export function defaultConfig() {
@@ -85,6 +99,12 @@ export function defaultConfig() {
       store: ".haechi/auth.json",
       allowedLabelKeys: ["team", "env", "tier", "role"]
     },
+    // Top-level kill-switch for dynamic plugin loading (1.0 §2.2). Default true;
+    // an operator sets `plugins.enabled: false` to force-refuse construction of
+    // any sandboxed plugin (a live force-drop, since revocation is next-load).
+    plugins: {
+      enabled: true
+    },
     mcp: {
       allowedMethods: ["initialize", "tools/call", "resources/read", "prompts/get"],
       protectParams: true,
@@ -128,8 +148,10 @@ export function createRuntime(config, providers = {}) {
   // closed at construction rather than deep in a request if a needing feature
   // is configured without it.
   if (typeof cryptoProvider.hmac !== "function"
-    && (normalized.auth.provider === "bearer" || normalized.tokenVault.deterministic)) {
-    throw new Error("cryptoProvider must implement hmac() for bearer auth / deterministic tokenization");
+    && (normalized.auth.provider === "bearer"
+      || normalized.auth.provider === "plugin"
+      || normalized.tokenVault.deterministic)) {
+    throw new Error("cryptoProvider must implement hmac() for bearer/plugin auth / deterministic tokenization");
   }
   const auditSink = providers.auditSink ?? createJsonlAuditSink({
     path: normalized.audit.path,
@@ -169,7 +191,7 @@ export function createRuntime(config, providers = {}) {
   const policyEngine = providers.policyEngine ?? policyProfiles.base.policyEngine;
   assertProvider("policyEngine", policyEngine, ["decide"]);
 
-  const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider);
+  const authProvider = resolveAuthProvider(normalized, providers, cryptoProvider, auditSink);
 
   return {
     config: normalized,
@@ -250,6 +272,10 @@ export function normalizeConfig(config) {
       ...(config.auth ?? {}),
       allowedLabelKeys: config.auth?.allowedLabelKeys ?? defaultConfig().auth.allowedLabelKeys
     },
+    plugins: {
+      ...defaultConfig().plugins,
+      ...(config.plugins ?? {})
+    },
     mcp: {
       ...defaultConfig().mcp,
       ...(config.mcp ?? {}),
@@ -340,7 +366,7 @@ export function normalizeConfig(config) {
     throw new Error("limits.upstreamTimeoutMs must be a positive number");
   }
   validatePolicyExtras(merged.policy);
-  if (!["none", "bearer", "external"].includes(merged.auth.provider)) {
+  if (!["none", "bearer", "external", "plugin"].includes(merged.auth.provider)) {
     throw new Error(`Invalid auth.provider: ${merged.auth.provider}`);
   }
   if (typeof merged.auth.store !== "string" || !merged.auth.store.trim()) {
@@ -350,6 +376,9 @@ export function normalizeConfig(config) {
     || !merged.auth.allowedLabelKeys.every((key) => typeof key === "string" && key.trim())) {
     throw new Error("auth.allowedLabelKeys must be an array of non-empty strings");
   }
+  if (merged.auth.provider === "plugin") {
+    validatePluginAuthConfig(merged);
+  }
   createProtocolAdapter(merged.target);
   return merged;
 }
@@ -411,7 +440,124 @@ function assertRate(value, label) {
   }
 }
 
-function resolveAuthProvider(config, providers, cryptoProvider) {
+// Enumerated, fail-closed validation of auth.provider:"plugin" (1.0 §2.3). Every
+// rule throws a distinct error so a bad option is attributable. Mirrors the
+// keys/tokenVault rigor — no silent degradation.
+function validatePluginAuthConfig(merged) {
+  // Kill-switch: refuse to construct any plugin when plugins.enabled is false.
+  if (typeof merged.plugins?.enabled !== "boolean") {
+    throw new Error("plugins.enabled must be boolean");
+  }
+  if (merged.plugins.enabled === false) {
+    throw new Error("plugins are disabled (plugins.enabled: false); refusing to construct a plugin authProvider");
+  }
+
+  const plugin = merged.auth.plugin;
+  if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
+    throw new Error("auth.provider 'plugin' requires an auth.plugin object");
+  }
+  if (typeof plugin.manifestPath !== "string" || !plugin.manifestPath.trim()) {
+    throw new Error("auth.plugin.manifestPath must be a non-empty string");
+  }
+
+  // trustAnchors: a non-empty array of {keyId, publicKey} OR a non-empty object
+  // map keyId -> publicKey/anchor.
+  const anchors = plugin.trustAnchors;
+  if (Array.isArray(anchors)) {
+    if (anchors.length === 0) {
+      throw new Error("auth.plugin.trustAnchors must be a non-empty array");
+    }
+    for (const anchor of anchors) {
+      if (!anchor || typeof anchor !== "object"
+        || typeof anchor.keyId !== "string" || !anchor.keyId.trim()
+        || anchor.publicKey === undefined || anchor.publicKey === null) {
+        throw new Error("each auth.plugin.trustAnchors entry must be { keyId, publicKey }");
+      }
+    }
+  } else if (anchors && typeof anchors === "object") {
+    const keys = Object.keys(anchors);
+    if (keys.length === 0) {
+      throw new Error("auth.plugin.trustAnchors must be a non-empty object");
+    }
+    for (const keyId of keys) {
+      if (anchors[keyId] === undefined || anchors[keyId] === null) {
+        throw new Error(`auth.plugin.trustAnchors.${keyId} must be a public key`);
+      }
+    }
+  } else {
+    throw new Error("auth.plugin.trustAnchors must be a non-empty array or object of { keyId, publicKey }");
+  }
+
+  // allowCapabilities: an array of known capability keys, including readsCredentials.
+  if (!Array.isArray(plugin.allowCapabilities) || plugin.allowCapabilities.length === 0) {
+    throw new Error("auth.plugin.allowCapabilities must be a non-empty array of capability keys");
+  }
+  for (const capability of plugin.allowCapabilities) {
+    if (typeof capability !== "string" || !KNOWN_PLUGIN_CAPABILITIES.has(capability)) {
+      throw new Error(`auth.plugin.allowCapabilities contains an unknown capability: ${capability}`);
+    }
+  }
+  if (!plugin.allowCapabilities.includes("readsCredentials")) {
+    throw new Error("auth.plugin.allowCapabilities must include readsCredentials for an authProvider");
+  }
+
+  if (!Number.isInteger(plugin.timeoutMs) || plugin.timeoutMs <= 0) {
+    throw new Error("auth.plugin.timeoutMs must be a positive integer");
+  }
+
+  const limits = plugin.resourceLimits;
+  if (!limits || typeof limits !== "object" || Array.isArray(limits)
+    || !Number.isInteger(limits.maxOldGenerationSizeMb) || limits.maxOldGenerationSizeMb <= 0) {
+    throw new Error("auth.plugin.resourceLimits.maxOldGenerationSizeMb must be a positive integer");
+  }
+
+  if (plugin.maxPendingCalls !== undefined
+    && (!Number.isInteger(plugin.maxPendingCalls) || plugin.maxPendingCalls < 1)) {
+    throw new Error("auth.plugin.maxPendingCalls must be a positive integer");
+  }
+  if (plugin.maxMessageBytes !== undefined
+    && (!Number.isInteger(plugin.maxMessageBytes) || plugin.maxMessageBytes < 1)) {
+    throw new Error("auth.plugin.maxMessageBytes must be a positive integer");
+  }
+
+  if (plugin.pin !== undefined && plugin.pin !== null) {
+    if (typeof plugin.pin !== "object" || Array.isArray(plugin.pin)) {
+      throw new Error("auth.plugin.pin must be an object");
+    }
+    for (const field of ["version", "entrySha256", "manifestSha256"]) {
+      if (plugin.pin[field] !== undefined && plugin.pin[field] !== null
+        && (typeof plugin.pin[field] !== "string" || !plugin.pin[field].trim())) {
+        throw new Error(`auth.plugin.pin.${field} must be a non-empty string`);
+      }
+    }
+  }
+
+  if (plugin.revoked !== undefined && plugin.revoked !== null) {
+    if (typeof plugin.revoked !== "object" || Array.isArray(plugin.revoked)) {
+      throw new Error("auth.plugin.revoked must be an object");
+    }
+    for (const field of ["signerKeyIds", "entrySha256"]) {
+      if (plugin.revoked[field] !== undefined
+        && (!Array.isArray(plugin.revoked[field])
+          || !plugin.revoked[field].every((v) => typeof v === "string" && v.trim()))) {
+        throw new Error(`auth.plugin.revoked.${field} must be an array of non-empty strings`);
+      }
+    }
+  }
+
+  if (plugin.versionFloor !== undefined && plugin.versionFloor !== null) {
+    if (typeof plugin.versionFloor !== "object" || Array.isArray(plugin.versionFloor)) {
+      throw new Error("auth.plugin.versionFloor must be an object mapping pluginId -> version");
+    }
+    for (const [id, floor] of Object.entries(plugin.versionFloor)) {
+      if (typeof floor !== "string" || !floor.trim()) {
+        throw new Error(`auth.plugin.versionFloor.${id} must be a non-empty version string`);
+      }
+    }
+  }
+}
+
+function resolveAuthProvider(config, providers, cryptoProvider, auditSink) {
   if (config.auth.provider === "external") {
     if (typeof providers.authProvider?.authenticate !== "function") {
       throw new Error("auth.provider external requires createRuntime(config, { authProvider })");
@@ -425,9 +571,42 @@ function resolveAuthProvider(config, providers, cryptoProvider) {
   if (config.auth.provider === "bearer") {
     return createBearerAuthProvider({ path: config.auth.store, cryptoProvider });
   }
+  if (config.auth.provider === "plugin") {
+    const plugin = config.auth.plugin;
+    return createSandboxedAuthProviderSync({
+      manifestPath: plugin.manifestPath,
+      trustAnchors: normalizeTrustAnchors(plugin.trustAnchors),
+      allowCapabilities: plugin.allowCapabilities,
+      pin: plugin.pin ?? null,
+      revoked: plugin.revoked ?? {},
+      versionFloor: plugin.versionFloor ?? {},
+      timeoutMs: plugin.timeoutMs,
+      maxPendingCalls: plugin.maxPendingCalls,
+      maxMessageBytes: plugin.maxMessageBytes,
+      resourceLimits: plugin.resourceLimits,
+      coreVersion: plugin.coreVersion ?? null,
+      cryptoProvider,
+      auditSink,
+      allowedLabelKeys: config.auth.allowedLabelKeys
+    });
+  }
   return null;
 }
 
+// The config form is a non-empty array of { keyId, publicKey } OR an object map.
+// verifySignedPlugin resolves the anchor by signerKeyId against an object map, so
+// normalize an array form into that map here.
+function normalizeTrustAnchors(anchors) {
+  if (Array.isArray(anchors)) {
+    const map = {};
+    for (const anchor of anchors) {
+      map[anchor.keyId] = anchor.publicKey;
+    }
+    return map;
+  }
+  return anchors;
+}
+
 function createConfiguredCryptoProvider(config) {
   if (config.keys.provider === "external") {
     throw new Error("keys.provider external requires createRuntime(config, { cryptoProvider })");

package/packages/core/index.mjs

@@ -387,14 +387,29 @@ async function replacementFor(segment, detection, decision, { context, cryptoPro
 
 function buildAuditEvent({ context, mode, enforced, blocked, payload, detections, decisions }) {
   return {
+    // Reader-facing audit-event schema version (frozen as part of the 1.0 API
+    // contract — see docs/current/api-stability.md). Additive-only: a new field
+    // bumps nothing here; only a canonicalization change is a MAJOR schema bump
+    // (a new value + a reader migration). It is part of the canonicalized object
+    // and so is self-consistent for hash-chain verification of new events.
+    schemaVersion: "1",
     id: randomUUID(),
     timestamp: new Date().toISOString(),
     protocol: context.protocol ?? "custom",
     operation: context.operation ?? "protect",
-    // PII-safe identity built by the auth layer (subject/issuer are keyed
-    // HMACs); null when no auth is configured. `profile` is the resolved
-    // policy profile name (or null).
-    identity: context.identity ?? null,
+    // PII-safe identity — projected to the five frozen 1.0 audit-identity keys
+    // (id, type, subjectHash, issuerHash, provider). scopes/labels are available
+    // to the live policy engine via context.identity but are NOT part of the
+    // frozen audit schema (§2.1) and must never be persisted to the hash-chained
+    // log (an untrusted plugin's attacker-controlled label/scope value would
+    // otherwise enter the immutable audit record via this path).
+    identity: context.identity ? {
+      id: context.identity.id,
+      type: context.identity.type,
+      subjectHash: context.identity.subjectHash,
+      issuerHash: context.identity.issuerHash,
+      provider: context.identity.provider
+    } : null,
     profile: context.profile ?? null,
     mode,
     enforced,