trustdex 0.4.0

package/src/inspect.mjs

@@ -0,0 +1,121 @@
+import { sha256Json } from './canonical.mjs';
+
+const SECRET_KEY_RE = /(token|secret|password|passwd|api[_-]?key|credential|auth)/i;
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'fish', 'cmd', 'powershell', 'pwsh']);
+const RUNNERS = new Set(['npx', 'pnpx', 'bunx', 'uvx']);
+
+function executableName(command = '') {
+  const name = String(command).trim().split(/[\\/]/).pop().toLowerCase();
+  return name.replace(/\.(?:bat|cmd|exe)$/i, '');
+}
+
+function firstPackageArg(command, args) {
+  const cmd = executableName(command);
+  if (!RUNNERS.has(cmd)) return null;
+  const values = Array.isArray(args) ? args.map(String) : [];
+  for (let i = 0; i < values.length; i += 1) {
+    const arg = values[i];
+    if (arg === '--package' || arg === '-p') return values[i + 1] || null;
+    if (arg.startsWith('--package=')) return arg.slice('--package='.length) || null;
+    if (arg.startsWith('-p=')) return arg.slice('-p='.length) || null;
+    if (arg.startsWith('-')) continue;
+    return arg;
+  }
+  return null;
+}
+
+export function isPinnedPackage(spec) {
+  if (!spec) return false;
+  const value = String(spec).trim();
+  if (!value || /@(latest|next|canary|beta|alpha)$/i.test(value)) return false;
+  if (value.startsWith('@')) {
+    const slash = value.indexOf('/');
+    if (slash < 0) return false;
+    return value.indexOf('@', slash) > slash;
+  }
+  return value.lastIndexOf('@') > 0 || /==[^=\s]+$/.test(value);
+}
+
+function looksLikePath(value) {
+  if (typeof value !== 'string') return false;
+  return value.startsWith('/') || value.startsWith('~/') || value.startsWith('./') ||
+    value.startsWith('../') || /^[A-Za-z]:\\/.test(value);
+}
+
+function extractRemoteEndpoint(server) {
+  const candidate = server?.url || server?.endpoint;
+  if (!candidate) return null;
+
+  try {
+    const url = new URL(String(candidate));
+    const protocol = url.protocol.toLowerCase();
+    return {
+      host: url.hostname.toLowerCase(),
+      origin: `${protocol}//${url.host.toLowerCase()}`,
+      protocol,
+      hasEmbeddedCredentials: Boolean(url.username || url.password),
+      hasQuery: Boolean(url.search)
+    };
+  } catch {
+    return null;
+  }
+}
+
+function normalizeServer(name, server = {}) {
+  const command = String(server.command || '');
+  const args = Array.isArray(server.args) ? server.args.map(String) : [];
+  const env = server.env && typeof server.env === 'object' ? server.env : {};
+  const envKeys = Object.keys(env).sort();
+  const packageSpec = firstPackageArg(command, args);
+  const remote = extractRemoteEndpoint(server);
+  const remoteHost = remote?.host || null;
+  const signals = new Set(Array.isArray(server._trustdexSignals) ? server._trustdexSignals : []);
+
+  if (remote) signals.add('network-endpoint');
+  if (remote && ['http:', 'ws:'].includes(remote.protocol)) signals.add('insecure-transport');
+  if (remote?.hasEmbeddedCredentials) signals.add('embedded-credentials');
+  if (remote?.hasQuery) signals.add('url-query-parameters');
+  if (SHELLS.has(executableName(command))) signals.add('shell-execution');
+  if (RUNNERS.has(executableName(command))) signals.add('install-on-run');
+  if (packageSpec && !isPinnedPackage(packageSpec)) signals.add('unbounded-version');
+  if (args.some(looksLikePath)) signals.add('filesystem-path');
+  if (envKeys.some((key) => SECRET_KEY_RE.test(key))) signals.add('secret-env');
+
+  let source = { type: 'unknown' };
+  if (remote) {
+    source = {
+      type: 'remote',
+      host: remoteHost,
+      origin: remote.origin,
+      protocol: remote.protocol
+    };
+  }
+  else if (packageSpec) source = { type: 'package', runner: executableName(command), package: packageSpec, pinned: isPinnedPackage(packageSpec) };
+  else if (command) source = { type: 'local', command };
+
+  const fingerprint = sha256Json({
+    command,
+    args,
+    url: server.url || null,
+    endpoint: server.endpoint || null,
+    envKeys,
+    adapter: server._trustdexFingerprintData || null
+  });
+
+  return { name, source, fingerprint, signals: [...signals].sort(), envKeys };
+}
+
+export function inspectMcpConfig(config) {
+  const servers = config?.mcpServers && typeof config.mcpServers === 'object'
+    ? config.mcpServers
+    : config?.servers && typeof config.servers === 'object'
+      ? config.servers
+      : config;
+  if (!servers || typeof servers !== 'object' || Array.isArray(servers)) {
+    throw new Error('Expected an MCP configuration object, or an object containing mcpServers/servers.');
+  }
+  return Object.entries(servers)
+    .filter(([, value]) => value && typeof value === 'object' && !Array.isArray(value))
+    .map(([name, server]) => normalizeServer(name, server))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/policy-packs.mjs

@@ -0,0 +1,87 @@
+const BASE_SIGNALS = {
+  'shell-execution': 'block',
+  'secret-env': 'ask',
+  'wildcard-tool-scope': 'ask',
+  'sensitive-path-instructions': 'ask',
+  'shell-instructions': 'ask',
+  'install-instructions': 'ask',
+  'missing-version': 'ask',
+  'header-helper-command': 'block',
+  'static-http-headers': 'ask',
+  'env-http-headers': 'ask',
+  'env-forwarding': 'ask',
+  'auto-approve-tools': 'ask',
+  'embedded-credentials': 'block',
+  'insecure-transport': 'block',
+  'url-query-parameters': 'ask',
+  'artifact-version-mismatch': 'block'
+};
+
+export const POLICY_PACKS = Object.freeze({
+  strict: Object.freeze({
+    version: 1,
+    unknownAction: 'block',
+    localAction: 'ask',
+    verifiedPublisherAction: 'allow',
+    sensitiveAction: 'ask',
+    unpinnedAction: 'block',
+    shellAction: 'block',
+    trustedPackages: [],
+    trustedRepositories: [],
+    allowedRemoteHosts: [],
+    signalActions: BASE_SIGNALS
+  }),
+  'official-first': Object.freeze({
+    version: 1,
+    unknownAction: 'block',
+    localAction: 'ask',
+    verifiedPublisherAction: 'allow',
+    sensitiveAction: 'ask',
+    unpinnedAction: 'ask',
+    shellAction: 'block',
+    trustedPackages: [],
+    trustedRepositories: [],
+    allowedRemoteHosts: [],
+    signalActions: BASE_SIGNALS,
+    note: 'ALLOW verified provenance assertions, ASK for local extensions, and BLOCK unknown third-party sources by default.'
+  }),
+  development: Object.freeze({
+    version: 1,
+    unknownAction: 'ask',
+    localAction: 'ask',
+    verifiedPublisherAction: 'allow',
+    sensitiveAction: 'ask',
+    unpinnedAction: 'ask',
+    shellAction: 'ask',
+    trustedPackages: [],
+    trustedRepositories: [],
+    allowedRemoteHosts: ['localhost', '127.0.0.1', '::1'],
+    signalActions: {
+      ...BASE_SIGNALS,
+      'shell-execution': 'ask',
+      'insecure-transport': 'ask'
+    }
+  })
+});
+
+export function getPolicyPack(name = 'strict') {
+  const pack = POLICY_PACKS[name];
+  if (!pack) {
+    throw new Error(`Unknown policy pack "${name}". Available: ${Object.keys(POLICY_PACKS).join(', ')}`);
+  }
+  return JSON.parse(JSON.stringify(pack));
+}
+
+export function mergePolicy(base, overlay = {}) {
+  return {
+    ...base,
+    ...overlay,
+    signalActions: {
+      ...(base.signalActions || {}),
+      ...(overlay.signalActions || {})
+    },
+    trustedPackages: overlay.trustedPackages ?? base.trustedPackages ?? [],
+    trustedRepositories: overlay.trustedRepositories ?? base.trustedRepositories ?? [],
+    allowedRemoteHosts: overlay.allowedRemoteHosts ?? base.allowedRemoteHosts ?? []
+  };
+}

package/src/policy.mjs

@@ -0,0 +1,102 @@
+const ACTIONS = new Set(['allow', 'ask', 'block']);
+
+function normalizeAction(value, fallback) {
+  const action = String(value || fallback).toLowerCase();
+  return ACTIONS.has(action) ? action : fallback;
+}
+
+function packageName(spec = '') {
+  const value = String(spec);
+  if (value.startsWith('@')) {
+    const slash = value.indexOf('/');
+    if (slash < 0) return value;
+    const versionAt = value.indexOf('@', slash);
+    return versionAt > slash ? value.slice(0, versionAt) : value;
+  }
+  const versionAt = value.lastIndexOf('@');
+  return versionAt > 0 ? value.slice(0, versionAt) : value.replace(/==[^=\s]+$/, '');
+}
+
+function raise(current, next) {
+  const rank = { allow: 0, ask: 1, block: 2 };
+  return rank[next] > rank[current] ? next : current;
+}
+
+function signalAction(policy, signal, fallback = null) {
+  const configured = policy?.signalActions?.[signal];
+  if (!configured) return fallback;
+  return normalizeAction(configured, fallback || 'ask');
+}
+
+export function evaluateServer(server, policy = {}) {
+  const unknownAction = normalizeAction(policy.unknownAction, 'block');
+  const localAction = normalizeAction(policy.localAction, 'ask');
+  const sensitiveAction = normalizeAction(policy.sensitiveAction, 'ask');
+  const unpinnedAction = normalizeAction(policy.unpinnedAction, 'ask');
+  const shellAction = normalizeAction(policy.shellAction, 'block');
+  const verifiedPublisherAction = normalizeAction(policy.verifiedPublisherAction, 'allow');
+
+  const trustedPackages = new Set(policy.trustedPackages || []);
+  const trustedRepositories = new Set((policy.trustedRepositories || []).map((x) => String(x).toLowerCase()));
+  const allowedRemoteHosts = new Set((policy.allowedRemoteHosts || []).map((x) => String(x).toLowerCase()));
+
+  let action = unknownAction;
+  const reasons = [];
+
+  if (server.provenance?.status === 'verified') {
+    action = verifiedPublisherAction;
+    reasons.push(`verified provenance assertion: ${server.provenance.publisher}`);
+  }
+
+  if (server.source.type === 'package') {
+    const pkg = packageName(server.source.package);
+    if (trustedPackages.has(pkg)) {
+      action = 'allow';
+      reasons.push(`trusted package: ${pkg}`);
+    } else if (server.provenance?.status !== 'verified') {
+      reasons.push(`package is not trusted: ${pkg}`);
+    }
+    if (!server.source.pinned) {
+      action = raise(action, unpinnedAction);
+      reasons.push('package version is not pinned');
+    }
+  } else if (server.source.type === 'remote') {
+    if (allowedRemoteHosts.has(server.source.host)) {
+      action = 'allow';
+      reasons.push(`allowed remote host: ${server.source.host}`);
+    } else if (server.provenance?.status !== 'verified') {
+      reasons.push(`remote host is not allowlisted: ${server.source.host}`);
+    }
+  } else if (server.source.type === 'repository') {
+    const repository = String(server.source.repository || '').toLowerCase();
+    if (trustedRepositories.has(repository)) {
+      action = 'allow';
+      reasons.push(`trusted repository: ${server.source.repository}`);
+    } else if (server.provenance?.status !== 'verified') {
+      reasons.push(`repository is not trusted: ${server.source.repository || 'unknown'}`);
+    }
+  } else if (['local', 'skill-file', 'plugin-manifest'].includes(server.source.type)) {
+    if (server.provenance?.status !== 'verified') action = localAction;
+    reasons.push('local extension requires local trust policy');
+  } else if (server.provenance?.status !== 'verified') {
+    reasons.push('source could not be identified');
+  }
+
+  for (const signal of server.signals || []) {
+    let next = signalAction(policy, signal);
+
+    if (!next && signal === 'secret-env') next = sensitiveAction;
+    if (!next && signal === 'shell-execution') next = shellAction;
+
+    if (next) {
+      action = raise(action, next);
+      reasons.push(`signal policy: ${signal} -> ${next}`);
+    }
+  }
+
+  return { ...server, action, reasons };
+}
+
+export function evaluateAll(servers, policy = {}) {
+  return servers.map((server) => evaluateServer(server, policy));
+}