trustdex 0.4.4 → 0.5.1

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.4.4",
+  "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": {
@@ -9,7 +9,7 @@
   "scripts": {
     "test": "node --test",
     "test:research": "node --test test/research-fixtures.test.mjs",
-    "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/codex-config.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
+    "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/claude-config.mjs && node --check src/codex-config.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
     "prepublishOnly": "npm test && npm run check"
   },
   "engines": {

package/src/claude-config.mjs

@@ -0,0 +1,106 @@
+const SERVER_KEYS = {
+  stdio: new Set(['type', 'command', 'args', 'env']),
+  http: new Set(['type', 'url', 'headers', 'headersHelper']),
+  sse: new Set(['type', 'url', 'headers', 'headersHelper'])
+};
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g;
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireKeys(value, allowed, context) {
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw new Error(`Unsupported ${context} field. Claude MCP inspection fails closed on unknown settings.`);
+  }
+}
+
+function environmentReferences(value) {
+  return [...new Set([...value.matchAll(ENV_REFERENCE)].map((match) => match[1]))].sort();
+}
+
+// Return inspection input only. Gating must preserve entries from the original
+// configuration, never these internal adapter annotations.
+export function parseClaudeMcpConfig(config) {
+  if (!isRecord(config) || !isRecord(config.mcpServers)) {
+    throw new Error('Expected a Claude MCP JSON object containing an mcpServers object.');
+  }
+  requireKeys(config, new Set(['mcpServers']), 'Claude MCP root');
+
+  const entries = Object.entries(config.mcpServers).map(([name, server]) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name)) {
+      throw new Error('Unsupported Claude MCP server name.');
+    }
+    if (!isRecord(server)) throw new Error('Each Claude MCP server must be an object.');
+    const type = server.type === undefined ? 'stdio' : server.type;
+    if (typeof type !== 'string' || !Object.hasOwn(SERVER_KEYS, type)) {
+      throw new Error('Unsupported Claude MCP transport. Supported: stdio, http, sse.');
+    }
+    requireKeys(server, SERVER_KEYS[type], 'Claude MCP server');
+    const signals = [];
+    const adapter = { runtime: 'claude-mcp-v1', transport: type };
+
+    if (type === 'stdio') {
+      if (typeof server.command !== 'string' || !server.command.trim()) {
+        throw new Error('Claude stdio MCP servers require a non-empty command.');
+      }
+      if (server.command.includes('${')) {
+        throw new Error('Claude command variable expansion is unsupported; use an explicit executable.');
+      }
+      if (server.args !== undefined && (!Array.isArray(server.args) || server.args.some((arg) => typeof arg !== 'string' || arg.includes('${')))) {
+        throw new Error('Claude MCP args must be strings without unresolved variable expansion.');
+      }
+      if (server.env !== undefined && (!isRecord(server.env) || Object.values(server.env).some((value) => typeof value !== 'string'))) {
+        throw new Error('Claude MCP env must contain string values.');
+      }
+      // Reference names are safe metadata; do not fingerprint env values or defaults.
+      adapter.envReferences = Object.fromEntries(Object.entries(server.env || {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, environmentReferences(value)]));
+    } else {
+      if (typeof server.url !== 'string' || !server.url.trim() || server.url.includes('${')) {
+        throw new Error('Claude remote MCP servers require a literal HTTP(S) URL.');
+      }
+      let endpoint;
+      try { endpoint = new URL(server.url); } catch {
+        throw new Error('Invalid Claude MCP URL.');
+      }
+      if (!['https:', 'http:'].includes(endpoint.protocol)) {
+        throw new Error('Unsupported Claude MCP URL scheme.');
+      }
+      // The generic inspector fingerprints its input URL. Reject URL credentials
+      // and query/fragment values before they can enter that fingerprint.
+      if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new Error('Claude MCP URL credentials, query parameters, and fragments are unsupported; use headers.');
+      }
+      if (server.headers !== undefined) {
+        if (!isRecord(server.headers) || Object.values(server.headers).some((value) => typeof value !== 'string')) {
+          throw new Error('Claude MCP headers must contain string values.');
+        }
+        adapter.headerNames = Object.keys(server.headers).sort();
+        adapter.headerReferences = Object.fromEntries(Object.entries(server.headers)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, value]) => [key, environmentReferences(value)]));
+        if (adapter.headerNames.length) {
+          const references = Object.values(adapter.headerReferences);
+          if (references.some((refs) => refs.length)) signals.push('env-http-headers');
+          if (references.some((refs) => !refs.length)) signals.push('static-http-headers');
+        }
+      }
+      if (server.headersHelper !== undefined) {
+        if (typeof server.headersHelper !== 'string' || !server.headersHelper.trim()) {
+          throw new Error('Claude MCP headersHelper must be a non-empty string.');
+        }
+        signals.push('header-helper-command');
+        adapter.hasHeadersHelper = true;
+      }
+    }
+
+    return [name, {
+      ...server,
+      _trustdexSignals: signals,
+      _trustdexFingerprintData: adapter
+    }];
+  });
+  return { mcpServers: Object.fromEntries(entries) };
+}

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
   });