trustdex 0.4.4 → 0.5.0

package/README.md

@@ -54,6 +54,7 @@ TrustDex deliberately does not infer "official" status from names, stars, or bra
 - run as a GitHub Action in CI
 - fingerprint MCP entries, skills, and plugin manifests without storing secret values
 - inspect and filter Codex `config.toml` MCP sections
+- inspect and filter Claude Code MCP JSON with explicit transport validation and header execution controls
 - perform explicit provenance lookups against GitHub, npm, and the official MCP Registry
 - verify whether the latest GitHub release tag/commit has a GitHub-verified signature
 - create signed review bundles and automatically require re-review when trust-relevant state drifts
@@ -75,8 +76,8 @@ Requires Node.js 20+.
 Run directly from npm:
 
 ```bash
-npx trustdex@0.4.4 --help
-npx trustdex@0.4.4 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
+npx trustdex@0.5.0 --help
+npx trustdex@0.5.0 inspect ./mcp.json --pack strict --policy ./trustdex.policy.json
 ```
 
 Or work from a source checkout:
@@ -166,6 +167,26 @@ The gate removes non-approved MCP sections while preserving unrelated TOML secti
 
 See [Using TrustDex with Codex](docs/CODEX.md) for a step-by-step gating workflow and for how this project uses Codex in its own review process.
 
+## Claude Code MCP configuration
+
+Claude Code uses the `mcpServers` JSON shape. Use the Claude-specific commands so
+transport changes, authentication header metadata, and header helper commands
+are included in inspection and signed review:
+
+```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
+```
+
+Check the gate's result before starting Claude. Only `ALLOW` entries are exposed by
+default; `ASK` entries require review. The adapter rejects settings it cannot
+inspect instead of silently trusting them. These commands are available in npm 0.5.0 and later, and from a source checkout.
+Use `npx trustdex@0.5.0` in place of `node ./bin/trustdex.mjs` to run the published CLI.
+
+See [Using TrustDex with Claude](docs/CLAUDE.md) for supported settings, PowerShell
+error handling, signed review, and the Claude Desktop workflow.
+
 ## Online provenance observations
 
 Normal inspection remains local-only. These commands perform an explicit network lookup only when invoked:
@@ -311,7 +332,7 @@ The private key should never be committed.
 ```yaml
 - uses: actions/checkout@v4
 
-- uses: grigent/trustdex@v0.4.4
+- uses: grigent/trustdex@v0.5.0
   with:
     config: ./mcp.json
     pack: official-first

package/bin/trustdex.mjs

@@ -6,6 +6,7 @@ import process from 'node:process';
 
 import { inspectMcpConfig } from '../src/inspect.mjs';
 import { parseCodexMcpToml, gateCodexToml } from '../src/codex-config.mjs';
+import { parseClaudeMcpConfig } from '../src/claude-config.mjs';
 import { inspectSkillText, inspectPluginManifest } from '../src/extensions.mjs';
 import { evaluateAll } from '../src/policy.mjs';
 import { getPolicyPack, mergePolicy } from '../src/policy-packs.mjs';
@@ -48,6 +49,13 @@ Usage:
   trustdex gate-codex <config.toml> --out gated.toml [--pack ...] [--policy policy.json]
       [--trust-store trust-store.json] [--include-ask]
 
+  trustdex inspect-claude <.mcp.json> [--pack ...] [--policy policy.json] [--json]
+  trustdex gate-claude <.mcp.json> --out gated.json [--pack ...] [--policy policy.json]
+  trustdex snapshot-claude <.mcp.json> --out snapshot.json [--pack ...]
+  trustdex approve-claude <.mcp.json> --private key.pem --dir review [--pack ...]
+  trustdex recheck-claude <.mcp.json> --review-dir review --public key.pem [--json]
+  Claude commands accept the same policy/trust-store flags as their generic counterparts.
+
   trustdex provenance github <owner/repo> [--json]
   trustdex provenance github-release <owner/repo> [--json]
   trustdex provenance npm <package> [--json]
@@ -146,8 +154,14 @@ function setInspectExitCode(results) {
 }
 
 async function evaluateMcp(configPath, args) {
-  const config = await readJson(configPath);
-  const inspected = inspectMcpConfig(config);
+  const isClaude = args[0].endsWith('-claude');
+  let config;
+  try { config = await readJson(configPath); } catch (error) {
+    if (isClaude && error instanceof SyntaxError) throw new Error('Invalid Claude MCP JSON.');
+    throw error;
+  }
+  const inspectionConfig = isClaude ? parseClaudeMcpConfig(config) : config;
+  const inspected = inspectMcpConfig(inspectionConfig);
   const store = await loadTrustStore(args);
   const withProvenance = store ? attachProvenanceAll(inspected, store) : inspected;
   const policy = await loadPolicy(args);
@@ -225,7 +239,7 @@ async function main() {
     return;
   }
 
-  if (command === 'inspect') {
+  if (command === 'inspect' || command === 'inspect-claude') {
     const configPath = args[1];
     if (!configPath) throw new Error('inspect requires a path to an MCP JSON file.');
 
@@ -311,7 +325,7 @@ async function main() {
     return;
   }
 
-  if (command === 'gate') {
+  if (command === 'gate' || command === 'gate-claude') {
     const configPath = args[1];
     const out = getFlag(args, '--out');
     if (!configPath || !out) throw new Error('gate requires <mcp.json> and --out <gated.json>.');
@@ -332,7 +346,7 @@ async function main() {
     return;
   }
 
-  if (command === 'approve') {
+  if (command === 'approve' || command === 'approve-claude') {
     const configPath = args[1];
     const privatePath = getFlag(args, '--private');
     const reviewDir = getFlag(args, '--dir');
@@ -364,7 +378,7 @@ async function main() {
     return;
   }
 
-  if (command === 'recheck') {
+  if (command === 'recheck' || command === 'recheck-claude') {
     const configPath = args[1];
     const reviewDir = getFlag(args, '--review-dir');
     const publicPath = getFlag(args, '--public');
@@ -409,7 +423,7 @@ async function main() {
     return;
   }
 
-  if (command === 'snapshot') {
+  if (command === 'snapshot' || command === 'snapshot-claude') {
     const configPath = args[1];
     const out = getFlag(args, '--out');
     if (!configPath || !out) throw new Error('snapshot requires <mcp.json> and --out <snapshot.json>.');

package/docs/CLAUDE.md

@@ -0,0 +1,133 @@
+# Using TrustDex with Claude
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "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) };
+}