haechi 1.3.3 → 1.5.0

package/docs/current/release-process.ko.md

@@ -1,6 +1,6 @@
 # Haechi Release Process
 
-- 문서 상태: Living document (core 1.3.x 추적)
+- 문서 상태: Living document (core 1.5.x 추적)
 - 작성일: 2026-06-10
 
 ## 1. 로컬 릴리즈 검증

package/docs/current/release-process.md

@@ -1,6 +1,6 @@
 # Haechi Release Process
 
-- Status: Living document (tracks core 1.3.x)
+- Status: Living document (tracks core 1.5.x)
 - Date: 2026-06-10
 
 ## 1. Local Release Verification

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

@@ -1,8 +1,8 @@
 # Haechi 리스크 레지스터 및 릴리스 게이트
 
-- 문서 상태: Living document(core 1.3.x 추적)
+- 문서 상태: Living document(core 1.5.x 추적)
 - 작성일: 2026-06-16
-- 기준 버전: 1.3.x
+- 기준 버전: 1.5.x
 - 기준 브랜치: `main`
 
 ## 1. 현재 판단
@@ -14,9 +14,9 @@ Haechi는 `1.x` stable 라인을 출시했습니다. developer preview 게이트
 | 구분 | 판단 | 이유 |
 |---|---|---|
 | GitHub public | 허용 | 보안 한계, threat model, shared responsibility가 문서화됨 |
-| GitHub release/tag | 허용 (`v1.3.3` 릴리스됨) | `v1.3.3`이 현재 릴리스(CR2 컷 `1.3.2` 위의 선제적 하드닝 패치); §5.7 및 §5.8(`CR2-001..008`) 항목은 모두 Resolved 유지, G9/G10은 Pass |
-| npm stable | `haechi@1.3.3` publish됨 | `1.3.3`은 CR2-보완된 `1.3.2` 기준 위에 response-direction marker-skip 강화 + cosign 서명 GHCR 컨테이너 이미지를 더한 attested OIDC publish |
-| production use | 운영자 게이트; `1.3.3`로 업그레이드 | 운영자 네트워크 통제, 인가/인증, key custody가 있을 때만 지원; 운영자는 민감한 제3자 업스트림 트래픽을 프록시로 라우팅하기 전에 최신 `haechi@1.3.3`(1.3.2의 CR2 수정 + marker-skip 하드닝 포함)을 실행해야 함 |
+| GitHub release/tag | 허용 (`v1.5.0` 릴리스됨) | `v1.5.0`이 현재 릴리스(additive minor — 수평 확장을 위한 주입 가능한 audit/token-vault 저장소 시임); §5.7 / §5.8 항목은 모두 Resolved 유지, G9–G12는 Pass |
+| npm stable | `haechi@1.5.0` publish됨 | `1.5.0`은 `1.4.x` 기준 위에 `createAuditSink`/`createTokenVault` 저장소 시임(파일 기본값 바이트 동일)을 더한 attested OIDC publish; config/API 파괴 없음(`configVersion`은 `1` 유지) |
+| production use | 운영자 게이트; `1.5.0`로 업그레이드 | 운영자 네트워크 통제, 인가/인증, key custody가 있을 때만 지원; 여러 replica를 운영하는 운영자는 공유 저장소(`haechi-store-redis` 위성)를 주입해 audit 해시 체인과 token vault가 플릿 전체에서 유지되도록 해야 함 |
 
 ## 2. 릴리스 게이트
 
@@ -33,6 +33,8 @@ Haechi는 `1.x` stable 라인을 출시했습니다. developer preview 게이트
 | G8 | 1.3.0 백엔드 + 탐지 커버리지 확장 | **Anthropic Messages API**(`/v1/messages`, content-block + SSE `delta.text`, `event:` 라인 보존 재직렬화)와 **Google Gemini API**(model-in-path `:generateContent`/`:streamGenerateContent`, 기존 정확-매칭 어댑터를 바이트 동일하게 두는 additive `:method`-suffix 라우트 매처) 프로토콜 어댑터 추가; 탐지 커버리지 확장 — 클라우드/SaaS provider 키(OpenAI/Anthropic/Google-OAuth/SendGrid/Twilio/npm/Azure, anchored)와 국제 PII(FR/ES/JP + IT/SG/IN/DE/NL 국가 ID, 체크섬 validator), 각 하드블록-대-dial-eligible 결정은 측정된 충돌률 기반(하드블록은 비숫자 앵커 또는 비현실적으로 드문 형태가 필요; 흔한 길이의 bare-digit run은 allowlist로 정리 가능 유지); `bench:throughput` proxy 부하 벤치; `haechi-ratelimit-redis` 공유 저장소 rate-limiter 위성(WS3 시임의 운영 소비자; proxy가 이제 `rateLimiter.allow`를 `await`); `haechi-dashboard`가 요청별 `correlationId` 노출. 모든 변경은 additive — 새 `target.type`/탐지타입/`privacy.profile` *값*이며 새 config 키가 아님(`configVersion`은 `1` 유지); `tests/api-contract.test.mjs` 통과; core는 zero runtime dependency 유지; core 1.3.0 bump(additive 마이너) | Pass |
 | G9 | 2026-06-16 전체 코드리뷰 보완 게이트 (1.3.1로 발행) | `P0-CR-001` 및 `P1-CR-002`부터 `P1-CR-005`까지 해결 또는 책임자 명시 수용; P2 항목은 해결 또는 명시적 non-blocking 근거와 일정 기록; 연결된 등록부 갱신. **13개 `P*-CR-*` 항목이 모두 Resolved이며(§5.7) `haechi@1.3.1`(2026-06-16, attested OIDC publish)로 발행되었습니다; core가 1.3.0 → 1.3.1로 bump(patch, 보완 전용 — API/config 표면 변경 없음, `configVersion`은 `1` 유지)되었습니다.** | Pass (`haechi@1.3.1`, 2026-06-16) |
 | G10 | 2026-06-16 코드리뷰 round 2 (CR2) 보완 게이트 | CR2 등록부(`code-review-risk-register-2026-06-16-round2.md`, §5.8)는 **P0/P1을 발견하지 못했습니다**; 세 개의 P2(`CR2-001` 프록시 upstream-cancel, `CR2-002` token-vault audit hygiene, `CR2-003` plugin IPC reply 경계)와 P3 묶음(`CR2-004..008`)이 모두 **Resolved이며 `haechi@1.3.2`로 발행되었고**(`CR2-009` won't-fix, `CR2-010` accepted) 연결된 등록부가 갱신되었습니다. | Pass (`haechi@1.3.2`, 2026-06-16) |
+| G11 | 1.4.0 signed-plugin 저작 CLI | 1.0 Ed25519 trust gate를 위한 1차 저작 CLI — `plugin-keygen`(개인키 `0600`, 공개키 = trust anchor), `plugin-sign`(정확한 entry 바이트 바인딩), `plugin-verify`(런타임 동등 검증, fail-closed, `--allow-capability`); 개인키가 stdout/audit로 유출되지 않음; 적대적 검증 완료; `plugin-signing-and-trust.md` 큐레이션 런북이 P1-SEC-025 "운영자가 앵커를 큐레이션해야 함" 잔여를 해소. additive CLI 표면(config/API 파괴 없음, `configVersion`은 `1` 유지); `tests/api-contract.test.mjs` green; 코어는 zero runtime dependency 유지; 코어 1.3.3 → 1.4.0(additive minor)로 bump. | Pass (`haechi@1.4.0`, 2026-06-17) |
+| G12 | 1.5.0 수평 확장 저장소 시임 | audit sink와 token vault가 주입 가능한 **store**를 갖게 되어, 공유 저장소가 sha256 해시 체인 + token vault를 replica 전반에서 뒷받침할 수 있음(프로세스별 / 단일 writer 플릿 한계를 해소). `createAuditSink({store})` / `createTokenVault({store})` + 기본 `createFileAuditStore`/`createFileTokenStore`; 보안에 결정적인 chaining / `sanitizeAudit` / reveal governance / retention은 코어에 남고, store는 배타적 read-previous+persist(audit) / mutate+read(vault) 프리미티브만 추상화. 적대적 검증 완료: 파일 기본값 바이트 동일, chain 연산은 이전과 diff 동일, 비파일 store에서도 시임 동작, 동시 append/tokenize가 비분기·무손실 유지, CR2-002 audit-no-plaintext 유지. 새 export는 `api-stability.md` + `tests/api-contract.test.mjs`에 frozen; `createJsonlAuditSink`/`createLocalTokenVault`는 하위호환 래퍼; 코어는 zero runtime dependency 유지; 코어 1.4.0 → 1.5.0(additive minor)로 bump. `haechi-store-redis` 위성이 운영 소비자. | Pass (`haechi@1.5.0`, 2026-06-17) |
 
 ## 3. P0 배포 차단 리스크 상태
 

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

@@ -1,6 +1,6 @@
 # Haechi Risk Register and Release Gates
 
-- Status: Living document (tracks core 1.3.x)
+- Status: Living document (tracks core 1.5.x)
 - Date: 2026-06-16
 - Target version: 1.3.x
 - Branch: `main`
@@ -14,9 +14,9 @@ Haechi has shipped its `1.x` stable line. The developer-preview gate (G2, `haech
 | Category | Judgment | Rationale |
 |---|---|---|
 | GitHub public | Allowed | Security limitations, threat model, and shared responsibility are documented |
-| GitHub release/tag | Allowed (`v1.3.3` released) | `v1.3.3` is the current release (a proactive-hardening patch over the CR2 cut `1.3.2`); all §5.7 and §5.8 (`CR2-001..008`) findings remain Resolved and G9/G10 are Pass |
-| npm stable | `haechi@1.3.3` published | `1.3.3` is an attested OIDC publish adding the response-direction marker-skip tightening + a cosign-signed GHCR container image, over the CR2-remediated `1.3.2` baseline |
-| Production use | Operator-gated; upgrade to `1.3.3` | Supported only with operator network controls, authz/authn, and key custody; operators should run the latest `haechi@1.3.3` (it carries the CR2 fixes from `1.3.2` plus the marker-skip hardening) before routing sensitive third-party upstream traffic through the proxy |
+| GitHub release/tag | Allowed (`v1.5.0` released) | `v1.5.0` is the current release (additive minor — injectable audit/token-vault store seams for horizontal scale); all §5.7 / §5.8 findings remain Resolved and G9–G12 are Pass |
+| npm stable | `haechi@1.5.0` published | `1.5.0` is an attested OIDC publish adding `createAuditSink`/`createTokenVault` store seams (file defaults byte-identical) over the `1.4.x` baseline; no config/API break (`configVersion` stays `1`) |
+| Production use | Operator-gated; upgrade to `1.5.0` | Supported only with operator network controls, authz/authn, and key custody; operators running multiple replicas should inject a shared store (the `haechi-store-redis` satellite) so the audit hash chain and token vault hold across the fleet |
 
 ## 2. Release Gates
 
@@ -33,6 +33,8 @@ Haechi has shipped its `1.x` stable line. The developer-preview gate (G2, `haech
 | G8 | 1.3.0 backend + detection coverage expansion | New protocol adapters for the **Anthropic Messages API** (`/v1/messages`, content-block + SSE `delta.text` with `event:`-line-preserving re-serialize) and the **Google Gemini API** (model-in-path `:generateContent`/`:streamGenerateContent` via an additive `:method`-suffix route matcher that leaves the exact-match adapters byte-identical); detection coverage expansion — cloud/SaaS provider keys (OpenAI/Anthropic/Google-OAuth/SendGrid/Twilio/npm/Azure, anchored) and international PII (FR/ES/JP + IT/SG/IN/DE/NL national IDs with checksum validators), each hard-block-vs-dial-eligible decision driven by measured collision rates (a non-numeric anchor or implausibly-rare shape is required for hard-block; a bare-digit run over a common length stays allowlist-clearable); a `bench:throughput` proxy load benchmark; the `haechi-ratelimit-redis` shared-store rate-limiter satellite (the WS3 seam's production consumer; the proxy now `await`s `rateLimiter.allow`); `haechi-dashboard` surfaces the per-request `correlationId`. Every change is additive — new `target.type`/detection-type/`privacy.profile` *values*, not new config keys (`configVersion` stays `1`); `tests/api-contract.test.mjs` green; core stays zero runtime dependency; core bumped to 1.3.0 (additive minor) | Pass |
 | G9 | 2026-06-16 full code-review remediation gate (shipped in 1.3.1) | `P0-CR-001` and `P1-CR-002` through `P1-CR-005` resolved or formally accepted; P2 items either resolved or scheduled with explicit non-blocking rationale; linked register updated. **All 13 `P*-CR-*` findings are Resolved (§5.7) and shipped in `haechi@1.3.1` (2026-06-16, attested OIDC publish); core bumped 1.3.0 → 1.3.1 (patch, remediation-only — no API/config surface change, `configVersion` stays `1`).** | Pass (`haechi@1.3.1`, 2026-06-16) |
 | G10 | 2026-06-16 code-review round 2 (CR2) remediation gate | The CR2 register (`code-review-risk-register-2026-06-16-round2.md`, §5.8) found **no P0/P1**; its three P2s (`CR2-001` proxy upstream-cancel, `CR2-002` token-vault audit hygiene, `CR2-003` plugin IPC reply bound) plus the P3 cluster (`CR2-004..008`) are all **Resolved and shipped in `haechi@1.3.2`** (`CR2-009` won't-fix, `CR2-010` accepted) and the linked register is updated. | Pass (`haechi@1.3.2`, 2026-06-16) |
+| G11 | 1.4.0 signed-plugin authoring CLI | First-party CLI for the 1.0 Ed25519 trust gate — `plugin-keygen` (private key `0600`, public key = trust anchor), `plugin-sign` (binds the exact entry bytes), `plugin-verify` (runtime-equivalent verification, fail-closed, `--allow-capability`); no private-key leak to stdout/audit; adversarially verified; the `plugin-signing-and-trust.md` curation runbook closes the P1-SEC-025 "operator must curate anchors" residual. Additive CLI surface (no config/API break, `configVersion` stays `1`); `tests/api-contract.test.mjs` green; core stays zero runtime dependency; core bumped 1.3.3 → 1.4.0 (additive minor). | Pass (`haechi@1.4.0`, 2026-06-17) |
+| G12 | 1.5.0 horizontal-scale store seams | The audit sink and token vault gain an injectable **store** so a shared store can back the sha256 hash chain + token vault across replicas (closes the per-process / single-writer fleet limitations). `createAuditSink({store})` / `createTokenVault({store})` + the default `createFileAuditStore`/`createFileTokenStore`; the security-critical chaining / `sanitizeAudit` / reveal governance / retention stay in core, the store only abstracts the exclusive read-previous+persist (audit) / mutate+read (vault) primitives. Adversarially verified: file defaults byte-identical, chain math diff-identical to prior, the seam works for a non-file store, concurrent appends/tokenize stay non-forked/lossless, CR2-002 audit-no-plaintext intact. New exports frozen in `api-stability.md` + `tests/api-contract.test.mjs`; `createJsonlAuditSink`/`createLocalTokenVault` are back-compat wrappers; core stays zero runtime dependency; core bumped 1.4.0 → 1.5.0 (additive minor). The `haechi-store-redis` satellite is the production consumer. | Pass (`haechi@1.5.0`, 2026-06-17) |
 
 ## 3. P0 Distribution-Blocking Risk Status
 

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

@@ -1,6 +1,6 @@
 # Haechi Shared Responsibility
 
-- 문서 상태: Living document (core 1.3.x 추적)
+- 문서 상태: Living document (core 1.5.x 추적)
 - 작성일: 2026-06-10
 
 ## 1. 책임 매트릭스

package/docs/current/shared-responsibility.md

@@ -1,6 +1,6 @@
 # Haechi Shared Responsibility
 
-- Status: Living document (tracks core 1.3.x)
+- Status: Living document (tracks core 1.5.x)
 - Date: 2026-06-10
 
 ## 1. Responsibility Matrix

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

@@ -1,6 +1,6 @@
 # Haechi Threat Model
 
-- 문서 상태: Living document(core 1.3.x 추적)
+- 문서 상태: Living document(core 1.5.x 추적)
 - 작성일: 2026-06-10
 
 ## 1. 보호 대상

package/docs/current/threat-model.md

@@ -1,6 +1,6 @@
 # Haechi Threat Model
 
-- Status: Living document (tracks core 1.3.x)
+- Status: Living document (tracks core 1.5.x)
 - Date: 2026-06-10
 
 ## 1. Assets Under Protection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haechi",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "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",

package/packages/audit/index.mjs

@@ -30,9 +30,73 @@ const FORBIDDEN_KEYS = new Set([
   "scopes", "labels"
 ]);
 
-export function createJsonlAuditSink({ path, anchor = null }) {
+// An audit STORE abstracts the exclusive "read-previous + persist" primitive so
+// the SAME core-owned sha256 hash chain can sit on top of a file today and a
+// shared store (e.g. Redis) in a future satellite. The contract is:
+//
+//   async transaction(fn) — runs `fn` inside an EXCLUSIVE critical section that
+//     serializes concurrent appends. `fn` receives { readLastIntegrity, persist }
+//     where readLastIntegrity() -> the last record's auditIntegrity (or null) and
+//     persist(record) durably appends the built record. transaction() returns
+//     fn's return value.
+//   async ready() — OPTIONAL health/writability probe returning { ok, reason? };
+//     the sink falls back to { ok: true } when the store omits it.
+//
+// The store deliberately knows NOTHING about anchoring, sanitization, or the
+// chain math — those stay core-owned in createAuditSink so a non-core store can
+// never fork or weaken the chain.
+
+// createFileAuditStore implements the store contract over the CURRENT JSONL
+// mechanism: a `${path}.lock` exclusive section wrapping mkdir + the critical
+// section, a tail-read for the previous integrity, and an appendFile persist.
+// The on-disk bytes are identical to the pre-seam sink.
+export function createFileAuditStore({ path }) {
   if (!path) {
-    throw new Error("JSONL audit sink requires path");
+    throw new Error("file audit store requires path");
+  }
+
+  return {
+    async transaction(fn) {
+      await mkdir(dirname(path), { recursive: true });
+      return withFileLock(`${path}.lock`, () => fn({
+        readLastIntegrity: () => readLastIntegrity(path),
+        persist: (record) => appendFile(path, `${JSON.stringify(record)}\n`, "utf8")
+      }));
+    },
+
+    // WS4-A readiness probe: a CHEAP writability check used by /__haechi/ready.
+    // A security gateway that cannot append to its audit log is NOT ready
+    // (fail-closed), so this confirms the audit directory exists and is writable
+    // WITHOUT writing an event (no audit-chain side effect). It returns the bare
+    // boolean and an enum reason — never a path value or any payload/PII.
+    async ready() {
+      try {
+        const dir = dirname(path);
+        await mkdir(dir, { recursive: true });
+        await access(dir, fsConstants.W_OK);
+        // If the audit file already exists, confirm it is writable too.
+        try {
+          await access(path, fsConstants.W_OK);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            return { ok: false, reason: "audit_file_not_writable" };
+          }
+        }
+        return { ok: true };
+      } catch {
+        return { ok: false, reason: "audit_dir_not_writable" };
+      }
+    }
+  };
+}
+
+// createAuditSink holds the SECURITY-CRITICAL, core-owned logic: writeQueue
+// serialization, sanitizeAudit, the sha256 chain build, the anchor stream, and
+// the capabilities object. The store only supplies the exclusive
+// read-previous + persist primitive; anchor config never leaks into it.
+export function createAuditSink({ store, anchor = null }) {
+  if (!store || typeof store.transaction !== "function") {
+    throw new Error("audit sink requires a store with a transaction(fn) method");
   }
   const anchorMode = anchor?.mode ?? "none";
   const anchorPath = anchor?.path ?? null;
@@ -81,44 +145,41 @@ export function createJsonlAuditSink({ path, anchor = null }) {
       integrity: anchorMode === "none" ? "sha256-hash-chain" : "sha256-hash-chain+anchor"
     },
     async record(event) {
-      const write = writeQueue.then(async () => {
-        await mkdir(dirname(path), { recursive: true });
-        await withFileLock(`${path}.lock`, async () => {
-          const record = await buildIntegrityRecord(path, sanitizeAudit(event));
-          await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
-          await writeAnchor(record);
-        });
-      });
+      // The writeQueue serializes record() calls on this sink, and the store's
+      // transaction() adds the exclusive critical section; together they keep
+      // the chain strictly sequential and never forked under concurrency.
+      const write = writeQueue.then(() => store.transaction(async ({ readLastIntegrity, persist }) => {
+        const record = buildIntegrityRecord(await readLastIntegrity(), sanitizeAudit(event));
+        await persist(record);
+        await writeAnchor(record);
+        return record;
+      }));
       writeQueue = write.catch(() => {});
       await write;
     },
 
-    // WS4-A readiness probe: a CHEAP writability check used by /__haechi/ready.
-    // A security gateway that cannot append to its audit log is NOT ready
-    // (fail-closed), so this confirms the audit directory exists and is writable
-    // WITHOUT writing an event (no audit-chain side effect). It returns the bare
-    // boolean and an enum reason — never a path value or any payload/PII.
     async ready() {
-      try {
-        const dir = dirname(path);
-        await mkdir(dir, { recursive: true });
-        await access(dir, fsConstants.W_OK);
-        // If the audit file already exists, confirm it is writable too.
-        try {
-          await access(path, fsConstants.W_OK);
-        } catch (error) {
-          if (error.code !== "ENOENT") {
-            return { ok: false, reason: "audit_file_not_writable" };
-          }
-        }
-        return { ok: true };
-      } catch {
-        return { ok: false, reason: "audit_dir_not_writable" };
+      // Delegate to the store's writability probe; a store that omits it is
+      // treated as ready (the chain math has no readiness side effect of its own).
+      if (typeof store.ready === "function") {
+        return store.ready();
       }
+      return { ok: true };
     }
   };
 }
 
+// Thin back-compat wrapper: the original file-backed sink is now createAuditSink
+// over createFileAuditStore. Its returned shape (id, version, capabilities,
+// record, ready) and on-disk bytes are unchanged, so existing call sites
+// (runtime.mjs injection, tests) keep working untouched.
+export function createJsonlAuditSink({ path, anchor = null }) {
+  if (!path) {
+    throw new Error("JSONL audit sink requires path");
+  }
+  return createAuditSink({ store: createFileAuditStore({ path }), anchor });
+}
+
 export async function readAuditSummary(path) {
   const summary = {
     events: 0,
@@ -272,8 +333,13 @@ async function readAnchors(anchorPath) {
   return { bySequence, lastSequence };
 }
 
-async function buildIntegrityRecord(path, event) {
-  const previous = await readLastIntegrity(path);
+// PURE chain math: given the previous record's auditIntegrity (or null) and a
+// sanitized event, deterministically computes the next chained record. No fs,
+// no IO — the store supplies `previousIntegrity` (via its read-previous
+// primitive) so the SAME computation backs a file or a shared store. Exported
+// for store/satellite tests.
+export function buildIntegrityRecord(previousIntegrity, event) {
+  const previous = previousIntegrity ?? null;
   const sequence = previous ? previous.sequence + 1 : 1;
   const unsigned = {
     ...event,

package/packages/cli/bin/haechi.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { readFile, stat } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createPrivateKey, generateKeyPairSync } from "node:crypto";
 import { readAuditSummary, verifyAuditChain } from "../../audit/index.mjs";
 import { DEFAULT_PROXY_PORT, HAECHI_VERSION, createHaechiProxy } from "../../proxy/index.mjs";
 import { signPolicyBundleFile, verifyPolicyBundleFile } from "../../policy-bundle/index.mjs";
-import { validatePluginManifestFile } from "../../plugin/index.mjs";
+import { PluginLoadError, signPluginManifest, validatePluginManifestFile, verifySignedPlugin } from "../../plugin/index.mjs";
 import { runMcpStdioFilter, wrapMcpChild } from "../../mcp-stdio/index.mjs";
 import { addToken, listTokens, revokeToken } from "../../auth/index.mjs";
 import { createLocalCryptoProvider } from "../../crypto/index.mjs";
@@ -51,6 +53,15 @@ try {
     case "plugin-validate":
       await pluginValidateCommand(argv);
       break;
+    case "plugin-keygen":
+      await pluginKeygenCommand(argv);
+      break;
+    case "plugin-sign":
+      await pluginSignCommand(argv);
+      break;
+    case "plugin-verify":
+      await pluginVerifyCommand(argv);
+      break;
     case "mcp-stdio":
       await mcpStdioCommand(argv);
       break;
@@ -472,6 +483,251 @@ async function pluginValidateCommand(argv) {
   }
 }
 
+// plugin-keygen — generate an Ed25519 keypair for signing plugin envelopes. The
+// PRIVATE key is written PKCS8 PEM at 0600 (operator-readable only); the PUBLIC
+// key is written SPKI PEM (this is the trust anchor an operator pastes into
+// auth.plugin.trustAnchors). The JSON output carries ONLY non-secret fields plus
+// the PATH to the private key — never the private key material itself.
+async function pluginKeygenCommand(argv) {
+  const options = parseOptions(argv);
+  const keyId = typeof options["key-id"] === "string" ? options["key-id"] : "haechi-plugin-signer";
+  const outDir = typeof options["out-dir"] === "string" ? options["out-dir"] : ".";
+
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
+
+  const privateKeyPath = join(outDir, `${keyId}.key`);
+  const publicKeyPath = join(outDir, `${keyId}.pub`);
+
+  await mkdir(outDir, { recursive: true });
+  // Restrictive mode on the private key: written 0600 so it is not group/world
+  // readable. (mkdir above is best-effort for "." which always exists.)
+  await writeFile(privateKeyPath, privateKeyPem, { mode: 0o600 });
+  await writeFile(publicKeyPath, publicKeyPem);
+
+  writeJson({
+    ok: true,
+    command: "plugin-keygen",
+    keyId,
+    privateKeyPath,
+    publicKeyPath,
+    publicKeyPem
+  });
+}
+
+// plugin-sign — Ed25519-sign a plugin envelope. The entry bytes are read as RAW
+// bytes (no transcoding) so entrySha256 binds the exact on-disk plugin source.
+// The private key is read from a FILE (never from argv — a key on the command
+// line leaks into process args / shell history). Output is the signed envelope
+// JSON; the JSON status print never includes private material.
+async function pluginSignCommand(argv) {
+  const [entryPath, ...rest] = argv;
+  if (!entryPath || entryPath.startsWith("--")) {
+    throw new Error("plugin-sign requires an entry file path");
+  }
+  const options = parseOptions(rest);
+
+  const required = {
+    key: "--key <private-key.pem>",
+    "signer-key-id": "--signer-key-id <id>",
+    "plugin-id": "--plugin-id <id>",
+    kind: "--kind <kind>",
+    "plugin-version": "--plugin-version <v>",
+    "core-range": "--core-range <range>"
+  };
+  for (const [flag, usage] of Object.entries(required)) {
+    if (typeof options[flag] !== "string" || options[flag].length === 0) {
+      throw new Error(`plugin-sign requires ${usage}`);
+    }
+  }
+
+  // Read the EXACT entry bytes (Buffer, no utf8 transcoding) so the signed
+  // entrySha256 binds the real source.
+  const entryBytes = await readFile(entryPath);
+  // Read the private key from the file, not from argv.
+  const privateKey = createPrivateKey(await readFile(options.key, "utf8"));
+
+  const capabilities = await parseCapabilitiesOption(options.capabilities);
+  const notBefore = parseOptionalEpochMs(options["not-before"], "--not-before");
+  const notAfter = parseOptionalEpochMs(options["not-after"], "--not-after");
+
+  const pluginId = options["plugin-id"];
+  const signed = signPluginManifest(
+    {
+      pluginId,
+      kind: options.kind,
+      version: options["plugin-version"],
+      capabilities,
+      coreVersionRange: options["core-range"],
+      entryBytes,
+      notBefore,
+      notAfter
+    },
+    privateKey,
+    options["signer-key-id"]
+  );
+
+  const outPath = typeof options.out === "string" ? options.out : `${pluginId}.signed.json`;
+  await writeFile(outPath, `${JSON.stringify(signed, null, 2)}\n`);
+
+  writeJson({
+    ok: true,
+    command: "plugin-sign",
+    outPath,
+    pluginId,
+    signerKeyId: signed.signerKeyId,
+    entrySha256: signed.payload.entrySha256,
+    kind: signed.payload.kind,
+    version: signed.payload.version
+  });
+}
+
+// plugin-verify — verify a signed plugin envelope against the exact entry bytes
+// and operator trust anchors. Anchors come from EITHER an explicit --anchor PEM
+// (+ --anchor-key-id, defaulting to the envelope's signerKeyId) OR a --config
+// file's auth.plugin.trustAnchors. On success prints valid:true; on a
+// PluginLoadError it FAILS CLOSED — the error propagates to main()'s catch, the
+// reason code is printed to stderr, and the process exits non-zero (the gate
+// signal). Never prints private material.
+async function pluginVerifyCommand(argv) {
+  const [signedPath, ...rest] = argv;
+  if (!signedPath || signedPath.startsWith("--")) {
+    throw new Error("plugin-verify requires a signed envelope JSON file path");
+  }
+  const options = parseOptions(rest);
+  if (typeof options.entry !== "string" || options.entry.length === 0) {
+    throw new Error("plugin-verify requires --entry <entry-file>");
+  }
+
+  const signed = JSON.parse(await readFile(signedPath, "utf8"));
+  const entryBytes = await readFile(options.entry);
+
+  const trustAnchors = await resolvePluginTrustAnchors(options, signed);
+
+  const coreVersion = typeof options["core-version"] === "string" ? options["core-version"] : null;
+  const pin = typeof options.pin === "string" ? { entrySha256: options.pin } : null;
+
+  // --allow-capability <name> (repeatable) mirrors the OPERATOR capability
+  // allowlist that createRuntime passes at load time. It is REQUIRED to verify an
+  // authProvider envelope (core mandates such a plugin declare readsCredentials,
+  // which is not allowlisted by default) — without it, plugin-verify can only
+  // confirm a no-capability plugin. A bare flag (no value) is ignored.
+  const rawAllow = options["allow-capability"];
+  const allowCapabilities = (Array.isArray(rawAllow) ? rawAllow : [rawAllow])
+    .filter((value) => typeof value === "string" && value.length > 0);
+
+  // verifySignedPlugin throws a PluginLoadError on any refusal. We surface the
+  // stable .reason CODE (the gate signal) in the error message and re-throw so
+  // main()'s catch prints it and sets a non-zero exit code. A non-zero exit +
+  // the reason code is what a caller branches on (never a free-text message).
+  let payload;
+  try {
+    payload = verifySignedPlugin({
+      signed,
+      entryBytes,
+      trustAnchors,
+      coreVersion,
+      pin,
+      allowCapabilities
+    });
+  } catch (error) {
+    if (error instanceof PluginLoadError) {
+      throw new Error(`plugin-verify refused: ${error.reason} (${error.message})`);
+    }
+    throw error;
+  }
+
+  writeJson({
+    ok: true,
+    command: "plugin-verify",
+    valid: true,
+    pluginId: payload.pluginId,
+    signerKeyId: signed.signerKeyId,
+    entrySha256: payload.entrySha256
+  });
+}
+
+// Resolve plugin trust anchors for plugin-verify. Precedence: an explicit
+// --anchor PEM file (keyed by --anchor-key-id, defaulting to the envelope's
+// signerKeyId) wins; otherwise --config supplies auth.plugin.trustAnchors. The
+// config is read as RAW JSON (not normalizeConfig) so verifying an envelope does
+// not require a full auth.provider:"plugin" config — only the anchors matter.
+async function resolvePluginTrustAnchors(options, signed) {
+  if (typeof options.anchor === "string" && options.anchor.length > 0) {
+    const publicKeyPem = await readFile(options.anchor, "utf8");
+    const keyId = typeof options["anchor-key-id"] === "string" && options["anchor-key-id"].length > 0
+      ? options["anchor-key-id"]
+      : signed?.signerKeyId;
+    if (typeof keyId !== "string" || keyId.length === 0) {
+      throw new Error("plugin-verify --anchor requires --anchor-key-id (or a signerKeyId in the envelope)");
+    }
+    return { [keyId]: publicKeyPem };
+  }
+
+  if (typeof options.config === "string" && options.config.length > 0) {
+    const raw = JSON.parse(await readFile(options.config, "utf8"));
+    const anchors = raw?.auth?.plugin?.trustAnchors;
+    if (Array.isArray(anchors)) {
+      const map = {};
+      for (const anchor of anchors) {
+        if (!anchor || typeof anchor !== "object" || typeof anchor.keyId !== "string" || anchor.publicKey == null) {
+          throw new Error("each auth.plugin.trustAnchors entry must be { keyId, publicKey }");
+        }
+        map[anchor.keyId] = anchor.publicKey;
+      }
+      if (Object.keys(map).length === 0) {
+        throw new Error("auth.plugin.trustAnchors in --config is empty");
+      }
+      return map;
+    }
+    if (anchors && typeof anchors === "object") {
+      if (Object.keys(anchors).length === 0) {
+        throw new Error("auth.plugin.trustAnchors in --config is empty");
+      }
+      return anchors;
+    }
+    throw new Error("--config has no auth.plugin.trustAnchors to verify against");
+  }
+
+  throw new Error("plugin-verify requires either --anchor <public-key.pem> or --config <haechi.config.json>");
+}
+
+// Parse the --capabilities option: inline JSON, or @file pointing at a JSON
+// file. Defaults to {} (an empty capability set). Must resolve to a plain
+// object; anything else fails closed.
+async function parseCapabilitiesOption(value) {
+  if (value === undefined || value === true) {
+    return {};
+  }
+  if (typeof value !== "string") {
+    throw new Error("--capabilities must be inline JSON or @file");
+  }
+  const text = value.startsWith("@") ? await readFile(value.slice(1), "utf8") : value;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`--capabilities is not valid JSON: ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--capabilities must be a JSON object");
+  }
+  return parsed;
+}
+
+// Parse an optional epoch-ms flag value. Absent -> undefined (the signer treats
+// it as null/unbounded). A present value must be an integer string.
+function parseOptionalEpochMs(value, flag) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string" || !/^-?\d+$/.test(value.trim())) {
+    throw new Error(`${flag} must be an integer epoch-ms value`);
+  }
+  return Number(value);
+}
+
 async function authCommand(argv) {
   const [sub, ...rest] = argv;
   const options = parseOptions(rest);
@@ -759,6 +1015,21 @@ const COMMAND_HELP = {
     usage: "haechi plugin-validate <plugin-manifest.json>",
     summary: "Validate a plugin manifest (manifest-only; dynamic runtime is rejected)."
   },
+  "plugin-keygen": {
+    usage: "haechi plugin-keygen [--key-id haechi-plugin-signer] [--out-dir .]",
+    summary: "Generate an Ed25519 plugin-signing keypair.",
+    detail: "Writes the PKCS8-PEM private key to <out-dir>/<keyId>.key (0600) and the SPKI-PEM public key to <out-dir>/<keyId>.pub. The public key is the trust anchor an operator pastes into auth.plugin.trustAnchors. The private key is never printed — only its path."
+  },
+  "plugin-sign": {
+    usage: "haechi plugin-sign <entry-file> --key <private-key.pem> --signer-key-id <id> --plugin-id <id> --kind <kind> --plugin-version <v> --core-range <range> [--capabilities <json|@file>] [--not-before <ms>] [--not-after <ms>] [--out <signed.json>]",
+    summary: "Ed25519-sign a plugin envelope binding the exact entry bytes.",
+    detail: "Reads the entry file as raw bytes (entrySha256 binds the real source) and the private key from the --key FILE (never argv). Writes the signed envelope to --out (default <plugin-id>.signed.json). Capabilities default to {}; provide inline JSON or @file. The private key is never printed."
+  },
+  "plugin-verify": {
+    usage: "haechi plugin-verify <signed.json> --entry <entry-file> [--anchor <public-key.pem> --anchor-key-id <id>] [--config haechi.config.json] [--core-version <v>] [--pin <entrySha256>] [--allow-capability <name>]...",
+    summary: "Verify a signed plugin envelope; fail closed on any refusal.",
+    detail: "Resolves trust anchors from --anchor (with --anchor-key-id, default the envelope signerKeyId) or from --config auth.plugin.trustAnchors. Pass --allow-capability <name> (repeatable) to allowlist each declared capability — REQUIRED to verify an authProvider envelope (it must declare readsCredentials, which is not allowlisted by default). On success prints valid:true; on any refusal it exits non-zero with the PluginLoadError reason (the gate signal)."
+  },
   "mcp-stdio": {
     usage: "haechi mcp-stdio [--config haechi.config.json]",
     summary: "Filter MCP JSON-RPC traffic on stdin/stdout (one direction)."
@@ -790,7 +1061,8 @@ function printHelp(topic) {
     "init", "protect", "report", "status", "audit-verify", "proxy",
     "policy-sign", "policy-verify",
     "token-reveal", "token-purge", "token-export",
-    "plugin-validate", "mcp-stdio", "mcp-wrap", "auth", "config"
+    "plugin-validate", "plugin-keygen", "plugin-sign", "plugin-verify",
+    "mcp-stdio", "mcp-wrap", "auth", "config"
   ];
   const lines = order.map((name) => `  ${name.padEnd(16)}${COMMAND_HELP[name].summary}`);
   console.log(`Haechi — self-hosted AI context enforcement