trustdex 0.5.0 → 0.5.1

package/README.ko.md

@@ -0,0 +1,369 @@
+# TrustDex
+
+<p align="right">
+  <a href="./README.md">English</a> | <strong>한국어</strong>
+</p>
+
+[![CI](https://github.com/grigent/trustdex/actions/workflows/ci.yml/badge.svg)](https://github.com/grigent/trustdex/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/grigent/trustdex/actions/workflows/codeql.yml/badge.svg)](https://github.com/grigent/trustdex/actions/workflows/codeql.yml)
+[![Release](https://img.shields.io/github/v/release/grigent/trustdex)](https://github.com/grigent/trustdex/releases)
+[![npm](https://img.shields.io/npm/v/trustdex)](https://www.npmjs.com/package/trustdex)
+[![License](https://img.shields.io/github/license/grigent/trustdex)](LICENSE)
+
+**AI 에이전트 도구를 위한 로컬 우선 신뢰 및 출처 검증 게이트입니다.**
+
+TrustDex는 AI 에이전트가 어떤 MCP 서버, 스킬, 플러그인을 사용하도록 허용할지 판단하는 데 도움을 줍니다. 발견된 모든 확장을 신뢰하는 대신, TrustDex는 관찰 가능한 증거를 평가하여 다음 세 가지 결과 중 하나를 반환합니다.
+
+- **ALLOW** - 명시적인 신뢰 정책과 일치
+- **ASK** - 사람의 검토가 필요
+- **BLOCK** - 현재 정책에서 신뢰되지 않음
+
+> TrustDex는 보안 관련 인프라이며, 악성 코드 스캐너, 샌드박스 또는 인증 서비스가 아닙니다. ALLOW 결과는 검사된 증거가 사용자의 정책과 일치한다는 의미일 뿐입니다.
+
+> **프로젝트 상태:** TrustDex는 초기 단계이며 파일럿 사용자를 찾고 있습니다. 보안 경계가 문서화되어 있고, 지원되는 Node.js 버전에서 변경 사항을 테스트하지만, 1.0 이전에는 호환성이 계속 변경될 수 있습니다. [로드맵](docs/ROADMAP.ko.md), [거버넌스](GOVERNANCE.ko.md), [지원 가이드](SUPPORT.ko.md)를 참고하세요.
+
+## TrustDex가 필요한 이유
+
+AI 에이전트는 자격 증명을 받거나, 파일에 접근하거나, 원격 서비스에 연결하거나, 로컬 프로그램을 실행할 수 있는 서드파티 MCP 서버, 스킬, 플러그인에 점점 더 의존하고 있습니다. 패키지를 설치할 수 있다는 사실만으로 해당 패키지를 에이전트가 자동으로 사용할 수 있어서는 안 됩니다.
+
+TrustDex는 **도구가 노출되기 전**에 의사 결정 계층을 추가합니다.
+
+```text
+사용자 요청
+    |
+    v
+AI 에이전트 / Codex
+    |
+    v
+TrustDex 정책 + 출처 검증 게이트
+    |-- ALLOW -> 도구 노출 가능
+    |-- ASK   -> 사람의 검토 필요
+    `-- BLOCK -> 도구를 사용할 수 없도록 유지
+```
+
+TrustDex는 이름, 스타 수 또는 브랜딩만으로 "공식" 여부를 추론하지 않습니다. 출처는 명시적이고 검토 가능한 증거로 확인해야 합니다.
+
+## 현재 코드에서 지원하는 기능
+
+- 설정을 업로드하지 않고 로컬에서 MCP 서버 항목 검사
+- 패키지, 원격, 로컬 및 알 수 없는 소스 구분
+- 유동 버전, 실행 시 설치하는 런처, 셸 실행, 파일 시스템 경로로 보이는 인수, 비밀 정보로 보이는 환경 변수 이름, 원격 엔드포인트 등 신뢰 관련 신호 감지
+- `SKILL.md` 파일 및 플러그인 매니페스트에서 신뢰 관련 메타데이터와 지침 검사
+- 기본 제공 `strict`, `official-first`, `development` 정책 팩 적용
+- 로컬 신뢰 저장소에서 명시적인 게시자/출처 주장 연결
+- **ALLOW / ASK / BLOCK** 결정 출력
+- 정책에서 승인된 도구만 포함하는 필터링된 MCP 설정 생성
+- 스냅샷 생성 및 소스, 출처, 결정, 기능 드리프트 감지
+- 검토된 스냅샷에 대한 Ed25519 서명 신뢰 기록 생성
+- CI에서 GitHub Action으로 실행
+- 비밀 값을 저장하지 않고 MCP 항목, 스킬 및 플러그인 매니페스트의 지문 생성
+- Codex `config.toml`의 MCP 섹션 검사 및 필터링
+- 명시적인 전송 방식 검증과 헤더 실행 제어를 포함해 Claude Code MCP JSON 검사 및 필터링
+- GitHub, npm 및 공식 MCP Registry를 대상으로 명시적인 출처 조회 수행
+- 최신 GitHub 릴리스 태그/커밋에 GitHub 검증 서명이 있는지 확인
+- 서명된 검토 번들을 생성하고 신뢰 관련 상태가 변경되면 자동으로 재검토 요구
+- 보고서의 원격 엔드포인트 세부 정보에서 자격 증명, 경로 및 쿼리 값 제거
+- 엄격한 정책에서 URL에 포함된 자격 증명과 안전하지 않은 원격 전송 차단
+- 여러 호스트에서 Windows 실행 파일 경로와 명령 래퍼를 일관되게 인식
+- 지원하지 않는 Codex MCP 키와 하위 섹션을 발견하면 안전하게 실패
+- 사용자가 제공한 패키지 바이트를 npm SRI 또는 MCP Registry SHA-256 메타데이터와 대조해 검증
+- 무결성 기반 신뢰 증거를 설정된 패키지 버전에 연결하고 불일치 차단
+
+## 호환성
+
+TrustDex에는 Node.js 20 이상이 필요합니다. CI는 Ubuntu에서 Node.js 20과 22로 전체 테스트 및 게이트 워크플로를 실행하고, 최신 Windows 및 macOS 러너에서는 Node.js 22로 실행합니다. 체크아웃된 복합 GitHub Action에는 전용 엔드투엔드 스모크 테스트가 있습니다.
+
+## 빠른 시작
+
+Node.js 20 이상이 필요합니다.
+
+npm에서 직접 실행:
+
+```bash
+npx trustdex@0.5.0 --help
+npx trustdex@0.5.0 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
+```
+
+또는 소스 체크아웃에서 작업:
+
+```bash
+git clone https://github.com/grigent/trustdex.git
+cd trustdex
+npm test
+npm run check
+
+node ./bin/trustdex.mjs inspect ./examples/mcp.json \
+  --pack strict \
+  --policy ./examples/trustdex.policy.json
+```
+
+예제에는 의도적으로 알 수 없는 서버가 포함되어 있으므로 엄격한 검사는 0이 아닌 종료 코드를 반환합니다.
+
+검사의 종료 코드:
+
+- `0` - 모든 항목 허용
+- `1` - 하나 이상의 항목에 검토 필요
+- `2` - 하나 이상의 항목이 차단되었거나 명령 실패
+
+## 재현 가능한 방어적 연구
+
+TrustDex에는 서드파티 서비스에 연결하거나 실행하지 않고 정책 경계를 테스트할 수 있는 비활성 적대적 벤치마크가 포함되어 있습니다. 픽스처는 예약된 `.invalid` 도메인, 자리표시자 자격 증명 및 설정 데이터만 사용합니다. TrustDex는 이를 정적으로 검사하며 나열된 서버를 실행하지 않습니다.
+
+```bash
+npm run test:research
+
+node ./bin/trustdex.mjs inspect \
+  ./examples/adversarial/mcp-config.json \
+  --pack strict \
+  --policy ./examples/adversarial/policy.json
+```
+
+직접 검사는 의도적으로 종료 코드 `2`를 반환합니다. 체크인된 기대 결과는 `ALLOW` 1개, `ASK` 1개, `BLOCK` 5개입니다. 자동화된 테스트는 자리표시자 비밀 값이 결과에 나타나지 않는지, 비밀 정보를 포함하는 새 환경 변수가 이전 검토 상태를 무효화하는지도 확인합니다.
+
+[방어적 보안 연구 정책](docs/SECURITY_RESEARCH.ko.md), [평가 기록](docs/EVALUATION.ko.md), [적대적 픽스처 가이드](examples/adversarial/README.ko.md)를 참고하세요.
+
+## 기본 제공 정책 팩
+
+```bash
+node ./bin/trustdex.mjs policy strict
+node ./bin/trustdex.mjs policy official-first
+node ./bin/trustdex.mjs policy development
+```
+
+`official-first`는 소위 공식 공급업체의 하드코딩된 목록을 유지하지 **않습니다**. 신뢰 저장소에 명시적인 출처 증거가 있는 소스(또는 사용자가 명시적으로 허용 목록에 추가한 소스)만 허용하며, 알 수 없는 서드파티 소스는 기본적으로 차단합니다.
+
+[신뢰 저장소와 출처](docs/TRUST_STORE.ko.md)를 참고하세요.
+
+## 에이전트가 사용하기 전에 도구 필터링
+
+```bash
+node ./bin/trustdex.mjs gate ./examples/mcp.json \
+  --pack official-first \
+  --out .trustdex/gated-mcp.json
+```
+
+기본적으로 `ALLOW` 항목만 게이트된 설정에 기록됩니다. `ASK` 항목은 검토될 때까지 제외됩니다.
+
+이것이 TrustDex의 핵심 경계입니다. 에이전트는 검토되지 않은 원본 설정 대신 필터링된 설정을 받습니다.
+
+## 스킬 및 플러그인 검사
+
+```bash
+node ./bin/trustdex.mjs inspect-skill ./path/to/SKILL.md --pack strict
+node ./bin/trustdex.mjs inspect-plugin ./path/to/plugin.json --pack strict
+```
+
+이 검사는 관찰 가능한 신뢰 신호를 드러냅니다. 확장이 안전하다는 것을 증명하지는 않습니다.
+
+## Codex config.toml
+
+현재 Codex 클라이언트는 `config.toml`의 `[mcp_servers.<name>]` 테이블 아래에 MCP 설정을 저장합니다. TrustDex는 해당 MCP 섹션을 위한 전용 어댑터를 제공합니다.
+
+```bash
+node ./bin/trustdex.mjs inspect-codex ./examples/codex.config.toml --pack strict
+
+node ./bin/trustdex.mjs gate-codex ./examples/codex.config.toml \
+  --pack strict \
+  --out .trustdex/gated-codex.toml
+```
+
+게이트는 승인되지 않은 MCP 섹션을 제거하면서 관련 없는 TOML 섹션은 유지합니다. TrustDex는 필요한 MCP 관련 TOML 구성만 의도적으로 파싱합니다. 지원하지 않는 MCP 구문은 조용히 신뢰하지 않고 실패합니다.
+
+단계별 게이트 워크플로와 이 프로젝트가 자체 검토 과정에서 Codex를 사용하는 방법은 [Codex에서 TrustDex 사용하기](docs/CODEX.ko.md)를 참고하세요.
+
+## Claude Code MCP 설정
+
+Claude Code는 `mcpServers` JSON 형식을 사용합니다. 전송 방식 변경, 인증 헤더 메타데이터 및 헤더 도우미 명령이 검사와 서명된 검토에 포함되도록 Claude 전용 명령을 사용하세요.
+
+```bash
+node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict
+node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --out .trustdex/claude-mcp.json
+claude --strict-mcp-config --mcp-config .trustdex/claude-mcp.json
+```
+
+Claude를 시작하기 전에 게이트의 결과를 확인하세요. 기본적으로 `ALLOW` 항목만 노출되며, `ASK` 항목에는 검토가 필요합니다. 어댑터는 검사할 수 없는 설정을 조용히 신뢰하지 않고 거부합니다. 이 명령은 npm 0.5.0 이상과 소스 체크아웃에서 사용할 수 있습니다. 게시된 CLI를 실행하려면 `node ./bin/trustdex.mjs` 대신 `npx trustdex@0.5.0`을 사용하세요.
+
+지원되는 설정, PowerShell 오류 처리, 서명된 검토 및 Claude Desktop 워크플로는 [Claude에서 TrustDex 사용하기](docs/CLAUDE.ko.md)를 참고하세요.
+
+## 온라인 출처 관찰
+
+일반 검사는 계속 로컬에서만 수행됩니다. 다음 명령은 명시적으로 실행할 때만 네트워크 조회를 수행합니다.
+
+```bash
+node ./bin/trustdex.mjs provenance github modelcontextprotocol/servers
+node ./bin/trustdex.mjs provenance github-release owner/repository
+node ./bin/trustdex.mjs provenance npm @scope/package
+node ./bin/trustdex.mjs provenance mcp io.github.user/server
+```
+
+조회 결과는 **증거이지 신뢰가 아닙니다**. 증거를 로컬 신뢰 저장소의 주장으로 전환하려면 사용자가 게시자를 명시적으로 지정해야 합니다.
+
+```bash
+node ./bin/trustdex.mjs trust-source mcp io.github.user/server \
+  --publisher "Example Publisher" \
+  --out ./trust-store.json
+```
+
+`github-release`의 경우 GitHub가 릴리스 태그 또는 대상 커밋 서명을 검증된 것으로 보고하지 않으면 TrustDex는 신뢰 주장을 생성하지 않습니다.
+
+### 정확한 패키지 바이트 검증
+
+레지스트리 메타데이터는 예상 다이제스트를 식별할 수 있지만, 메타데이터만으로 다운로드한 파일이 해당 값과 일치한다는 것을 증명할 수는 없습니다. 검토한 정확한 패키지 아카이브 또는 아티팩트를 제공하세요.
+
+```bash
+node ./bin/trustdex.mjs trust-source npm @scope/package \
+  --publisher "Example Publisher" \
+  --artifact ./scope-package-1.2.3.tgz \
+  --out ./trust-store.json
+
+node ./bin/trustdex.mjs trust-source mcp io.github.user/server \
+  --publisher "Example Publisher" \
+  --artifact ./downloaded-package \
+  --out ./trust-store.json
+```
+
+TrustDex는 파일을 로컬에서 읽고 해당 바이트를 npm SRI 메타데이터 또는 MCP Registry SHA-256 다이제스트와 비교합니다. 아티팩트를 다운로드하거나 실행하지 않습니다. 무결성 기반 증거는 특정 버전에 연결됩니다. 설정된 패키지 버전이 다르면 `artifact-version-mismatch`가 발생하며 차단됩니다.
+
+## 출처 신뢰 저장소
+
+예시:
+
+```json
+{
+  "version": 1,
+  "claims": [
+    {
+      "type": "package",
+      "subject": "example-mcp-server",
+      "publisher": "Example Publisher",
+      "status": "verified",
+      "evidence": {
+        "kind": "manual-review",
+        "reference": "https://example.invalid/security-review"
+      }
+    }
+  ]
+}
+```
+
+그런 다음:
+
+```bash
+node ./bin/trustdex.mjs inspect ./mcp.json \
+  --pack official-first \
+  --trust-store ./trust-store.json
+```
+
+여기서 `verified`는 해당 신뢰 저장소에서 관리하는 증거에 따라 검증되었다는 뜻입니다. OpenAI, TrustDex, GitHub, npm 또는 다른 플랫폼이 확장을 인증했다는 의미가 아닙니다.
+
+## 기능 및 출처 드리프트
+
+기준선 저장:
+
+```bash
+node ./bin/trustdex.mjs snapshot ./examples/mcp.json \
+  --pack strict \
+  --out .trustdex/baseline.json
+```
+
+업데이트 후 다른 스냅샷을 저장하고 비교:
+
+```bash
+node ./bin/trustdex.mjs diff .trustdex/baseline.json .trustdex/current.json
+```
+
+TrustDex는 새로 추가된 신호, 소스 변경, 출처 변경, 결정 변경, 콘텐츠/설정 지문 변경을 보고합니다.
+
+검토 워크플로에서는 서명 키를 한 번 생성하고 차단되지 않은 설정을 승인합니다.
+
+```bash
+node ./bin/trustdex.mjs keygen \
+  --private .trustdex/private.pem \
+  --public .trustdex/public.pem
+
+node ./bin/trustdex.mjs approve ./examples/mcp.json \
+  --private .trustdex/private.pem \
+  --dir .trustdex/review \
+  --pack development
+```
+
+나중에 해당 서명된 검토를 기준으로 현재 설정을 다시 평가합니다.
+
+```bash
+node ./bin/trustdex.mjs recheck ./examples/mcp.json \
+  --review-dir .trustdex/review \
+  --public .trustdex/public.pem
+```
+
+결과는 `APPROVED`, `NEEDS_REVIEW` 또는 `INVALID`입니다. 지문, 소스, 출처, 신호 또는 정책 관련 변경이 발생하면 이전 상태의 일치가 무효화됩니다.
+
+## 서명된 신뢰 기록
+
+로컬 서명 키 생성:
+
+```bash
+node ./bin/trustdex.mjs keygen \
+  --private .trustdex/trustdex-private.pem \
+  --public .trustdex/trustdex-public.pem
+```
+
+검토된 스냅샷 서명:
+
+```bash
+node ./bin/trustdex.mjs sign .trustdex/baseline.json \
+  --private .trustdex/trustdex-private.pem \
+  --out .trustdex/trust-record.json
+```
+
+나중에 검증:
+
+```bash
+node ./bin/trustdex.mjs verify .trustdex/trust-record.json \
+  --public .trustdex/trustdex-public.pem \
+  --snapshot .trustdex/baseline.json
+```
+
+비공개 키는 절대 커밋하면 안 됩니다.
+
+## GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+
+- uses: grigent/trustdex@v0.5.0
+  with:
+    config: ./mcp.json
+    pack: official-first
+    trust-store: ./trust-store.json
+    output: .trustdex/gated-mcp.json
+```
+
+프로덕션 CI에서는 이동하는 브랜치 대신 검토된 커밋 SHA에 Action을 고정하세요.
+
+## 원칙
+
+1. **로컬 우선.** 비공개 에이전트 설정이 컴퓨터 밖으로 나갈 필요가 없어야 합니다.
+2. **맹목적으로 신뢰하지 않기.** 출처가 없으면 추측으로 ALLOW하지 않고 검토하거나 거부해야 합니다.
+3. **출력에 비밀 값 포함 금지.** 환경 변수 이름은 보고할 수 있지만 값은 보고하지 않습니다.
+4. **드리프트는 중요합니다.** 신뢰 관련 변경이 발생해도 승인이 조용히 유지되어서는 안 됩니다.
+5. **단순한 결과.** 불투명한 위험 점수 대신 ALLOW / ASK / BLOCK을 사용합니다.
+6. **브랜딩보다 증거.** 익숙한 이름만으로 "공식"이라고 추론하지 않습니다.
+7. **공급업체 중립.** 정책 모델은 Codex 및 다른 에이전트 런타임에서도 작동해야 합니다.
+
+## 로드맵
+
+공개 로드맵은 [docs/ROADMAP.ko.md](docs/ROADMAP.ko.md)에서 관리합니다. 단기 작업은 레지스트리 무결성 검증, 재현 가능한 릴리스, 추가 에이전트 런타임 어댑터 및 실제 파일럿 피드백에 중점을 둡니다. 로드맵 항목은 계획이며 약속이 아닙니다.
+
+## 보안
+
+TrustDex는 서드파티 코드가 안전하다는 것을 **증명하지 않으며**, 샌드박싱, 의존성 검사, 코드 검토 또는 최소 권한 자격 증명을 대체하지 않습니다.
+
+[SECURITY.ko.md](SECURITY.ko.md), [docs/THREAT_MODEL.ko.md](docs/THREAT_MODEL.ko.md), [docs/SECURITY_RESEARCH.ko.md](docs/SECURITY_RESEARCH.ko.md), [docs/EVALUATION.ko.md](docs/EVALUATION.ko.md), [docs/TRUST_STORE.ko.md](docs/TRUST_STORE.ko.md)를 참고하세요.
+
+## 기여
+
+기여를 환영합니다. [CONTRIBUTING.ko.md](CONTRIBUTING.ko.md), [GOVERNANCE.ko.md](GOVERNANCE.ko.md), [CODE_OF_CONDUCT.ko.md](CODE_OF_CONDUCT.ko.md), [AGENTS.ko.md](AGENTS.ko.md)를 참고하세요.
+
+## 라이선스
+
+MIT

package/README.md

@@ -1,5 +1,9 @@
 # TrustDex
 
+<p align="right">
+  <strong>English</strong> | <a href="./README.ko.md">한국어</a>
+</p>
+
 [![CI](https://github.com/grigent/trustdex/actions/workflows/ci.yml/badge.svg)](https://github.com/grigent/trustdex/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/grigent/trustdex/actions/workflows/codeql.yml/badge.svg)](https://github.com/grigent/trustdex/actions/workflows/codeql.yml)
 [![Release](https://img.shields.io/github/v/release/grigent/trustdex)](https://github.com/grigent/trustdex/releases)

package/SECURITY.md

@@ -1,5 +1,9 @@
 # Security Policy
 
+<p align="right">
+  <strong>English</strong> | <a href="./SECURITY.ko.md">한국어</a>
+</p>
+
 TrustDex is security-related software, but it is not a sandbox, malware scanner, vulnerability scanner, or certification service. An ALLOW decision means only that the observed evidence matched the selected policy.
 
 ## Supported versions

package/docs/ARCHITECTURE.ko.md

@@ -0,0 +1,47 @@
+# 아키텍처
+
+<p align="right">
+  <a href="./ARCHITECTURE.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 관찰, 정책, 게이트 및 검토 증거를 분리하는 의존성 없는 Node.js CLI입니다.
+
+## 데이터 흐름
+
+1. 어댑터가 MCP JSON 파일, Codex TOML의 제한된 하위 집합, 스킬 또는 플러그인 매니페스트를 읽습니다.
+2. 검사가 소스를 정규화하고 관찰 가능한 신호를 생성합니다. 비밀 값은 보고서에 보관하지 않습니다.
+3. 선택적인 신뢰 저장소 주장이 명시적인 출처 증거를 연결합니다.
+4. 정책 엔진이 ALLOW, ASK 또는 BLOCK을 생성합니다.
+5. 게이트가 승인된 설정만 출력합니다.
+6. 스냅샷과 서명된 신뢰 기록을 통해 이후 드리프트를 검토할 수 있습니다.
+
+게이트가 강제 적용 경계입니다. 보고서만으로는 에이전트가 검토되지 않은 확장을 불러오는 것을 막을 수 없습니다.
+
+## 모듈
+
+| 영역 | 책임 |
+| --- | --- |
+| `src/inspect.mjs` | MCP 소스 분류, 민감 정보 제거, 지문 생성 및 신호 |
+| `src/codex-config.mjs` | 안전하게 실패하는 Codex MCP 전용 파싱 및 섹션 필터링 |
+| `src/extensions.mjs` | 스킬 및 플러그인 매니페스트 검사 |
+| `src/provenance.mjs` | 명시적인 로컬 신뢰 저장소 주장 |
+| `src/provenance-online.mjs` | 사용자가 호출하는 GitHub, npm 및 MCP Registry 관찰과 로컬 아티팩트 다이제스트 검증 |
+| `src/policy.mjs` | 단조로운 정책 평가. 신호는 심각도를 높일 수 있음 |
+| `src/gate.mjs` | 승인된 MCP 항목만 출력 |
+| `src/snapshot.mjs` | 결정론적 신뢰 관련 상태 및 드리프트 |
+| `src/trust-record.mjs` | Ed25519 검토 기록 서명 및 검증 |
+| `src/review.mjs` | 서명된 기준선 비교 |
+
+## 보안 불변 조건
+
+- 검사는 검사 대상 확장을 실행해서는 안 됩니다.
+- 비밀 값은 출력하거나 스냅샷에 저장해서는 안 됩니다.
+- 알 수 없는 증거가 신뢰로 바뀌어서는 안 됩니다.
+- 차단 신호의 심각도를 출처 정보로 낮춰서는 안 됩니다.
+- 지원하지 않는 보안 관련 구문은 안전하게 실패해야 합니다.
+- 네트워크 조회는 명시적으로 수행하며, 관찰은 승인이 아닙니다.
+- ALLOW는 정책 결과이지 안전 인증이 아닙니다.
+
+## 의존성 정책
+
+현재 런타임 코드는 Node.js 기본 제공 기능만 사용합니다. 새로운 의존성을 추가하려면 해당 기능을 플랫폼만으로 합리적으로 구현할 수 없는 이유, 패키지의 유지관리 및 보안 상태, 공급망 경계에 미치는 영향을 설명하는 이슈가 필요합니다.

package/docs/ARCHITECTURE.md

@@ -1,5 +1,9 @@
 # Architecture
 
+<p align="right">
+  <strong>English</strong> | <a href="./ARCHITECTURE.ko.md">한국어</a>
+</p>
+
 TrustDex is a dependency-free Node.js CLI that separates observation, policy, gating, and review evidence.
 
 ## Data flow

package/docs/CLAUDE.ko.md

@@ -0,0 +1,92 @@
+# Claude에서 TrustDex 사용하기
+
+<p align="right">
+  <a href="./CLAUDE.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 Claude Code 또는 Claude Desktop이 MCP JSON을 받기 전에 이를 검사할 수 있습니다. 설정 증거를 로컬에서 평가하고, MCP 서버를 시작하지 않으며, 설정을 업로드하지 않습니다. ALLOW 결정은 증거가 정책과 일치한다는 뜻이며 서버 코드가 안전하다는 것을 증명하지 않습니다.
+
+Claude 전용 명령은 TrustDex 0.5.0 이상에서 사용할 수 있습니다. 게시된 CLI를 실행하려면 아래 예제의 `node ./bin/trustdex.mjs` 대신 `npx trustdex@0.5.0`을 사용하거나, 소스 체크아웃에서 명령을 직접 사용하세요.
+
+## 지원되는 설정
+
+최상위 `mcpServers` 객체가 있는 전용 JSON 파일을 사용하세요.
+
+```json
+{
+  "mcpServers": {
+    "reviewed-tools": {
+      "type": "http",
+      "url": "https://your-reviewed-server.example/mcp"
+    }
+  }
+}
+```
+
+위 URL은 설명용입니다. 직접 검토한 서버와 신뢰 정책을 설정하세요.
+
+지원되는 서버 필드:
+
+| 전송 방식 | 필드 |
+| --- | --- |
+| `stdio`(`type`을 생략한 경우의 기본값이기도 함) | `type`, `command`, `args`, `env` |
+| `http` 또는 `sse` | `type`, `url`, `headers`, `headersHelper` |
+
+원격 항목에는 명시적인 `type`이 필요합니다. 명령 인수와 환경/헤더 값은 문자열이어야 합니다. 알 수 없는 루트/서버 필드, 다른 전송 방식, 잘못된 항목, 해석되지 않은 명령/인수/엔드포인트 변수, 자격 증명·쿼리 매개변수·프래그먼트가 포함된 URL은 안전하게 실패합니다. 이는 명시적인 검사 구현이 마련될 때까지 사용자 지정 `oauth`, `alwaysLoad`, WebSocket 설정 및 향후 제어 기능을 의도적으로 제외합니다. 일반적인 서버 관리형 OAuth에는 `oauth` 필드가 필요 없으며 Claude가 계속 책임집니다.
+
+인증 헤더는 `static-http-headers` 및/또는 `env-http-headers` 신호를 추가합니다. 기본 제공 팩에서는 이에 대한 검토를 요구합니다. `headersHelper`는 `header-helper-command`를 추가하며, Claude가 셸에서 실행하므로 기본 제공 팩에서는 이를 차단합니다. TrustDex는 도우미를 절대 실행하지 않습니다.
+
+지문에는 전송 방식, 헤더 이름, 참조된 환경 변수 이름 및 도우미 존재 여부가 포함됩니다. 헤더/변수 값, 기본값 및 도우미 명령 텍스트는 제외됩니다. 자격 증명 값만 교체해도 검토는 무효화되지 않지만 헤더 이름이나 환경 변수 참조를 변경하면 무효화됩니다. 자격 증명을 명령 인수나 URL 경로에 넣지 마세요. 게이트된 파일은 허용된 원본 항목을 보존하며 입력에 제공된 자격 증명을 포함할 수 있습니다. 로컬에 보관하고 버전 관리에서 제외하세요.
+
+## Claude Code
+
+Claude Code는 `.mcp.json`에서 프로젝트 MCP 설정을 읽습니다. Claude 어댑터로 검사한 뒤 해당 세션에는 생성된 설정만 제공하세요.
+
+소스 체크아웃의 PowerShell에서:
+
+```powershell
+node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json
+
+node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json --out ./.trustdex/claude-mcp.json
+if ($LASTEXITCODE -ne 0) { throw "Resolve the gate error or pending reviews before starting Claude." }
+
+claude --strict-mcp-config --mcp-config ./.trustdex/claude-mcp.json
+```
+
+정책 파일은 공급업체 이름에서 추론한 목록이 아니라 사용자의 명시적인 신뢰 정책입니다. 엄격한 기본값을 사용하려면 `--policy`를 생략하세요. 엄격한 기본값은 알 수 없는 소스를 차단하고 로컬 프로그램에 대해 묻습니다. 기본적으로 게이트에는 ALLOW 항목만 포함됩니다. ASK와 BLOCK 항목은 제외됩니다. 게이트 종료 코드 `1`은 처리되지 않은 ASK 결정, `2`는 실패를 나타냅니다. 게이트가 실패한 뒤 이전 출력 파일로 실행하지 마세요.
+
+`--strict-mcp-config` 플래그가 중요합니다. `--mcp-config`만 사용하면 다른 MCP 소스와 함께 설정이 추가됩니다. 관리형 MCP 설정을 사용하는 조직은 관리 정책의 실제 서버도 확인해야 합니다. 이 워크플로는 Claude의 기본 제공 도구를 게이트하거나 모든 스킬/플러그인을 자동으로 검사하지 않습니다.
+
+생성된 Claude Code 세션 안에서 `/mcp`를 사용해 실제로 로드된 서버를 확인하세요. 설정/단위 테스트가 이 런타임 확인을 대신할 수는 없습니다.
+
+공식 참고 자료: [Claude Code MCP](https://code.claude.com/docs/en/mcp) 및 [CLI 플래그](https://code.claude.com/docs/en/cli-reference).
+
+## 서명된 검토 및 드리프트
+
+검토 워크플로 전체에서 Claude 어댑터를 유지하세요. 일반 MCP 명령은 Claude 전용 제어를 검사하지 않습니다.
+
+```bash
+node ./bin/trustdex.mjs keygen --private .trustdex/private.pem --public .trustdex/public.pem
+node ./bin/trustdex.mjs approve-claude ./.mcp.json --private .trustdex/private.pem --dir .trustdex/claude-review --pack strict --policy ./trustdex.policy.json
+node ./bin/trustdex.mjs recheck-claude ./.mcp.json --review-dir .trustdex/claude-review --public .trustdex/public.pem
+node ./bin/trustdex.mjs snapshot-claude ./.mcp.json --out .trustdex/claude-snapshot.json --pack strict --policy ./trustdex.policy.json
+```
+
+승인은 BLOCK 결정을 거부합니다. ASK 결정에는 명시적인 사람의 검토가 필요합니다. `approve-claude`를 실행하면 해당 검토가 기록되지만 게이트 정책이 자동으로 변경되지는 않습니다. 재검사는 APPROVED, NEEDS_REVIEW 또는 INVALID를 반환합니다. 기존 일반 검토는 지문이 다르므로 Claude 어댑터로 다시 검토해야 합니다. 비공개 키는 절대 커밋하면 안 됩니다.
+
+## Claude Desktop
+
+로컬 stdio MCP 설정에서는 `claude_desktop_config.json`의 `mcpServers` 객체만 전용 입력 파일로 내보내세요. 관련 없는 Desktop 환경설정을 MCP 어댑터에 입력하지 마세요. 해당 파일에 `inspect-claude`와 `gate-claude`를 사용하고 결과를 검토한 뒤, Desktop 설정의 `mcpServers` 섹션만 게이트된 섹션으로 교체하고 Claude Desktop을 다시 시작하세요. 원본 설정의 백업을 보관하세요.
+
+TrustDex는 활성 Desktop 설정을 수정하거나 커넥터를 설치하지 않습니다. Desktop 확장과 계정 수준 원격 커넥터에는 별도 검토가 필요합니다. 이 JSON 게이트가 이를 자동으로 관리하지는 않습니다.
+
+## 비활성 예제
+
+`examples/claude.mcp.json`은 예약된 `.invalid` 도메인, 자리표시자 환경 변수 참조 및 비활성 도우미 문자열을 사용합니다. Claude에서 실행하지 마세요. 정적 검사 전용입니다.
+
+```bash
+node ./bin/trustdex.mjs inspect-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json
+node ./bin/trustdex.mjs gate-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json --out .trustdex/example-claude.json
+```
+
+검사는 의도적으로 `2`로 종료됩니다. 예상 결정은 ALLOW 1개, ASK 1개, BLOCK 2개입니다. 게이트는 `reviewed`만 기록하고 검토가 남아 있으므로 `1`로 종료됩니다.

package/docs/CLAUDE.md

@@ -1,5 +1,9 @@
 # Using TrustDex with Claude
 
+<p align="right">
+  <strong>English</strong> | <a href="./CLAUDE.ko.md">한국어</a>
+</p>
+
 TrustDex can inspect Claude MCP JSON before Claude Code or Claude Desktop receives it.
 It evaluates configuration evidence locally, does not start MCP servers, and does not
 upload your configuration. An ALLOW decision means the evidence matched your policy;

package/docs/CODEX.ko.md

@@ -0,0 +1,77 @@
+# Codex에서 TrustDex 사용하기
+
+<p align="right">
+  <a href="./CODEX.md">English</a> | <strong>한국어</strong>
+</p>
+
+이 가이드는 Codex 클라이언트가 시작할 수 있는 MCP 서버를 게이트하는 방법과 TrustDex 자체를 Codex로 유지관리하는 방법을 설명합니다.
+
+TrustDex는 독립 프로젝트입니다. OpenAI와 제휴하거나 OpenAI의 보증 또는 인증을 받지 않았으며, ALLOW 결정은 OpenAI 또는 TrustDex의 안전 인증이 아닙니다.
+
+## Codex MCP 서버 게이트
+
+Codex 클라이언트는 `config.toml`(기본적으로 `~/.codex/` 아래)의 `[mcp_servers.<name>]` 테이블에서 MCP 서버 정의를 읽습니다. 각 항목은 로컬 프로세스를 시작하거나 제공된 자격 증명으로 원격 엔드포인트에 연결할 수 있습니다.
+
+### 1. 현재 설정 검사
+
+```bash
+npx trustdex@0.4.4 inspect-codex ~/.codex/config.toml --pack strict
+```
+
+이 명령은 파일을 로컬에서 읽으며 네트워크 요청을 하지 않습니다. 출력에는 각 MCP 서버, 소스 유형, 신뢰 신호 및 ALLOW / ASK / BLOCK 결정이 표시됩니다. 환경 변수 이름은 표시될 수 있지만 값은 절대 표시되지 않습니다.
+
+기계가 읽을 수 있는 출력에는 `--json`을 사용하고, 명시적인 게시자 증거를 연결하려면 `--trust-store ./trust-store.json`을 사용하세요([TRUST_STORE.ko.md](TRUST_STORE.ko.md) 참고).
+
+### 2. 게이트된 사본 작성
+
+```bash
+npx trustdex@0.4.4 gate-codex ~/.codex/config.toml \
+  --pack official-first \
+  --trust-store ./trust-store.json \
+  --out ./gated-config.toml
+```
+
+게이트된 파일은 관련 없는 TOML 섹션(모델, 기능, 프로필)을 그대로 유지하며 ALLOW가 아닌 모든 MCP 섹션을 제거합니다. 다른 승인 계층이 있을 때만 사용해야 하는 `--include-ask`를 전달하지 않는 한 `ASK` 항목도 제외됩니다.
+
+사용하기 전에 차이를 검토하세요.
+
+```bash
+diff ~/.codex/config.toml ./gated-config.toml
+```
+
+TrustDex는 `config.toml`을 직접 수정하지 않습니다. 원본 파일을 교체하거나 Codex 설치가 게이트된 사본을 가리키도록 하는 작업은 검토 후 사용자가 명시적으로 수행합니다.
+
+### 3. 변경할 때마다 다시 실행
+
+패키지 버전이 올라가거나, 런처가 바뀌거나, 새 환경 변수가 전달되면 MCP 항목이 변경됩니다. `config.toml`이 변경될 때마다 `inspect-codex`와 `gate-codex`를 다시 실행하세요. dotfiles 저장소의 CI 작업 또는 pre-commit 훅이 적합합니다.
+
+[README](../README.ko.md#기능-및-출처-드리프트)의 서명된 `snapshot`, `approve`, `recheck` 드리프트 워크플로는 현재 MCP JSON만 받습니다. Codex `config.toml`로 확장하는 작업은 [로드맵](ROADMAP.ko.md)에 기록되어 있습니다.
+
+### 안전하게 실패하는 파싱
+
+TrustDex는 Codex MCP 섹션에 사용되는 TOML 구성만 파싱합니다. 지원하지 않는 MCP 키, 중첩 하위 섹션 또는 구문은 건너뛰지 않고 오류로 보고되므로 TrustDex가 완전히 읽을 수 없는 설정이 조용히 ALLOW가 되지 않습니다.
+
+### 스킬 및 플러그인
+
+에이전트 스킬과 플러그인 매니페스트도 같은 방법으로 검사할 수 있습니다.
+
+```bash
+npx trustdex@0.4.4 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.4.4 inspect-plugin ./path/to/plugin.json --pack strict
+```
+
+이 명령은 파이프로 연결된 셸 설치 프로그램, 민감한 경로 참조, 네트워크 URL 및 와일드카드 도구 범위와 같은 관찰 가능한 신호를 보고합니다. 스킬이나 플러그인이 안전하다는 것을 증명하지는 않습니다.
+
+## CI에서 MCP 설정 게이트
+
+에이전트용 MCP 설정을 제공하는 저장소는 모든 풀 리퀘스트에서 [TrustDex GitHub Action](../README.ko.md#github-action)으로 게이트할 수 있습니다. Action을 검토된 커밋 SHA에 고정하세요.
+
+## Codex를 사용한 TrustDex 유지관리
+
+TrustDex는 사용자에게 적용하도록 요청하는 것과 동일한 신뢰 경계를 사용해 Codex를 검토자 및 유지관리 도우미로 사용합니다.
+
+- [AGENTS.ko.md](../AGENTS.ko.md)에는 개발 규칙과 Codex 코드 검토가 TrustDex 풀 리퀘스트에 적용하는 **검토 지침** 섹션이 있습니다. 지침은 프로젝트의 보안 불변 조건(조용한 ALLOW 금지, 출력에 비밀 값 금지, 출처가 차단 신호를 무시하지 못함, 안전하게 실패하는 파싱, Action 고정)을 명시적인 검토 발견 사항으로 전환합니다.
+- Codex 제안은 다른 기여와 동일하게 취급됩니다. 풀 리퀘스트를 거치고, 크로스 플랫폼 CI 매트릭스와 CodeQL을 통과해야 하며, 유지관리자 검토 후에만 병합됩니다.
+- Codex는 릴리스 자격 증명을 보유하지 않습니다. npm 게시는 유지관리자가 트리거하는 `.github/workflows/publish.yml`에서 Sigstore 출처가 포함된 Trusted Publisher OIDC를 사용합니다.
+
+Codex 또는 다른 코딩 에이전트로 기여하는 경우 변경 사항에도 동일한 AGENTS.md 규칙이 적용됩니다.

package/docs/CODEX.md

@@ -1,5 +1,9 @@
 # Using TrustDex with Codex
 
+<p align="right">
+  <strong>English</strong> | <a href="./CODEX.ko.md">한국어</a>
+</p>
+
 This guide covers two things: gating the MCP servers a Codex client may start, and how TrustDex itself is maintained with Codex.
 
 TrustDex is an independent project. It is not affiliated with, endorsed by, or certified by OpenAI, and an ALLOW decision is not an OpenAI or TrustDex safety certification.

package/docs/EVALUATION.ko.md

@@ -0,0 +1,39 @@
+# 방어적 평가
+
+<p align="right">
+  <a href="./EVALUATION.md">English</a> | <strong>한국어</strong>
+</p>
+
+이 평가는 체크인된 적대적 픽스처로 강제되는 동작을 기록합니다. 재현하려면 `npm run test:research`를 실행하세요. 테스트는 로컬 정적 검사만 수행하며 설정된 서버를 실행하거나 연결하지 않습니다.
+
+## MCP 정책 사례
+
+사례는 `examples/adversarial/policy.json`의 작은 오버레이와 함께 기본 제공 `strict` 정책을 사용합니다.
+
+| 사례 | 필수 증거 | 예상 결정 | 이유 |
+| --- | --- | --- | --- |
+| `trusted-pinned-package` | 고정된 패키지, 명시적으로 신뢰된 패키지 이름 | `ALLOW` | 설정된 버전이 고정되어 있고 정책에 명시적인 패키지 신뢰 규칙이 있음 |
+| `floating-version` | `install-on-run`, `unbounded-version` | `BLOCK` | 유동 패키지 버전은 검토 없이 변경될 수 있음 |
+| `shell-launcher` | `shell-execution`, `filesystem-path` | `BLOCK` | 엄격한 정책이 셸 실행을 차단함 |
+| `credential-bearing-url` | `embedded-credentials`, `network-endpoint`, `url-query-parameters` | `BLOCK` | 호스트가 허용 목록에 있어도 URL에 포함된 자격 증명은 차단 신호임 |
+| `insecure-remote` | `insecure-transport`, `network-endpoint` | `BLOCK` | 호스트가 허용 목록에 있어도 평문 전송은 차단 신호임 |
+| `sensitive-local-env` | `filesystem-path`, `secret-env` | `ASK` | 비밀 정보로 보이는 환경 변수 이름을 사용하는 로컬 확장에는 검토가 필요함 |
+| `unknown-remote` | `network-endpoint` | `BLOCK` | 원격 호스트에 명시적인 허용 목록 또는 출처 증거가 없음 |
+
+예상 합계: `ALLOW` 1개, `ASK` 1개, `BLOCK` 5개.
+
+## 드리프트 사례
+
+드리프트 픽스처는 신뢰되는 고정 패키지에서 시작한 뒤 `API_TOKEN` 환경 키를 추가합니다. 회귀 테스트는 다음 변경을 모두 요구합니다.
+
+- `secret-env`에 대한 `signals-added`
+- `ALLOW`에서 `ASK`로의 `decision-changed`
+- `fingerprint-changed`
+
+자리표시자 값 자체는 검사 결과나 스냅샷 어디에도 나타나면 안 됩니다.
+
+## 이 평가가 측정하지 않는 것
+
+이 벤치마크는 의도적으로 범위가 좁습니다. 런타임 동작, 샌드박스 탈출, 임의의 악성 코드, 모든 형태의 프롬프트 인젝션, 게시자 신원 소유권 또는 전이 의존성의 취약점을 측정하지 않습니다. 특히 이미 실행 중인 MCP 서버가 동적으로 반환하는 도구 설명은 현재 정적 설정 경계 밖에 있습니다.
+
+이 작은 픽스처 집합은 회귀 기준선이지 탐지 정확도에 대한 통계적 주장이 아닙니다. 거짓 양성과 거짓 음성 비율을 측정하려면 민감 정보를 제거한 실제 설정으로 구성되고 독립적으로 검토된 더 큰 코퍼스가 필요합니다.

package/docs/EVALUATION.md

@@ -1,5 +1,9 @@
 # Defensive evaluation
 
+<p align="right">
+  <strong>English</strong> | <a href="./EVALUATION.ko.md">한국어</a>
+</p>
+
 This evaluation records the behavior enforced by the checked-in adversarial fixtures. Run `npm run test:research` to reproduce it. The test performs local static inspection only and does not execute or contact any configured server.
 
 ## MCP policy cases

package/docs/RELEASING.ko.md

@@ -0,0 +1,70 @@
+# TrustDex 릴리스
+
+<p align="right">
+  <a href="./RELEASING.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 두 개의 작은 GitHub Actions 워크플로를 사용합니다.
+
+- `release.yml`은 테스트 통과 후 GitHub 태그와 릴리스를 생성합니다.
+- `publish.yml`은 바로 그 태그를 npm에 게시합니다.
+
+이 분리는 GitHub 릴리스 생성과 레지스트리 자격 증명을 분리합니다.
+
+## 최초 게시
+
+일회성 토큰 기반 최초 게시는 완료되었습니다. 일반 릴리스에서 반복하지 마세요.
+
+단기 `NPM_TOKEN`은 신뢰할 수 있는 게시를 설정하고 검증할 때까지만 유지할 수 있습니다. 최초 OIDC 게시에 성공한 즉시 npm 토큰과 GitHub 저장소 비밀을 모두 삭제하세요.
+
+npm 자격 증명을 이슈, 풀 리퀘스트, 소스 파일, 로그 또는 채팅에 붙여 넣지 마세요.
+
+## npm 신뢰할 수 있는 게시
+
+패키지가 만들어진 뒤 다음 값으로 npm 신뢰할 수 있는 게시를 설정합니다.
+
+- GitHub 사용자/조직: `grigent`
+- 저장소: `trustdex`
+- 워크플로 파일 이름: `publish.yml`
+- 허용 작업: 직접 `npm publish`
+
+워크플로는 `contents: read`와 `id-token: write`만 부여합니다. 그러면 npm은 장기 쓰기 토큰 대신 OIDC로 GitHub 호스팅 작업을 인증할 수 있습니다.
+
+신뢰할 수 있는 게시가 작동하면 `NPM_TOKEN` 저장소 비밀을 제거하고 npm에서 최초 게시 토큰을 폐기합니다. npm이 OIDC 인증을 선택할 수 있도록 워크플로는 의도적으로 표준 `npm publish` 명령을 계속 사용합니다.
+
+두 릴리스 워크플로는 `npm pkg fix`를 실행하고 패킹 또는 게시 전에 깨끗한 `package.json` 차이를 요구합니다. 이렇게 하면 npm이 CLI 진입점 같은 중요한 메타데이터를 조용히 정규화해 없애는 것을 방지합니다.
+
+## 출처 및 릴리스 증거
+
+저장소와 패키지가 공개이므로 GitHub 호스팅 게시는 npm 출처를 생성할 수 있습니다. 워크플로는 `--provenance`도 명시적으로 전달합니다.
+
+출처는 게시된 아티팩트를 해당 소스/빌드 환경과 연결합니다. 패키지에 악성 동작이 없다는 것을 증명하지는 않습니다.
+
+GitHub 릴리스 워크플로는 다음도 생성하고 업로드합니다.
+
+- 릴리스 커밋에서 빌드한 npm 패키지 tarball
+- CycloneDX JSON SBOM
+- tarball과 SBOM을 포함하는 `SHA256SUMS` 파일
+- tarball용 GitHub 빌드 출처 증명
+- SBOM을 tarball에 연결하는 GitHub SBOM 증명
+
+릴리스를 다운로드한 뒤 검사 또는 설치하기 전에 체크섬과 GitHub 증명을 검증하세요.
+
+```bash
+shasum -a 256 -c SHA256SUMS
+gh attestation verify trustdex-<version>.tgz --repo grigent/trustdex
+```
+
+npm 출처 진술과 GitHub 증명은 서로 다른 게시 경로를 다룹니다. 어느 쪽도 악성 코드 분석이 아니며 릴리스 콘텐츠와 문서화된 신뢰 경계를 검토하는 일을 대신하지 않습니다.
+
+## 버전 체크리스트
+
+각 릴리스 전에:
+
+1. `package.json` 버전 업데이트
+2. 해당 변경 기록 섹션을 `Unreleased` 밖으로 이동
+3. CI가 통과하는지 확인
+4. 정확히 `v<package version>`으로 릴리스 워크플로 실행
+5. 바로 그 릴리스 태그에 대해 게시 워크플로 실행
+
+게시 워크플로는 최신 브랜치 HEAD가 아니라 태그 SHA를 체크아웃하므로 npm 아티팩트에 이후 커밋이 조용히 포함될 수 없습니다.

package/docs/RELEASING.md

@@ -1,5 +1,9 @@
 # Releasing TrustDex
 
+<p align="right">
+  <strong>English</strong> | <a href="./RELEASING.ko.md">한국어</a>
+</p>
+
 TrustDex uses two small GitHub Actions workflows:
 
 - `release.yml` creates a GitHub tag and release after tests pass.

package/docs/ROADMAP.ko.md

@@ -0,0 +1,38 @@
+# 로드맵
+
+<p align="right">
+  <a href="./ROADMAP.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 초기 단계입니다. 이 로드맵은 방향을 공유하며 릴리스를 약속하지 않습니다.
+
+## 현재: 경계 강화
+
+- MCP JSON, Codex TOML, 스킬 및 플러그인 매니페스트의 적대적 픽스처 확장
+- 사람이 읽을 수 있는 모든 출력에 비밀 값이 계속 포함되지 않는지 검증
+- 크로스 플랫폼 소스 및 경로 정규화 개선
+- 안정적인 정책 및 스냅샷 스키마 규칙 문서화
+- CI, CodeQL 및 릴리스 자동화를 재현 가능하고 검토 가능한 상태로 유지
+
+## 다음: 무결성 증명
+
+- 레지스트리가 암호학적 해시를 제공할 때 변경 불가능한 패키지 아티팩트 검증
+- 레지스트리 관찰을 정확한 패키지 버전 및 저장소 신원과 연결
+- TrustDex 릴리스용 체크섬 또는 더 강력한 출처 게시
+- 소유권 이전, 삭제된 릴리스, 게시 취소된 패키지 및 레지스트리 드리프트용 픽스처 추가
+
+## 향후: 상호 운용성 확장
+
+- 서명된 스냅샷, 승인 및 재검사 워크플로를 Codex `config.toml`로 확장
+- 추가 에이전트 런타임 및 레지스트리용 어댑터 추가
+- 테스트에 근거한 호환성 매트릭스 게시
+- CI 및 정책 도구용 기계 판독 가능 결정 출력 정의
+- 조직 관리형 신뢰 저장소 및 검토 키 교체 탐색
+
+## 도입 목표
+
+프로젝트는 거짓 양성, 거짓 음성, 설정 형식 및 유지관리자 워크플로에 대해 민감하지 않은 피드백을 공유할 파일럿 사용자를 찾고 있습니다. 사용 관련 주장은 검증할 수 있을 때만 문서화합니다. 스타 수, 브랜딩 및 패키지 이름은 절대 보안 증거로 취급하지 않습니다.
+
+## 참여 방법
+
+실제 설정에서 TrustDex를 실행했다면 **Pilot feedback** 이슈 양식이 결과를 보고하는 가장 빠른 방법입니다. 그렇지 않으면 사용 사례와 민감 정보를 제거한 설정 형태를 설명하는 범위가 명확한 이슈를 여세요. 보안에 민감한 제안에는 예상 신뢰 경계와 우회 사례를 포함하세요.

package/docs/ROADMAP.md

@@ -1,5 +1,9 @@
 # Roadmap
 
+<p align="right">
+  <strong>English</strong> | <a href="./ROADMAP.ko.md">한국어</a>
+</p>
+
 TrustDex is early-stage. This roadmap communicates direction and is not a release commitment.
 
 ## Now: harden the boundary

package/docs/SECURITY_RESEARCH.ko.md

@@ -0,0 +1,64 @@
+# 방어적 보안 연구
+
+<p align="right">
+  <a href="./SECURITY_RESEARCH.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 AI 에이전트가 서드파티 도구에 접근하기 전에 내리는 신뢰 결정에 관한 합법적인 방어적 연구를 위해 개발됩니다. 이 문서는 해당 작업의 승인, 안전 및 공개 경계를 정의합니다.
+
+## 목적
+
+이 연구는 사람이 또는 정책이 명시적으로 신뢰할 때까지 확장을 사용할 수 없게 유지하는 데 관찰 가능한 설정, 출처, 무결성 및 기능 증거가 충분한지 묻습니다. 현재 작업은 다음에 중점을 둡니다.
+
+- 고정되지 않았거나 대체된 패키지
+- 실행 시 설치 및 셸 런처
+- URL에 포함된 자격 증명과 안전하지 않은 원격 전송
+- 값을 보관하지 않고 비밀 정보를 포함하는 환경 변수 이름 감지
+- 소스, 출처, 결정, 지문 및 기능 드리프트
+- 서명된 검토 기록과 신뢰 관련 변경 후 재검토
+- 지원하지 않는 구문에서 안전하게 실패해야 하는 파서 동작
+
+의도한 결과물은 재현 가능한 픽스처, 회귀 테스트, 문서화된 제한 사항 및 에이전트 개발자와 운영자를 위한 실용적인 완화책입니다.
+
+## 승인 경계
+
+연구는 다음으로 제한됩니다.
+
+- 연구자가 소유한 시스템과 계정 또는
+- 연구자가 테스트할 명시적인 승인을 받은 시스템 그리고
+- 민감하지 않은 픽스처를 사용하는 격리된 로컬 또는 연구 전용 테스트 환경
+
+TrustDex 연구는 관련 없는 공개 시스템을 테스트할 권한을 부여하지 않습니다. 자격 증명 탈취, 지속성 확보, 파괴적 작업, 데이터 유출, 대규모 악용, 무단 접근, 악성 코드 배포 및 다른 사람의 보호 조치 우회는 제외됩니다.
+
+## 안전한 테스트 데이터
+
+체크인된 적대적 픽스처는 비활성 설정 문서입니다. 예약된 `.invalid` 도메인, 존재하지 않는 패키지 네임스페이스 및 명백한 자리표시자 값을 사용합니다. TrustDex는 검사 중에 MCP 서버를 실행하지 않습니다.
+
+테스트는 비밀 정보로 보이는 값, URL 자격 증명, 쿼리 값 및 비공개 경로가 검사 결과에 나타나지 않는지 확인합니다. 실제 자격 증명, 비공개 엔드포인트, 개인 데이터 또는 프로덕션 서비스가 필요한 픽스처는 이 저장소에서 허용되지 않습니다.
+
+## 방법
+
+각 연구 사례에는 다음이 포함되어야 합니다.
+
+1. 최소한의 검토 가능한 입력 픽스처
+2. 예상 신뢰 관련 신호
+3. 이름이 지정된 정책에서 예상되는 `ALLOW`, `ASK` 또는 `BLOCK` 결정
+4. 자동화된 회귀 테스트
+5. 문서화된 제한 사항 또는 가능한 우회 조건
+
+`ALLOW` 결과는 관찰된 증거가 선택한 정책과 일치한다는 의미일 뿐입니다. 임의의 코드가 안전하다는 증거로 표현해서는 안 됩니다.
+
+## 발견 사항 처리
+
+사용자를 위험에 빠뜨릴 수 있는 잠재적인 TrustDex 취약점은 [SECURITY.ko.md](../SECURITY.ko.md)를 따라야 합니다. 다른 프로젝트에서 발견한 사항은 해당 프로젝트의 승인된 보안 채널을 통해 공개해야 하며, 합리적인 공동 공개 절차가 끝나기 전에 게시해서는 안 됩니다.
+
+공개 보고서에서는 자격 증명, 비공개 엔드포인트, 독점 프롬프트, 개인 데이터 및 불필요한 위험을 만드는 악용 세부 정보를 제거해야 합니다. 연구 노트는 문제를 재현하고 수정하는 데 필요한 최소한의 증거를 우선해야 합니다.
+
+## 현재 재현 가능한 증거
+
+- [적대적 MCP 픽스처](../examples/adversarial/README.ko.md)
+- [평가 기록](EVALUATION.ko.md)
+- [위협 모델](THREAT_MODEL.ko.md)
+- [보안 정책](../SECURITY.ko.md)
+
+프로젝트는 저장소의 Pilot feedback 이슈 양식을 통해 거짓 양성과 거짓 음성을 포함한 검증 가능한 파일럿 피드백을 환영합니다. 인기도, 브랜딩 및 검증할 수 없는 사용 후기는 보안 증거로 취급하지 않습니다.

package/docs/SECURITY_RESEARCH.md

@@ -1,5 +1,9 @@
 # Defensive security research
 
+<p align="right">
+  <strong>English</strong> | <a href="./SECURITY_RESEARCH.ko.md">한국어</a>
+</p>
+
 TrustDex is developed for legitimate defensive research into trust decisions made before AI agents receive access to third-party tools. This document defines the authorization, safety, and disclosure boundaries for that work.
 
 ## Purpose

package/docs/THREAT_MODEL.ko.md

@@ -0,0 +1,51 @@
+# 위협 모델
+
+<p align="right">
+  <a href="./THREAT_MODEL.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 하나의 좁은 질문을 다룹니다.
+
+> **사용자의 정책에 따라 에이전트가 이 확장을 보고 호출하도록 허용해야 하는가?**
+
+## 범위 내
+
+- 알 수 없거나 승인되지 않은 MCP 소스
+- 검토 없이 변경될 수 있는 유동 패키지 버전
+- 검토된 스냅샷 사이의 소스 변경
+- 출처 주장의 변경 또는 소멸
+- 새로 관찰된 셸, 파일 시스템, 네트워크, 설치, 와일드카드 도구 또는 비밀 환경 신호
+- 정책 회귀로 발생하는 안전하지 않은 도구 노출
+- 검토된 레지스트리 무결성 메타데이터와 일치하지 않는 패키지 바이트로의 대체
+- 설정된 패키지 버전이 무결성 검증된 아티팩트 버전에서 벗어남
+- 서명된 신뢰 기록이 있을 때 검토된 스냅샷의 변조
+
+## 신뢰 경계
+
+TrustDex가 신뢰하는 것:
+
+- 자체 정책/설정을 읽을 수 있을 정도의 로컬 호스트
+- 사용자가 명시적으로 설정한 정책
+- 신뢰 저장소 유지관리자가 검토한 범위 내의 출처 증거
+- 사용자가 신뢰할 수 있는 채널을 통해 얻은 경우에만 공개 키
+
+TrustDex는 익숙한 프로젝트 이름, 스타 수, 패키지 이름 또는 로고를 출처로 취급하지 **않습니다**.
+
+## 범위 밖
+
+- 임의의 서드파티 코드가 악성이 아님을 증명
+- 도구 실행 샌드박싱
+- 모든 프롬프트 인젝션 기법 탐지
+- 모든 전이 의존성의 취약점 검사
+- 무결성이 일치하는 패키지 바이트가 악성이 아님을 증명
+- 로컬 신뢰 저장소 주장만으로 게시자 소유권을 독립적으로 증명
+- 완전히 침해된 호스트 보호
+- 도난당한 서명 비공개 키로부터 보호
+
+## 중요한 실패 모드
+
+유효한 서명은 신뢰 기록이 해당 비공개 키로 서명되었고 연결된 스냅샷 다이제스트가 변경되지 않았음을 증명합니다. 원래 검토가 정확했다는 것은 증명하지 않습니다.
+
+## 설계 원칙
+
+TrustDex는 누락된 증거를 신뢰로 변환해서는 안 됩니다. 알 수 없는 출처는 추측할 이유가 아니라 정책 입력입니다.

package/docs/THREAT_MODEL.md

@@ -1,5 +1,9 @@
 # Threat model
 
+<p align="right">
+  <strong>English</strong> | <a href="./THREAT_MODEL.ko.md">한국어</a>
+</p>
+
 TrustDex addresses one narrow question:
 
 > **Should an agent be allowed to see and invoke this extension under the user's policy?**

package/docs/TRUST_STORE.ko.md

@@ -0,0 +1,93 @@
+# 신뢰 저장소와 출처
+
+<p align="right">
+  <a href="./TRUST_STORE.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 패키지 이름, GitHub 스타 수 또는 브랜딩으로 게시자가 "공식"인지 추측하지 않습니다.
+
+사용자 또는 조직이 로컬 신뢰 저장소에 명시적인 주장을 배치한 경우에만 소스에 `verified` 출처 주장을 부여할 수 있습니다.
+
+## 형식
+
+```json
+{
+  "version": 1,
+  "claims": [
+    {
+      "type": "package",
+      "subject": "example-mcp-server",
+      "publisher": "Example Publisher",
+      "status": "verified",
+      "evidence": {
+        "kind": "manual-review",
+        "reference": "https://example.invalid/security-review",
+        "checkedAt": "2026-09-19T00:00:00Z"
+      }
+    }
+  ]
+}
+```
+
+지원되는 주장 유형:
+
+- `package` - npm/Python 형식의 패키지 주체
+- `remote` - 원격 MCP 호스트 이름
+- `repository` - 향후 저장소 어댑터용 저장소 신원
+
+`verified`라는 단어는 **신뢰 저장소 유지관리자가 기록한 증거에 따라 검증됨**을 의미합니다. OpenAI, TrustDex, GitHub, npm 또는 다른 플랫폼이 확장을 인증했다는 의미가 아닙니다.
+
+## 사용하기
+
+```bash
+node ./bin/trustdex.mjs inspect ./examples/mcp.json \
+  --pack official-first \
+  --trust-store ./examples/trust-store.example.json
+```
+
+알 수 없는 서드파티 소스는 `official-first`에서 계속 차단됩니다. 검증된 출처 주장은 초기 신뢰를 설정할 수 있지만 셸 실행과 같은 차단 기능 신호는 여전히 해당 신뢰보다 우선할 수 있습니다.
+
+## 권장 사례
+
+- 팀 정책인 신뢰 저장소는 소스 관리에 보관
+- 각 주장을 지속 가능한 증거에 연결
+- 가능한 경우 패키지 버전 또는 소스 커밋 고정
+- 소유권이나 기능이 변경되면 주장을 재검토
+- 증거 필드에 자격 증명, 토큰, 비공개 URL 또는 비밀을 기록하지 않음
+
+## 무결성 기반 패키지 증거
+
+`trust-source npm` 및 `trust-source mcp`의 선택적 `--artifact` 플래그는 아티팩트 증거를 기록하기 전에 사용자가 제공한 파일을 검증합니다.
+
+- npm 관찰에는 SHA-256, SHA-384 또는 SHA-512를 사용하는 SRI 값이 필요합니다.
+- MCP Registry 관찰에는 SHA-256 다이제스트가 있는 단일 패키지가 필요합니다.
+- 파일은 로컬에서 읽으며 실행하거나 업로드하지 않습니다.
+- 신뢰 저장소 주장은 레지스트리 식별자, 버전, 예상 무결성 메타데이터, 계산된 다이제스트 및 검증 시간을 기록합니다.
+- 설정된 패키지 버전은 검증된 아티팩트 버전과 일치해야 합니다.
+
+증거 형식 예시:
+
+```json
+{
+  "kind": "npm-registry",
+  "reference": "https://www.npmjs.com/package/example-mcp-server",
+  "checkedAt": "2026-09-19T00:00:00Z",
+  "artifact": {
+    "registryType": "npm",
+    "identifier": "example-mcp-server",
+    "version": "1.2.3",
+    "integrity": "sha512-..."
+  },
+  "artifactVerification": {
+    "verified": true,
+    "algorithm": "sha512",
+    "digest": "...",
+    "encoding": "base64",
+    "version": "1.2.3",
+    "identifier": "example-mcp-server",
+    "verifiedAt": "2026-09-19T00:00:01Z"
+  }
+}
+```
+
+아티팩트 무결성은 제공된 바이트가 해당 시점에 관찰된 레지스트리 메타데이터와 일치한다는 것만 증명합니다. 바이트가 안전하다는 것, 레지스트리 계정이 침해되지 않았다는 것 또는 게시자 이름이 합법적이라는 것은 증명하지 않습니다.

package/docs/TRUST_STORE.md

@@ -1,5 +1,9 @@
 # Trust store and provenance
 
+<p align="right">
+  <strong>English</strong> | <a href="./TRUST_STORE.ko.md">한국어</a>
+</p>
+
 TrustDex does not guess whether a publisher is "official" from a package name, GitHub stars, or branding.
 
 A source can receive a `verified` provenance assertion only when the user or an organization places an explicit claim in a local trust store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
   "type": "module",
   "bin": {

package/src/inspect.mjs

@@ -42,6 +42,57 @@ function looksLikePath(value) {
     value.startsWith('../') || /^[A-Za-z]:\\/.test(value);
 }
 
+function fingerprintUrl(value) {
+  try {
+    const url = new URL(String(value));
+    return {
+      origin: `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}`,
+      pathname: url.pathname,
+      queryKeys: [...new Set(url.searchParams.keys())].sort()
+    };
+  } catch {
+    return { invalid: true };
+  }
+}
+
+function fingerprintArgs(args) {
+  const values = Array.isArray(args) ? args.map(String) : [];
+  const sanitized = [];
+  let redactNext = false;
+
+  for (const value of values) {
+    if (redactNext) {
+      sanitized.push('<redacted>');
+      redactNext = false;
+      continue;
+    }
+
+    const assignment = value.match(/^(-{1,2}[^=]+)=(.*)$/);
+    if (assignment && SECRET_KEY_RE.test(assignment[1])) {
+      sanitized.push(`${assignment[1]}=<redacted>`);
+      continue;
+    }
+    if (/^-{1,2}/.test(value) && SECRET_KEY_RE.test(value)) {
+      sanitized.push(value);
+      redactNext = true;
+      continue;
+    }
+    if (value === '-H' || value === '--header') {
+      sanitized.push(value);
+      redactNext = true;
+      continue;
+    }
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+      sanitized.push(fingerprintUrl(value));
+      continue;
+    }
+
+    sanitized.push(value);
+  }
+
+  return sanitized;
+}
+
 function extractRemoteEndpoint(server) {
   const candidate = server?.url || server?.endpoint;
   if (!candidate) return null;
@@ -53,6 +104,8 @@ function extractRemoteEndpoint(server) {
       host: url.hostname.toLowerCase(),
       origin: `${protocol}//${url.host.toLowerCase()}`,
       protocol,
+      pathname: url.pathname,
+      queryKeys: [...new Set(url.searchParams.keys())].sort(),
       hasEmbeddedCredentials: Boolean(url.username || url.password),
       hasQuery: Boolean(url.search)
     };
@@ -95,9 +148,13 @@ function normalizeServer(name, server = {}) {
 
   const fingerprint = sha256Json({
     command,
-    args,
-    url: server.url || null,
-    endpoint: server.endpoint || null,
+    args: fingerprintArgs(args),
+    remoteEndpoint: remote ? {
+      origin: remote.origin,
+      pathname: remote.pathname,
+      queryKeys: remote.queryKeys
+    } : null,
+    invalidEndpoint: (server.url || server.endpoint) && !remote ? true : null,
     envKeys,
     adapter: server._trustdexFingerprintData || null
   });