trustdex 0.4.0

package/docs/TRUST_STORE.md

@@ -0,0 +1,89 @@
+# Trust store and provenance
+
+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.
+
+## Format
+
+```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"
+      }
+    }
+  ]
+}
+```
+
+Supported claim types:
+
+- `package` - npm/Python-style package subject
+- `remote` - remote MCP hostname
+- `repository` - repository identity for future repository adapters
+
+The word `verified` means **verified according to the evidence recorded by the trust-store maintainer**. It does not mean OpenAI, TrustDex, GitHub, npm, or another platform certified the extension.
+
+## Use it
+
+```bash
+node ./bin/trustdex.mjs inspect ./examples/mcp.json \
+  --pack official-first \
+  --trust-store ./examples/trust-store.example.json
+```
+
+Unknown third-party sources remain blocked in `official-first`. A verified provenance assertion can establish initial trust, but blocking capability signals such as shell execution can still override that trust.
+
+## Recommended practice
+
+- keep trust stores in source control when they are team policy
+- link each claim to durable evidence
+- pin package versions or source commits where possible
+- re-review claims when ownership or capabilities change
+- do not record credentials, tokens, private URLs, or secrets in evidence fields
+
+## Integrity-backed package evidence
+
+The optional `--artifact` flag on `trust-source npm` and `trust-source mcp` verifies a user-supplied file before recording artifact evidence.
+
+- npm observations require an SRI value using SHA-256, SHA-384, or SHA-512
+- MCP Registry observations require a single package with a SHA-256 digest
+- the file is read locally and is never executed or uploaded
+- the trust-store claim records the registry identifier, version, expected integrity metadata, computed digest, and verification time
+- the configured package version must match the verified artifact version
+
+Example evidence shape:
+
+```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"
+  }
+}
+```
+
+Artifact integrity proves only that the supplied bytes match the registry metadata observed at that time. It does not prove that the bytes are safe, that the registry account was uncompromised, or that the publisher name is legitimate.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "trustdex",
+  "version": "0.4.0",
+  "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
+  "type": "module",
+  "bin": {
+    "trustdex": "./bin/trustdex.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "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",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "security",
+    "supply-chain",
+    "codex",
+    "agent-skills",
+    "trust-policy",
+    "provenance"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grigent/trustdex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/grigent/trustdex/issues"
+  },
+  "homepage": "https://github.com/grigent/trustdex#readme",
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/canonical.mjs

@@ -0,0 +1,17 @@
+import crypto from 'node:crypto';
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function sha256Text(value) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function sha256Json(value) {
+  return sha256Text(canonicalJson(value));
+}

package/src/codex-config.mjs

@@ -0,0 +1,308 @@
+const CODEX_MCP_NESTED_SECTIONS = new Set(['env', 'http_headers', 'env_http_headers']);
+
+function stripComment(line) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quote && char === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      if (quote === char) quote = null;
+      else if (!quote) quote = char;
+      continue;
+    }
+    if (char === '#' && !quote) return line.slice(0, i);
+  }
+  return line;
+}
+
+function splitTopLevel(value) {
+  const out = [];
+  let current = '';
+  let quote = null;
+  let escaped = false;
+  let depth = 0;
+
+  for (const char of value) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (quote && char === '\\') {
+      current += char;
+      escaped = true;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      if (quote === char) quote = null;
+      else if (!quote) quote = char;
+      current += char;
+      continue;
+    }
+    if (!quote && (char === '[' || char === '{')) depth += 1;
+    if (!quote && (char === ']' || char === '}')) depth -= 1;
+    if (char === ',' && !quote && depth === 0) {
+      out.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+
+  if (current.trim()) out.push(current.trim());
+  return out;
+}
+
+function unquote(value) {
+  const raw = value.trim();
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+function parseValue(raw) {
+  const value = raw.trim();
+  if (!value) return '';
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return unquote(value);
+  }
+  if (value.startsWith('[') && value.endsWith(']')) {
+    return splitTopLevel(value.slice(1, -1)).map(parseValue);
+  }
+  if (value.startsWith('{') && value.endsWith('}')) {
+    const object = {};
+    for (const part of splitTopLevel(value.slice(1, -1))) {
+      const index = part.indexOf('=');
+      if (index < 1) throw new Error(`Unsupported TOML inline table entry: ${part}`);
+      object[unquote(part.slice(0, index).trim())] = parseValue(part.slice(index + 1));
+    }
+    return object;
+  }
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+function valueComplete(value) {
+  let square = 0;
+  let curly = 0;
+  let quote = null;
+  let escaped = false;
+
+  for (const char of value) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quote && char === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      if (quote === char) quote = null;
+      else if (!quote) quote = char;
+      continue;
+    }
+    if (quote) continue;
+    if (char === '[') square += 1;
+    if (char === ']') square -= 1;
+    if (char === '{') curly += 1;
+    if (char === '}') curly -= 1;
+  }
+
+  return !quote && square === 0 && curly === 0;
+}
+
+export function codexServerNameFromHeader(header) {
+  const match = String(header || '').trim().match(
+    /^mcp_servers\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))(?:\.(.*))?$/
+  );
+  if (!match) return null;
+  return {
+    name: match[1] || match[2] || match[3],
+    nested: match[4] || ''
+  };
+}
+
+function envNames(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => {
+    if (typeof item === 'string') return item;
+    if (item && typeof item === 'object' && typeof item.name === 'string') return item.name;
+    return null;
+  }).filter(Boolean);
+}
+
+function applyAssignment(server, nested, key, value) {
+  const signals = server._trustdexSignals;
+
+  if (nested === 'env') {
+    server.env[key] = '<redacted>';
+    return;
+  }
+  if (nested === 'http_headers') {
+    server._trustdexFingerprintData.httpHeaderKeys.push(key);
+    signals.add('static-http-headers');
+    return;
+  }
+  if (nested === 'env_http_headers') {
+    server._trustdexFingerprintData.envHttpHeaderKeys.push(key);
+    signals.add('env-http-headers');
+    return;
+  }
+
+  if (nested) {
+    throw new Error(`Unsupported Codex MCP subsection "${nested}".`);
+  }
+
+  if (key === 'command' && typeof value === 'string') server.command = value;
+  else if (key === 'args' && Array.isArray(value)) server.args = value.map(String);
+  else if (key === 'url' && typeof value === 'string') server.url = value;
+  else if (key === 'cwd' && typeof value === 'string') {
+    server.args ??= [];
+    server._trustdexFingerprintData.cwd = value;
+  } else if (key === 'env' && value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const envKey of Object.keys(value)) server.env[envKey] = '<redacted>';
+  } else if (key === 'env_vars') {
+    for (const envKey of envNames(value)) server.env[envKey] = '<forwarded>';
+    if (envNames(value).length) signals.add('env-forwarding');
+  } else if (key === 'bearer_token_env_var' && typeof value === 'string') {
+    server.env[value] = '<bearer-token>';
+    signals.add('secret-env');
+  } else if (key === 'http_headers' && value && typeof value === 'object') {
+    server._trustdexFingerprintData.httpHeaderKeys.push(...Object.keys(value));
+    if (Object.keys(value).length) signals.add('static-http-headers');
+  } else if (key === 'env_http_headers' && value && typeof value === 'object') {
+    server._trustdexFingerprintData.envHttpHeaderKeys.push(...Object.keys(value));
+    if (Object.keys(value).length) signals.add('env-http-headers');
+  } else if (key === 'http_headers_helper' && typeof value === 'string') {
+    server._trustdexFingerprintData.httpHeadersHelper = value;
+    signals.add('header-helper-command');
+  } else if (key === 'enabled_tools' && Array.isArray(value)) {
+    server._trustdexFingerprintData.enabledTools = value.map(String).sort();
+    if (value.some((item) => String(item) === '*')) signals.add('wildcard-tool-scope');
+  } else if (key === 'disabled_tools' && Array.isArray(value)) {
+    server._trustdexFingerprintData.disabledTools = value.map(String).sort();
+  } else if (key === 'default_tools_approval_mode' && typeof value === 'string') {
+    server._trustdexFingerprintData.defaultToolsApprovalMode = value;
+    if (value === 'approve') signals.add('auto-approve-tools');
+  } else if (key === 'enabled' && typeof value === 'boolean') {
+    server._trustdexFingerprintData.enabled = value;
+  } else if (key === 'startup_timeout_sec' && typeof value === 'number') {
+    server._trustdexFingerprintData.startupTimeoutSec = value;
+  } else if (key === 'tool_timeout_sec' && typeof value === 'number') {
+    server._trustdexFingerprintData.toolTimeoutSec = value;
+  } else {
+    throw new Error(`Unsupported or invalid Codex MCP key "${key}".`);
+  }
+}
+
+export function parseCodexMcpToml(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const servers = {};
+  let section = null;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const cleaned = stripComment(lines[i]).trim();
+    if (!cleaned) continue;
+
+    const headerMatch = cleaned.match(/^\[([^\]]+)\]$/);
+    if (headerMatch) {
+      const rawHeader = headerMatch[1].trim();
+      section = codexServerNameFromHeader(rawHeader);
+      if ((rawHeader === 'mcp_servers' || rawHeader.startsWith('mcp_servers.')) && !section) {
+        throw new Error(`Unsupported Codex MCP section "[${rawHeader}]".`);
+      }
+      if (section?.nested && !CODEX_MCP_NESTED_SECTIONS.has(section.nested)) {
+        throw new Error(`Unsupported Codex MCP subsection "${section.nested}".`);
+      }
+      if (section && !servers[section.name]) {
+        servers[section.name] = {
+          env: {},
+          _trustdexSignals: new Set(),
+          _trustdexFingerprintData: {
+            format: 'codex-toml',
+            cwd: null,
+            httpHeaderKeys: [],
+            envHttpHeaderKeys: [],
+            httpHeadersHelper: null,
+            enabledTools: [],
+            disabledTools: [],
+            defaultToolsApprovalMode: null,
+            enabled: null,
+            startupTimeoutSec: null,
+            toolTimeoutSec: null
+          }
+        };
+      }
+      continue;
+    }
+
+    if (!section) continue;
+    const eq = cleaned.indexOf('=');
+    if (eq < 1) throw new Error(`Unsupported Codex TOML line ${i + 1}: expected key = value`);
+
+    const key = unquote(cleaned.slice(0, eq).trim());
+    let raw = cleaned.slice(eq + 1).trim();
+    while (!valueComplete(raw)) {
+      i += 1;
+      if (i >= lines.length) throw new Error(`Unterminated TOML value for ${key}`);
+      raw += `\n${stripComment(lines[i]).trim()}`;
+    }
+
+    applyAssignment(servers[section.name], section.nested, key, parseValue(raw));
+  }
+
+  for (const server of Object.values(servers)) {
+    server._trustdexSignals = [...server._trustdexSignals].sort();
+    server._trustdexFingerprintData.httpHeaderKeys =
+      [...new Set(server._trustdexFingerprintData.httpHeaderKeys)].sort();
+    server._trustdexFingerprintData.envHttpHeaderKeys =
+      [...new Set(server._trustdexFingerprintData.envHttpHeaderKeys)].sort();
+  }
+
+  return { mcpServers: servers };
+}
+
+export function gateCodexToml(text, results, options = {}) {
+  const includeAsk = Boolean(options.includeAsk);
+  const decisions = new Map(results.map((result) => [result.name, result.action]));
+  const lines = String(text || '').split(/\r?\n/);
+  const kept = [];
+  let keepSection = true;
+
+  for (const line of lines) {
+    const cleaned = stripComment(line).trim();
+    const headerMatch = cleaned.match(/^\[([^\]]+)\]$/);
+    if (headerMatch) {
+      const rawHeader = headerMatch[1].trim();
+      const section = codexServerNameFromHeader(rawHeader);
+      if ((rawHeader === 'mcp_servers' || rawHeader.startsWith('mcp_servers.')) && !section) {
+        throw new Error(`Unsupported Codex MCP section "[${rawHeader}]".`);
+      }
+      if (section?.nested && !CODEX_MCP_NESTED_SECTIONS.has(section.nested)) {
+        throw new Error(`Unsupported Codex MCP subsection "${section.nested}".`);
+      }
+      if (section) {
+        const action = decisions.get(section.name);
+        keepSection = action === 'allow' || (includeAsk && action === 'ask');
+      } else {
+        keepSection = true;
+      }
+    }
+    if (keepSection) kept.push(line);
+  }
+
+  const output = kept.join('\n');
+  return text.endsWith('\n') && !output.endsWith('\n') ? `${output}\n` : output;
+}

package/src/extensions.mjs

@@ -0,0 +1,112 @@
+import { sha256Json, sha256Text } from './canonical.mjs';
+
+const URL_RE = /https?:\/\/[^\s)>'"]+/gi;
+const SENSITIVE_PATH_RE = /(?:~\/\.(?:ssh|aws|config)|\/(?:etc|var\/run\/secrets)\/|\.env(?:\b|\/)|credentials?\b)/i;
+const SHELL_INSTRUCTION_RE = /(?:curl\s+[^\n|]+\|\s*(?:sh|bash)|wget\s+[^\n|]+\|\s*(?:sh|bash)|\brm\s+-rf\b|\bsudo\b|\bpowershell\b|\bchmod\s+\+x\b)/i;
+const INSTALL_RE = /(?:\bnpm\s+(?:i|install)\s+-g\b|\bpipx?\s+install\b|\bcargo\s+install\b|\bcurl\b|\bwget\b)/i;
+
+function parseScalar(value) {
+  const raw = value.trim();
+  if (!raw) return '';
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw.slice(1, -1).split(',').map((item) => parseScalar(item)).filter(Boolean);
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}
+
+export function parseFrontmatter(text) {
+  const value = String(text || '');
+  if (!value.startsWith('---\n') && !value.startsWith('---\r\n')) return {};
+  const lines = value.split(/\r?\n/);
+  const result = {};
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') break;
+    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match) result[match[1]] = parseScalar(match[2]);
+  }
+  return result;
+}
+
+function wildcardTools(metadata) {
+  const tools = metadata['allowed-tools'] ?? metadata.allowed_tools ?? metadata.tools;
+  if (tools === '*') return true;
+  if (Array.isArray(tools)) return tools.some((tool) => String(tool).trim() === '*');
+  return typeof tools === 'string' && /(^|[,\s])\*($|[,\s])/.test(tools);
+}
+
+export function inspectSkillText(text, sourceName = 'SKILL.md') {
+  const value = String(text || '');
+  const metadata = parseFrontmatter(value);
+  const signals = new Set();
+
+  if (URL_RE.test(value)) signals.add('network-instructions');
+  URL_RE.lastIndex = 0;
+  if (SENSITIVE_PATH_RE.test(value)) signals.add('sensitive-path-instructions');
+  if (SHELL_INSTRUCTION_RE.test(value)) signals.add('shell-instructions');
+  if (INSTALL_RE.test(value)) signals.add('install-instructions');
+  if (wildcardTools(metadata)) signals.add('wildcard-tool-scope');
+
+  return {
+    name: String(metadata.name || sourceName),
+    kind: 'skill',
+    source: { type: 'skill-file', path: sourceName },
+    fingerprint: sha256Text(value),
+    metadata: {
+      name: metadata.name || null,
+      description: metadata.description || null,
+      allowedTools: metadata['allowed-tools'] ?? metadata.allowed_tools ?? null
+    },
+    signals: [...signals].sort(),
+    envKeys: []
+  };
+}
+
+function walk(value, path = [], out = []) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walk(item, [...path, String(index)], out));
+  } else if (value && typeof value === 'object') {
+    Object.entries(value).forEach(([key, item]) => walk(item, [...path, key], out));
+  } else {
+    out.push({ path: path.join('.'), value });
+  }
+  return out;
+}
+
+export function inspectPluginManifest(manifest, sourceName = 'plugin.json') {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error('Expected a plugin manifest JSON object.');
+  }
+
+  const signals = new Set();
+  const leaves = walk(manifest);
+  const textLeaves = leaves.filter((entry) => typeof entry.value === 'string');
+
+  if (!manifest.version) signals.add('missing-version');
+  if (textLeaves.some((entry) => /^https?:\/\//i.test(entry.value))) signals.add('network-reference');
+  if (textLeaves.some((entry) => SENSITIVE_PATH_RE.test(entry.value))) signals.add('sensitive-path-reference');
+  if (textLeaves.some((entry) => SHELL_INSTRUCTION_RE.test(entry.value))) signals.add('shell-reference');
+
+  const toolish = leaves.filter((entry) => /(?:tool|permission|capabilit)/i.test(entry.path));
+  if (toolish.some((entry) => entry.value === '*' || (Array.isArray(entry.value) && entry.value.includes('*')))) {
+    signals.add('wildcard-tool-scope');
+  }
+
+  return {
+    name: String(manifest.name || sourceName),
+    kind: 'plugin',
+    source: { type: 'plugin-manifest', path: sourceName },
+    fingerprint: sha256Json(manifest),
+    metadata: {
+      name: manifest.name || null,
+      version: manifest.version || null,
+      description: manifest.description || null
+    },
+    signals: [...signals].sort(),
+    envKeys: []
+  };
+}

package/src/gate.mjs

@@ -0,0 +1,39 @@
+export function gateMcpConfig(config, results, options = {}) {
+  let containerKey = null;
+  let servers = config;
+
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    containerKey = 'mcpServers';
+    servers = config.mcpServers;
+  } else if (config?.servers && typeof config.servers === 'object') {
+    containerKey = 'servers';
+    servers = config.servers;
+  }
+
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) {
+    throw new Error('Expected an MCP configuration object, or an object containing mcpServers/servers.');
+  }
+
+  const includeAsk = Boolean(options.includeAsk);
+  const decisions = new Map(results.map((result) => [result.name, result.action]));
+  const allowed = {};
+
+  for (const [name, server] of Object.entries(servers)) {
+    const action = decisions.get(name);
+    if (action === 'allow' || (includeAsk && action === 'ask')) {
+      allowed[name] = server;
+    }
+  }
+
+  const output = containerKey ? { ...config, [containerKey]: allowed } : allowed;
+
+  return {
+    config: output,
+    summary: {
+      total: Object.keys(servers).length,
+      exposed: Object.keys(allowed).length,
+      blocked: results.filter((result) => result.action === 'block').map((result) => result.name),
+      needsReview: results.filter((result) => result.action === 'ask').map((result) => result.name)
+    }
+  };
+}