mcptrustchecker 1.0.0

package/dist/detectors/unicode.js

@@ -0,0 +1,244 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Stage 1 — Lexical / Unicode integrity.
+ *
+ * Scans every text field for the invisible-character families used to smuggle
+ * instructions past human review, and **decodes** the two families that carry a
+ * payload (Tags block, variation-selector channel) so the recovered text is
+ * surfaced as evidence. Also runs a mixed-script (homoglyph) check using Unicode
+ * script properties — a codepoint blocklist cannot catch visible confusables.
+ */
+import { collectTextFields } from '../util/text.js';
+import { classifyCodepoint, decodeTagCodepoint, decodeVariationSelectorByte, FAMILY_LABELS, } from '../data/unicode.js';
+// ESC (U+001B) then a CSI ([ ... final byte) or OSC (] ... BEL/ST) sequence.
+const ANSI_ESCAPE = /\u001b(?:\[[0-9;?]*[ -\/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\))/;
+function bytesToReadable(bytes) {
+    const printable = bytes.every((b) => b >= 0x20 && b <= 0x7e);
+    if (printable)
+        return Buffer.from(bytes).toString('latin1');
+    return bytes.map((b) => b.toString(16).padStart(2, '0')).join(' ');
+}
+const EMOJI_BASE = /\p{Extended_Pictographic}/u;
+function isVariationSelector(cp) {
+    return cp !== undefined && classifyCodepoint(cp) === 'variation-selector';
+}
+/**
+ * Is a variation selector at index `i` part of a genuine smuggling channel
+ * rather than a legitimate emoji-presentation / keycap selector?
+ *
+ *  - U+E0100–U+E01EF (supplementary selectors) encode bytes 16–255 and have no
+ *    legitimate use in tool metadata → always a channel.
+ *  - Otherwise (VS1–VS16, U+FE00–U+FE0F): a LONE selector is a legitimate
+ *    presentation selector (⚠️) or keycap sequence (1️⃣) and must NOT be flagged.
+ *    Only a RUN of ≥2 consecutive selectors — the one-selector-per-payload-byte
+ *    signature of emoji smuggling — counts.
+ */
+function vsIsSmuggling(chars, i, cp) {
+    if (cp >= 0xe0100 && cp <= 0xe01ef)
+        return true;
+    const prev = i > 0 ? chars[i - 1]?.codePointAt(0) : undefined;
+    const next = chars[i + 1]?.codePointAt(0);
+    return isVariationSelector(prev) || isVariationSelector(next);
+}
+/** Is the neighbor in direction `dir` (skipping variation selectors) an emoji? */
+function neighborIsEmoji(chars, from, dir) {
+    for (let j = from; j >= 0 && j < chars.length; j += dir) {
+        const c = chars[j]?.codePointAt(0);
+        if (isVariationSelector(c))
+            continue; // skip presentation selectors in the sequence
+        return c !== undefined && EMOJI_BASE.test(String.fromCodePoint(c));
+    }
+    return false;
+}
+/**
+ * A ZERO-WIDTH JOINER (U+200D) flanked by emoji is a legitimate emoji ZWJ
+ * sequence (👨‍💻, 🧑‍🔬) — not smuggling. Only exempt that exact shape.
+ */
+function zwjIsEmojiSequence(chars, i, cp) {
+    if (cp !== 0x200d)
+        return false;
+    return neighborIsEmoji(chars, i - 1, -1) && neighborIsEmoji(chars, i + 1, 1);
+}
+/** Group invisible-character hits by family, decoding payload channels. */
+export function analyzeText(text) {
+    if (typeof text !== 'string')
+        return [];
+    const acc = new Map();
+    const chars = [...text];
+    for (let i = 0; i < chars.length; i++) {
+        const cp = chars[i].codePointAt(0);
+        if (cp === undefined)
+            continue;
+        const fam = classifyCodepoint(cp);
+        if (!fam)
+            continue;
+        // Skip legitimate emoji constructs that reuse smuggling-family codepoints.
+        if (fam === 'variation-selector' && !vsIsSmuggling(chars, i, cp))
+            continue;
+        if (fam === 'zero-width' && zwjIsEmojiSequence(chars, i, cp))
+            continue;
+        const entry = acc.get(fam) ?? { count: 0, tagChars: [], vsBytes: [] };
+        entry.count += 1;
+        if (fam === 'tags') {
+            const d = decodeTagCodepoint(cp);
+            if (d)
+                entry.tagChars.push(d);
+        }
+        else if (fam === 'variation-selector') {
+            const b = decodeVariationSelectorByte(cp);
+            if (b !== null)
+                entry.vsBytes.push(b);
+        }
+        acc.set(fam, entry);
+    }
+    const hits = [];
+    for (const [family, entry] of acc) {
+        const hit = { family, count: entry.count };
+        if (family === 'tags' && entry.tagChars.length > 0)
+            hit.decoded = entry.tagChars.join('');
+        if (family === 'variation-selector' && entry.vsBytes.length > 2)
+            hit.decoded = bytesToReadable(entry.vsBytes);
+        hits.push(hit);
+    }
+    return hits;
+}
+/** Resolve the Unicode script names present in a string (Latin, Cyrillic, …). */
+function scriptsOf(text) {
+    const scripts = new Set();
+    const named = [
+        ['Latin', /\p{Script=Latin}/u],
+        ['Cyrillic', /\p{Script=Cyrillic}/u],
+        // Greek only counts when the character is genuinely Latin-CONFUSABLE (Α Β Ε
+        // Κ Μ Ν Ο Ρ Τ Υ Χ ο ρ …) — not math symbols like Δ Ω Σ Φ Ψ Π μ, which appear
+        // constantly in legitimate technical metadata ("ΔT", "kΩ") and are not a
+        // homoglyph attack.
+        ['Greek', /[ΑΒΕΖΗΙΚΜΝΟΡΤΥΧκνορυχ]/u],
+        ['Armenian', /\p{Script=Armenian}/u],
+        ['Hebrew', /\p{Script=Hebrew}/u],
+    ];
+    // Evaluate per token so a legitimately multilingual description isn't flagged;
+    // only a single token that mixes scripts is confusable.
+    for (const token of text.split(/\s+/)) {
+        if (token.length < 2)
+            continue;
+        const tokenScripts = new Set();
+        for (const [name, re] of named)
+            if (re.test(token))
+                tokenScripts.add(name);
+        if (tokenScripts.size > 1) {
+            for (const s of tokenScripts)
+                scripts.add(s);
+        }
+    }
+    return scripts;
+}
+function severityFor(family, count, threshold) {
+    switch (family) {
+        case 'tags':
+            return { severity: 'critical', confidence: 'confirmed' };
+        case 'variation-selector':
+            return count > 2 ? { severity: 'high', confidence: 'confirmed' } : { severity: 'medium', confidence: 'heuristic' };
+        case 'bidi-override':
+            return { severity: 'high', confidence: 'strong' };
+        case 'control':
+            return { severity: 'high', confidence: 'strong' };
+        case 'zero-width':
+        case 'invisible-math':
+            return count >= threshold
+                ? { severity: 'high', confidence: 'strong' }
+                : { severity: 'medium', confidence: 'heuristic' };
+        case 'bidi-isolate':
+        case 'bidi-mark':
+        case 'default-ignorable':
+            return { severity: 'medium', confidence: 'heuristic' };
+        case 'unusual-whitespace':
+            return { severity: 'low', confidence: 'heuristic' };
+        default:
+            return { severity: 'low', confidence: 'speculative' };
+    }
+}
+const FAMILY_RULE = {
+    tags: 'MTC-UNI-001',
+    'variation-selector': 'MTC-UNI-002',
+    'bidi-override': 'MTC-UNI-003',
+    'bidi-isolate': 'MTC-UNI-004',
+    'bidi-mark': 'MTC-UNI-004',
+    'zero-width': 'MTC-UNI-005',
+    'invisible-math': 'MTC-UNI-005',
+    'default-ignorable': 'MTC-UNI-006',
+    'unusual-whitespace': 'MTC-UNI-007',
+    control: 'MTC-UNI-008',
+};
+export const unicodeDetector = {
+    id: 'unicode',
+    stage: 1,
+    title: 'Lexical / Unicode integrity',
+    run(ctx) {
+        const findings = [];
+        const threshold = ctx.config.invisibleCharThreshold;
+        for (const field of collectTextFields(ctx.surface)) {
+            for (const hit of analyzeText(field.text)) {
+                const { severity, confidence } = severityFor(hit.family, hit.count, threshold);
+                const label = FAMILY_LABELS[hit.family];
+                const decodedNote = hit.decoded ? ` Decoded hidden payload: "${hit.decoded}".` : '';
+                findings.push({
+                    ruleId: FAMILY_RULE[hit.family],
+                    title: `Hidden ${label} in ${field.location.field ?? field.location.kind}`,
+                    category: 'injection',
+                    severity,
+                    confidence,
+                    description: `Found ${hit.count} ${label} character(s) in the ${field.location.field ?? 'text'} of ` +
+                        `${field.location.kind}${field.location.name ? ` "${field.location.name}"` : ''}. ` +
+                        `These are invisible to a human reviewer but are read verbatim by the model.${decodedNote}`,
+                    remediation: 'Reject or normalize server metadata containing invisible/smuggling characters. ' +
+                        'Legitimate tool descriptions do not need them.',
+                    location: field.location,
+                    evidence: hit.decoded ?? `${hit.count}× ${hit.family}`,
+                    owasp: 'LLM01:2025 Prompt Injection',
+                    references: ['https://unicode.org/reports/tr39/'],
+                    data: { family: hit.family, count: hit.count, decoded: hit.decoded },
+                });
+            }
+            // ANSI / CSI terminal escape sequences: hidden/overwritten text and color
+            // tricks enable consent phishing in a terminal client. No legitimate
+            // reason for them to be in server metadata.
+            if (ANSI_ESCAPE.test(field.text)) {
+                findings.push({
+                    ruleId: 'MTC-UNI-010',
+                    title: `ANSI terminal escape sequence in ${field.location.field ?? field.location.kind}`,
+                    category: 'injection',
+                    severity: 'high',
+                    confidence: 'strong',
+                    description: 'A terminal escape (ANSI/CSI/OSC) sequence is embedded in server metadata. In a terminal client these ' +
+                        'can move the cursor, hide, recolor, or overwrite text — so the action a user approves can differ from ' +
+                        'what is displayed (consent phishing).',
+                    remediation: 'Strip control/escape sequences from server metadata before displaying it.',
+                    location: field.location,
+                    evidence: JSON.stringify(field.text.slice(0, 60)),
+                    owasp: 'LLM01:2025 Prompt Injection',
+                });
+            }
+            // Mixed-script / homoglyph check (visible confusables).
+            const scripts = scriptsOf(field.text);
+            if (scripts.size > 1) {
+                findings.push({
+                    ruleId: 'MTC-UNI-009',
+                    title: `Mixed-script (homoglyph) text in ${field.location.field ?? field.location.kind}`,
+                    category: 'injection',
+                    severity: 'high',
+                    confidence: 'strong',
+                    description: `A single token mixes multiple scripts (${[...scripts].join(', ')}). This is the signature of a ` +
+                        `homoglyph attack — visually identical characters from another script used to impersonate a ` +
+                        `trusted name or slip past keyword filters.`,
+                    remediation: 'Restrict metadata to a single script, or normalize confusables before display.',
+                    location: field.location,
+                    evidence: field.text.slice(0, 120),
+                    owasp: 'LLM01:2025 Prompt Injection',
+                    references: ['https://unicode.org/reports/tr39/'],
+                    data: { scripts: [...scripts] },
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/engine.d.ts

@@ -0,0 +1,27 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * The scan engine — orchestrates the pipeline over a normalized surface:
+ *   detectors → toxic-flow graph → integrity (TOFU) → filter → score → report.
+ * Pure and synchronous-in-spirit (detectors may be async), with no I/O of its
+ * own beyond what a caller passes in (the lockfile). That keeps it fully
+ * testable and deterministic.
+ */
+import type { ScanReport, ServerSurface, McpTrustCheckerConfig } from './types.js';
+import { type Lockfile } from './lockfile.js';
+export interface ScanOptions {
+    config?: McpTrustCheckerConfig;
+    /**
+     * Pre-loaded lockfile for the integrity check. `undefined` skips integrity;
+     * `null` means "no pin yet" (first-seen). Load with `readLockfile`.
+     */
+    lockfile?: Lockfile | null;
+    /** ISO timestamp to stamp the report with. Omit for a reproducible report. */
+    scannedAt?: string;
+    /** Tool names from other servers in the same scan (cross-server collision). */
+    siblingTools?: {
+        server: string;
+        name: string;
+    }[];
+}
+/** Run the full pipeline over a normalized surface. */
+export declare function scanSurface(rawSurface: ServerSurface, options?: ScanOptions): Promise<ScanReport>;

package/dist/engine.js

@@ -0,0 +1,135 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * The scan engine — orchestrates the pipeline over a normalized surface:
+ *   detectors → toxic-flow graph → integrity (TOFU) → filter → score → report.
+ * Pure and synchronous-in-spirit (detectors may be async), with no I/O of its
+ * own beyond what a caller passes in (the lockfile). That keeps it fully
+ * testable and deterministic.
+ */
+import { resolveConfig } from './config.js';
+import { extractCapabilities } from './util/capabilities.js';
+import { DETECTORS } from './detectors/index.js';
+import { analyzeToxicFlows } from './detectors/toxicFlow.js';
+import { checkIntegrity } from './lockfile.js';
+import { surfaceDigest } from './util/hash.js';
+import { computeScore } from './scoring/index.js';
+import { computeCapabilityProfile } from './scoring/capability.js';
+import { METHODOLOGY_VERSION, TOOL_NAME, TOOL_VERSION } from './version.js';
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+function findingKey(f) {
+    // Include the title so distinct findings that share a rule+location but differ
+    // in detail (e.g. two different squatting dependencies of one package) are not
+    // collapsed by dedup. Title carries the discriminating name/target.
+    return [f.ruleId, f.location?.kind, f.location?.name, f.location?.field, f.title, f.evidence].join('|');
+}
+function isObject(v) {
+    return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Defensively normalize a surface at the engine boundary so a hand-built
+ * (library-API) surface or a non-compliant live server can't crash any stage:
+ * tools/prompts/resources become arrays of objects, and the server object is
+ * always present. Field-level type quirks are handled by the individual stages.
+ */
+function sanitizeSurface(s) {
+    const arr = (v) => (Array.isArray(v) ? v : []);
+    return {
+        ...s,
+        source: isObject(s.source) ? s.source : { kind: 'manifest', origin: '' },
+        server: isObject(s.server) ? s.server : {},
+        tools: arr(s.tools).filter(isObject),
+        prompts: arr(s.prompts).filter(isObject),
+        resources: arr(s.resources).filter(isObject),
+    };
+}
+/** Run the full pipeline over a normalized surface. */
+export async function scanSurface(rawSurface, options = {}) {
+    const surface = sanitizeSurface(rawSurface);
+    const config = resolveConfig(options.config);
+    const capabilities = extractCapabilities(surface, config);
+    const ctx = { surface, config, capabilities, siblingTools: options.siblingTools ?? [] };
+    const raw = [];
+    for (const detector of DETECTORS) {
+        if (config.disabledRules.includes(detector.id))
+            continue;
+        raw.push(...(await detector.run(ctx)));
+    }
+    const { flows, findings: flowFindings } = analyzeToxicFlows(ctx);
+    raw.push(...flowFindings);
+    // Integrity (rug-pull) check, if a lockfile context was provided.
+    let integrity;
+    if (options.lockfile !== undefined) {
+        integrity = checkIntegrity(surface, options.lockfile);
+        if (integrity.status === 'drift') {
+            raw.push({
+                ruleId: 'MTC-TOFU-001',
+                title: 'Server surface changed since it was pinned (possible rug pull)',
+                category: 'supply-chain',
+                severity: 'high',
+                confidence: 'confirmed',
+                description: `The canonical fingerprint of this server no longer matches its pinned value in the lockfile. ` +
+                    `Tool definitions can change silently after you approve them (a rug pull); review every change before ` +
+                    `trusting it again.\n` +
+                    (integrity.changes ?? []).map((c) => `  • ${c.detail}`).join('\n'),
+                remediation: 'Review the diff; re-pin only after confirming the changes are legitimate (`mcptrustchecker pin`).',
+                location: { kind: 'server' },
+                owasp: 'LLM03:2025 Supply Chain',
+                evidence: `${integrity.changes?.length ?? 0} change(s) since pin`,
+                data: { changes: integrity.changes },
+            });
+        }
+    }
+    // Filter: disabled rules, whole-rule allowlist waivers, and location-scoped
+    // baseline suppressions (rule + optional tool/field, with a reason).
+    const disabled = new Set(config.disabledRules);
+    const allowed = new Set(config.allowlist);
+    const suppressions = config.suppress ?? [];
+    const isSuppressed = (f) => suppressions.some((s) => s.rule === f.ruleId &&
+        (s.tool === undefined || s.tool === f.location?.name) &&
+        (s.field === undefined || s.field === f.location?.field));
+    const seen = new Set();
+    const findings = [];
+    for (const f of raw) {
+        if (disabled.has(f.ruleId) || allowed.has(f.ruleId) || isSuppressed(f))
+            continue;
+        const key = findingKey(f);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        findings.push(f);
+    }
+    findings.sort((a, b) => {
+        if (SEVERITY_ORDER[a.severity] !== SEVERITY_ORDER[b.severity])
+            return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+        if (a.category !== b.category)
+            return a.category < b.category ? -1 : 1;
+        return a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0;
+    });
+    const score = computeScore(findings);
+    const findingsBySeverity = Object.fromEntries(SEVERITIES.map((s) => [s, 0]));
+    for (const f of findings)
+        findingsBySeverity[f.severity] += 1;
+    return {
+        tool: { name: TOOL_NAME, version: TOOL_VERSION, methodologyVersion: METHODOLOGY_VERSION },
+        target: {
+            id: surface.id,
+            source: surface.source,
+            server: { name: surface.server.name, version: surface.server.version },
+        },
+        ...(options.scannedAt ? { scannedAt: options.scannedAt } : {}),
+        findings,
+        score,
+        capabilities,
+        capabilityProfile: computeCapabilityProfile(capabilities, flows),
+        toxicFlows: flows,
+        integrity,
+        surfaceDigest: surfaceDigest(surface),
+        stats: {
+            tools: surface.tools.length,
+            prompts: surface.prompts.length,
+            resources: surface.resources.length,
+            findingsBySeverity,
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * MCP Trust Checker public API.
+ *
+ * The same engine that powers the CLI is exported here so a marketplace or CI
+ * service can embed it directly:
+ *
+ *   import { scanSurface, surfaceFromManifest } from 'mcptrustchecker';
+ *   const surface = surfaceFromManifest(toolsJson, 'my-server');
+ *   const report = await scanSurface(surface);
+ *   console.log(report.score.grade, report.score.score);
+ *
+ * Everything in `scanSurface` is deterministic and offline: same methodology
+ * version + same surface ⇒ identical score.
+ */
+export * from './types.js';
+export { METHODOLOGY_VERSION, TOOL_VERSION, TOOL_NAME, UNICODE_DATA_VERSION } from './version.js';
+export { scanSurface, type ScanOptions } from './engine.js';
+export { computeScore } from './scoring/index.js';
+export * as scoringModel from './scoring/model.js';
+export { resolveConfig, loadConfigFile, loadIgnoreFile, DEFAULT_CONFIG } from './config.js';
+export { evaluatePolicy, type PolicyViolation } from './policy.js';
+export { resolveTargets, type ResolveOptions, type ResolvedTarget } from './acquire/index.js';
+export { surfaceFromManifest } from './acquire/manifest.js';
+export { surfaceFromPackageDir, readSourceFiles } from './acquire/source.js';
+export { acquireStdio, acquireHttp, ALLOWED_COMMANDS, type StdioSpec, type LiveOptions } from './acquire/live.js';
+export { parseClientConfig, isClientConfig, packageFromStdio } from './acquire/clientConfig.js';
+export { fetchNpmMeta, fetchPypiMeta } from './acquire/npm.js';
+export { extractCapabilities, extractToolCapability } from './util/capabilities.js';
+export { analyzeToxicFlows } from './detectors/toxicFlow.js';
+export { readLockfile, writeLockfile, pinSurface, checkIntegrity, emptyLockfile, type Lockfile, type LockEntry, } from './lockfile.js';
+export { surfaceDigest, canonicalSurface } from './util/hash.js';
+export { renderTerminal } from './report/terminal.js';
+export { renderJson } from './report/json.js';
+export { renderSarif } from './report/sarif.js';
+export { renderMarkdown } from './report/markdown.js';
+export { renderBadge } from './report/badge.js';
+export { DETECTORS } from './detectors/index.js';

package/dist/index.js

@@ -0,0 +1,46 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * MCP Trust Checker public API.
+ *
+ * The same engine that powers the CLI is exported here so a marketplace or CI
+ * service can embed it directly:
+ *
+ *   import { scanSurface, surfaceFromManifest } from 'mcptrustchecker';
+ *   const surface = surfaceFromManifest(toolsJson, 'my-server');
+ *   const report = await scanSurface(surface);
+ *   console.log(report.score.grade, report.score.score);
+ *
+ * Everything in `scanSurface` is deterministic and offline: same methodology
+ * version + same surface ⇒ identical score.
+ */
+export * from './types.js';
+export { METHODOLOGY_VERSION, TOOL_VERSION, TOOL_NAME, UNICODE_DATA_VERSION } from './version.js';
+// Core engine
+export { scanSurface } from './engine.js';
+export { computeScore } from './scoring/index.js';
+export * as scoringModel from './scoring/model.js';
+// Config
+export { resolveConfig, loadConfigFile, loadIgnoreFile, DEFAULT_CONFIG } from './config.js';
+export { evaluatePolicy } from './policy.js';
+// Acquisition
+export { resolveTargets } from './acquire/index.js';
+export { surfaceFromManifest } from './acquire/manifest.js';
+export { surfaceFromPackageDir, readSourceFiles } from './acquire/source.js';
+export { acquireStdio, acquireHttp, ALLOWED_COMMANDS } from './acquire/live.js';
+export { parseClientConfig, isClientConfig, packageFromStdio } from './acquire/clientConfig.js';
+export { fetchNpmMeta, fetchPypiMeta } from './acquire/npm.js';
+// Capabilities & flows (useful for custom analysis / UIs)
+export { extractCapabilities, extractToolCapability } from './util/capabilities.js';
+export { analyzeToxicFlows } from './detectors/toxicFlow.js';
+// Integrity / lockfile
+export { readLockfile, writeLockfile, pinSurface, checkIntegrity, emptyLockfile, } from './lockfile.js';
+// Hashing (rug-pull fingerprint)
+export { surfaceDigest, canonicalSurface } from './util/hash.js';
+// Reporters
+export { renderTerminal } from './report/terminal.js';
+export { renderJson } from './report/json.js';
+export { renderSarif } from './report/sarif.js';
+export { renderMarkdown } from './report/markdown.js';
+export { renderBadge } from './report/badge.js';
+// Detectors (for extension / introspection)
+export { DETECTORS } from './detectors/index.js';

package/dist/lockfile.d.ts

@@ -0,0 +1,30 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Rug-pull / Trust-On-First-Use (TOFU) integrity lockfile.
+ *
+ * On first scan we pin the canonical fingerprint of each server's tool surface.
+ * On every rescan we diff against the pin: any silent change to a tool's
+ * description or schema (the MCPoison rug-pull) shows up as drift and must be
+ * re-approved. Users are encouraged to commit `mcptrustchecker.lock` to git.
+ */
+import type { IntegrityResult, ServerSurface } from './types.js';
+export interface LockEntry {
+    digest: string;
+    tools: Record<string, string>;
+    instructionsDigest: string;
+    pinnedAt?: string;
+}
+export interface Lockfile {
+    lockfileVersion: 1;
+    methodologyVersion: string;
+    servers: Record<string, LockEntry>;
+}
+export declare function emptyLockfile(): Lockfile;
+export declare function readLockfile(path: string): Lockfile | null;
+export declare function writeLockfile(path: string, lock: Lockfile): void;
+/** Build a lock entry from the current surface. */
+export declare function entryFor(surface: ServerSurface, pinnedAt?: string): LockEntry;
+/** Add/update this surface's pin in the lockfile (returns a new object). */
+export declare function pinSurface(lock: Lockfile, surface: ServerSurface, pinnedAt?: string): Lockfile;
+/** Compare the current surface against its pinned entry. */
+export declare function checkIntegrity(surface: ServerSurface, lock: Lockfile | null): IntegrityResult;

package/dist/lockfile.js

@@ -0,0 +1,87 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Rug-pull / Trust-On-First-Use (TOFU) integrity lockfile.
+ *
+ * On first scan we pin the canonical fingerprint of each server's tool surface.
+ * On every rescan we diff against the pin: any silent change to a tool's
+ * description or schema (the MCPoison rug-pull) shows up as drift and must be
+ * re-approved. Users are encouraged to commit `mcptrustchecker.lock` to git.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { canonicalTool, surfaceDigest, toolDigest } from './util/hash.js';
+import { METHODOLOGY_VERSION } from './version.js';
+function hashString(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+export function emptyLockfile() {
+    return { lockfileVersion: 1, methodologyVersion: METHODOLOGY_VERSION, servers: {} };
+}
+export function readLockfile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse lockfile ${path}: ${err.message}`);
+    }
+}
+export function writeLockfile(path, lock) {
+    writeFileSync(path, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+/** Build a lock entry from the current surface. */
+export function entryFor(surface, pinnedAt) {
+    const tools = {};
+    for (const t of surface.tools)
+        tools[t.name] = toolDigest(t);
+    return {
+        digest: surfaceDigest(surface),
+        tools,
+        instructionsDigest: hashString(surface.server.instructions ?? ''),
+        ...(pinnedAt ? { pinnedAt } : {}),
+    };
+}
+/** Add/update this surface's pin in the lockfile (returns a new object). */
+export function pinSurface(lock, surface, pinnedAt) {
+    return {
+        ...lock,
+        methodologyVersion: METHODOLOGY_VERSION,
+        servers: { ...lock.servers, [surface.id]: entryFor(surface, pinnedAt) },
+    };
+}
+/** Compare the current surface against its pinned entry. */
+export function checkIntegrity(surface, lock) {
+    const currentDigest = surfaceDigest(surface);
+    const entry = lock?.servers[surface.id];
+    if (!entry)
+        return { status: 'first-seen', currentDigest };
+    if (entry.digest === currentDigest)
+        return { status: 'unchanged', currentDigest, previousDigest: entry.digest };
+    const changes = [];
+    const currentTools = {};
+    for (const t of surface.tools)
+        currentTools[t.name] = toolDigest(t);
+    for (const name of Object.keys(currentTools)) {
+        if (!(name in entry.tools)) {
+            changes.push({ kind: 'tool-added', name, detail: `Tool "${name}" is new since the pin.` });
+        }
+        else if (entry.tools[name] !== currentTools[name]) {
+            const tool = surface.tools.find((t) => t.name === name);
+            changes.push({
+                kind: 'tool-changed',
+                name,
+                detail: `Tool "${name}" changed after approval (description/schema drift): ${JSON.stringify(canonicalTool(tool)).slice(0, 200)}…`,
+            });
+        }
+    }
+    for (const name of Object.keys(entry.tools)) {
+        if (!(name in currentTools)) {
+            changes.push({ kind: 'tool-removed', name, detail: `Tool "${name}" was removed since the pin.` });
+        }
+    }
+    if (entry.instructionsDigest !== hashString(surface.server.instructions ?? '')) {
+        changes.push({ kind: 'instructions-changed', detail: 'Server instructions changed since the pin.' });
+    }
+    return { status: 'drift', currentDigest, previousDigest: entry.digest, changes };
+}

package/dist/policy.d.ts

@@ -0,0 +1,13 @@
+/*! MCP Trust Checker · https://mcptrustchecker.com · support@mcptrustchecker.com · © 2026 Illia Haidar · MIT */
+/**
+ * Policy-as-code. A team declares what "acceptable" means once (in
+ * `mcptrustchecker.config.json` under `policy`) and every scan is gated against
+ * it in CI — beyond a single grade/score threshold. Pure and deterministic.
+ */
+import type { Policy, ScanReport } from './types.js';
+export interface PolicyViolation {
+    policy: 'minGrade' | 'maxCapability' | 'denyRules' | 'denyCapabilities';
+    message: string;
+}
+/** Evaluate a report against a policy; empty array means it passes. */
+export declare function evaluatePolicy(report: ScanReport, policy: Policy | undefined): PolicyViolation[];