trustdex 0.4.4 → 0.5.1

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

@@ -0,0 +1,137 @@
+# 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;
+it does not prove that server code is safe.
+
+The Claude-specific commands are available in TrustDex 0.5.0 and later.
+Use `npx trustdex@0.5.0` in place of `node ./bin/trustdex.mjs` in the examples
+below to run the published CLI, or use the commands directly from a source checkout.
+
+## Supported configuration
+
+Use a dedicated JSON file with a top-level `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "reviewed-tools": {
+      "type": "http",
+      "url": "https://your-reviewed-server.example/mcp"
+    }
+  }
+}
+```
+
+The URL above is illustrative; configure your own reviewed server and trust policy.
+
+Supported server fields:
+
+| Transport | Fields |
+| --- | --- |
+| `stdio` (also the default when `type` is omitted) | `type`, `command`, `args`, `env` |
+| `http` or `sse` | `type`, `url`, `headers`, `headersHelper` |
+
+Remote entries require an explicit `type`. Command arguments and environment/header
+values must be strings. Unknown root/server fields, other transports, malformed
+entries, unresolved command/argument/endpoint variables, and URLs containing
+credentials, query parameters, or fragments fail closed. This intentionally excludes
+custom `oauth`, `alwaysLoad`, WebSocket settings, and future controls until they have
+an explicit inspection implementation. Ordinary server-managed OAuth needs no
+`oauth` field and remains Claude's responsibility.
+
+Authentication headers add `static-http-headers` and/or `env-http-headers` signals.
+Built-in packs require review for them. `headersHelper` adds
+`header-helper-command`, which built-in packs block because Claude executes it in a
+shell. TrustDex never runs the helper.
+
+Fingerprints include the transport, header names, referenced environment-variable
+names, and helper presence. Header/variable values, defaults, and helper command text
+are omitted. Rotating a credential value alone does not invalidate a review; changing
+its header name or environment reference does. Avoid putting credentials in command
+arguments or URL paths. Gated files preserve original allowed entries and can contain
+credentials supplied in the input: keep them local and out of version control.
+
+## Claude Code
+
+Claude Code reads project MCP configuration from `.mcp.json`. Inspect it using the
+Claude adapter, then supply only the generated configuration for that session.
+
+From a source checkout in 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
+```
+
+The policy file is your explicit trust policy, not a list inferred from vendor names.
+Omit `--policy` to use the strict defaults, which block unknown sources and ask about
+local programs. By default, the gate includes only ALLOW entries. ASK and BLOCK entries
+stay out. A gate exit code of `1` indicates pending ASK decisions; `2` indicates failure.
+Do not launch using an old output file after a failed gate.
+
+The `--strict-mcp-config` flag matters: `--mcp-config` alone adds a configuration
+alongside other MCP sources. Organizations using managed MCP configuration should
+also verify the managed policy's effective servers. This workflow does not gate
+Claude's built-in tools or inspect every skill/plugin automatically.
+
+Inside the resulting Claude Code session, use `/mcp` to verify the actual loaded
+servers. Configuration/unit tests do not replace that runtime check.
+
+Official references:
+[Claude Code MCP](https://code.claude.com/docs/en/mcp) and
+[CLI flags](https://code.claude.com/docs/en/cli-reference).
+
+## Signed review and drift
+
+Keep the Claude adapter throughout a review workflow; generic MCP commands do not
+inspect Claude-specific controls.
+
+```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
+```
+
+Approval refuses BLOCK decisions. ASK decisions require an explicit human review;
+running `approve-claude` records that review but does not automatically change the
+gate's policy. Rechecks return APPROVED, NEEDS_REVIEW, or INVALID. A pre-existing
+generic review has a different fingerprint and must be reviewed with the Claude adapter.
+Private keys must never be committed.
+
+## Claude Desktop
+
+For a local stdio MCP configuration, export just the `mcpServers` object from
+`claude_desktop_config.json` into a dedicated input file. Do not feed unrelated
+Desktop preferences into the MCP adapter. Use `inspect-claude` and `gate-claude`
+on that file, review the result, then replace only the Desktop config's `mcpServers`
+section with the gated section and restart Claude Desktop. Keep a backup of the
+original configuration.
+
+TrustDex does not modify your active Desktop settings or install a connector.
+Desktop extensions and account-level remote connectors require separate review;
+this JSON gate does not automatically govern them.
+
+## Inert example
+
+`examples/claude.mcp.json` uses reserved `.invalid` domains, a placeholder
+environment-variable reference, and an inert helper string. Do not launch it in
+Claude. It is for static inspection only:
+
+```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
+```
+
+Inspection intentionally exits `2`. The expected decisions are one ALLOW, one ASK,
+and two BLOCK; the gate writes only `reviewed` and exits `1` because a review remains.

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?**