@proofofwork-agency/toolpin 0.2.3

package/dist/runtimeAdvisory.js

@@ -0,0 +1,80 @@
+import net from "node:net";
+import { readInstalledServerConfig } from "./doctor.js";
+import { resolveConfigTarget } from "./install.js";
+export async function localHttpRuntimeAdvisory(serverName, client, scope) {
+    const target = resolveConfigTarget(client, scope);
+    const installed = await readInstalledServerConfig(target.file, serverName, client);
+    if (installed.kind !== "ok")
+        return undefined;
+    const endpoint = localHttpEndpoint(installed.config);
+    if (!endpoint)
+        return undefined;
+    const running = await isTcpPortOpen(endpoint.host, endpoint.port);
+    return {
+        ...endpoint,
+        running,
+        message: running
+            ? `local HTTP endpoint ${endpoint.url} is accepting connections; delete removes config/lock only and does not stop that process.`
+            : `local HTTP endpoint ${endpoint.url} is configured, but port ${endpoint.port} is not accepting connections right now.`,
+    };
+}
+export function localHttpEndpoint(config) {
+    const record = asRecord(config);
+    const raw = firstString(record.url, record.httpUrl, record.serverUrl);
+    if (!raw)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return undefined;
+    if (!url.port)
+        return undefined;
+    const host = normalizeHost(url.hostname);
+    if (!isLoopbackHost(host))
+        return undefined;
+    const port = Number.parseInt(url.port, 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return undefined;
+    return { url: raw, host, port };
+}
+async function isTcpPortOpen(host, port, timeoutMs = 200) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host: connectHost(host), port });
+        let settled = false;
+        const finish = (open) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(open);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish(true));
+        socket.once("timeout", () => finish(false));
+        socket.once("error", () => finish(false));
+    });
+}
+function isLoopbackHost(host) {
+    if (host === "localhost" || host === "::1" || host === "0.0.0.0")
+        return true;
+    if (/^127(?:\.\d{1,3}){3}$/.test(host))
+        return true;
+    return false;
+}
+function connectHost(host) {
+    return host === "0.0.0.0" ? "127.0.0.1" : host;
+}
+function normalizeHost(host) {
+    return host.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/dist/safeFetch.js

@@ -0,0 +1,157 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+export async function safeFetch(input, options = {}) {
+    const url = new URL(input);
+    await assertSafeUrl(url, options.allowedHosts, options.lookup);
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, maxBytes: _maxBytes, allowedHosts: _allowedHosts, fetch: fetchImpl = fetch, lookup: _lookup, ...fetchOptions } = options;
+    return fetchImpl(url, {
+        ...fetchOptions,
+        redirect: "error",
+        signal: fetchOptions.signal ?? AbortSignal.timeout(timeoutMs),
+    });
+}
+export async function safeFetchBuffer(input, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const response = await safeFetch(input, options);
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+    return readResponseCapped(response, maxBytes);
+}
+export async function safeFetchJson(input, options = {}) {
+    const bytes = await safeFetchBuffer(input, {
+        ...options,
+        headers: {
+            Accept: "application/json",
+            ...(options.headers ?? {}),
+        },
+    });
+    return JSON.parse(bytes.toString("utf8"));
+}
+export async function assertSafeUrl(url, allowedHosts, lookupImpl = lookup) {
+    if (url.protocol !== "https:")
+        throw new Error(`Refusing non-HTTPS URL: ${url.href}`);
+    const hostname = normalizeHostname(url.hostname);
+    if (allowedHosts && !allowedHosts.has(hostname)) {
+        throw new Error(`Refusing untrusted host ${hostname}`);
+    }
+    await assertPublicHostname(hostname, lookupImpl);
+}
+async function assertPublicHostname(hostname, lookupImpl) {
+    if (isIP(hostname)) {
+        if (isBlockedIp(hostname))
+            throw new Error(`Refusing private or reserved IP address ${hostname}`);
+        return;
+    }
+    const addresses = await lookupImpl(hostname, { all: true, verbatim: true });
+    for (const address of addresses) {
+        if (isBlockedIp(address.address)) {
+            throw new Error(`Refusing private or reserved IP address ${address.address} for ${hostname}`);
+        }
+    }
+}
+async function readResponseCapped(response, maxBytes) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return Buffer.from(await response.arrayBuffer());
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Error(`Response exceeded ${maxBytes} byte limit`);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+}
+function normalizeHostname(hostname) {
+    return hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+}
+function isBlockedIp(address) {
+    const normalized = normalizeHostname(address);
+    const family = isIP(normalized);
+    if (family === 4)
+        return isBlockedIpv4(normalized);
+    if (family === 6)
+        return isBlockedIpv6(normalized);
+    return true;
+}
+function isBlockedIpv4(address) {
+    const parts = address.split(".").map((part) => Number.parseInt(part, 10));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return true;
+    const [a, b] = parts;
+    return a === 0
+        || a === 10
+        || a === 127
+        || (a === 169 && b === 254)
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 100 && b >= 64 && b <= 127)
+        || (a === 198 && (b === 18 || b === 19))
+        || a >= 224;
+}
+function isBlockedIpv6(address) {
+    const lower = address.toLowerCase();
+    const mappedIpv4 = lower.match(/(?:^|:)ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mappedIpv4)
+        return isBlockedIpv4(mappedIpv4[1]);
+    const groups = parseIpv6Groups(lower);
+    if (groups) {
+        const embeddedIpv4 = ipv4FromEmbeddedIpv6(groups);
+        if (embeddedIpv4 && isBlockedIpv4(embeddedIpv4))
+            return true;
+    }
+    return lower === "::"
+        || lower === "::1"
+        || lower.startsWith("fc")
+        || lower.startsWith("fd")
+        || lower.startsWith("fe8")
+        || lower.startsWith("fe9")
+        || lower.startsWith("fea")
+        || lower.startsWith("feb")
+        || lower.startsWith("ff");
+}
+function parseIpv6Groups(address) {
+    const withoutZone = address.split("%", 1)[0];
+    const [headRaw, tailRaw, extra] = withoutZone.split("::");
+    if (extra !== undefined)
+        return undefined;
+    const head = headRaw ? headRaw.split(":") : [];
+    const tail = tailRaw ? tailRaw.split(":") : [];
+    if (!withoutZone.includes("::") && head.length !== 8)
+        return undefined;
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0)
+        return undefined;
+    const groups = [...head, ...Array.from({ length: missing }, () => "0"), ...tail];
+    if (groups.length !== 8)
+        return undefined;
+    const parsed = groups.map((part) => Number.parseInt(part, 16));
+    if (parsed.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff))
+        return undefined;
+    return parsed;
+}
+function ipv4FromEmbeddedIpv6(groups) {
+    const firstFiveZero = groups.slice(0, 5).every((group) => group === 0);
+    const compatible = firstFiveZero && groups[5] === 0;
+    const mapped = firstFiveZero && groups[5] === 0xffff;
+    if (!compatible && !mapped)
+        return undefined;
+    const high = groups[6];
+    const low = groups[7];
+    return [
+        (high >> 8) & 0xff,
+        high & 0xff,
+        (low >> 8) & 0xff,
+        low & 0xff,
+    ].join(".");
+}

package/dist/sarif.js

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+const HELP_URI = "https://github.com/proofofwork-agency/toolpin#security-model";
+const RULES = [
+    rule("agent_instruction_override", "Agent instruction override", "Registry or tool metadata asks the agent to ignore higher-priority instructions.", "scan", "warning"),
+    rule("agent_hidden_behavior", "Hidden agent behavior", "Registry or tool metadata asks the agent to hide behavior from the user.", "scan", "warning"),
+    rule("agent_forced_tool_order", "Forced tool order", "Registry or tool metadata tries to force tool invocation order.", "scan", "note"),
+    rule("hidden_control_characters", "Hidden control characters", "Registry or tool metadata contains hidden or control characters.", "scan", "warning"),
+    rule("duplicate_tool_name", "Duplicate tool name", "A live tools/list response contains duplicate tool names.", "scan", "warning"),
+    rule("cross_tool_instruction", "Cross-tool instruction", "A tool description instructs the agent to use a sibling tool.", "scan", "note"),
+    rule("no_install_target", "No install target", "The server has no installable package or remote target.", "verify", "error"),
+    rule("mutable_oci_tag", "Mutable OCI tag", "An OCI package is not pinned by digest.", "verify", "error"),
+    rule("missing_mcpb_hash", "Missing MCPB hash", "An MCPB package is missing fileSha256.", "verify", "error"),
+    rule("package_probe_failed", "Package probe failed", "Live package capability verification failed.", "verify", "error"),
+    rule("remote_probe_failed", "Remote probe failed", "Live remote capability verification failed.", "verify", "error"),
+    rule("remote_probe_skipped", "Remote probe skipped", "Live remote capability verification was skipped.", "verify", "warning"),
+    rule("ci_lock_drift", "CI lock drift", "Frozen install verification found lockfile drift or resolver failures.", "ci", "error"),
+    rule("ci_digest_mismatch", "CI digest mismatch", "The lockfile digest does not match the expected digest.", "ci", "error"),
+    rule("ci_signature_failed", "CI signature failure", "The detached lockfile signature check failed.", "ci", "error"),
+];
+export function sarifLog(results, options = {}) {
+    return {
+        version: "2.1.0",
+        $schema: SARIF_SCHEMA,
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "ToolPin",
+                        informationUri: "https://github.com/proofofwork-agency/toolpin",
+                        rules: rulesForResults(results),
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: options.executionSuccessful ?? !results.some((result) => result.level === "error"),
+                        startTimeUtc: options.generatedAt ?? new Date().toISOString(),
+                    },
+                ],
+                results,
+            },
+        ],
+    };
+}
+export function scanSarifResults(scans) {
+    return scans.flatMap((scan) => scan.findings.map((finding) => resultFromScanFinding(finding)));
+}
+export function verificationSarifResults(report) {
+    const normalized = new Map();
+    for (const issue of report.issues) {
+        const result = resultFromTrustIssue(issue, `server:${report.serverName}`);
+        normalized.set(dedupeKey(result), result);
+    }
+    const embeddedScan = report.capabilityManifest.toolDescriptionScan;
+    if (embeddedScan) {
+        for (const result of scanSarifResults([embeddedScan])) {
+            normalized.set(dedupeKey(result), result);
+        }
+    }
+    return [...normalized.values()];
+}
+export function ciSarifResults(report, lockfilePath) {
+    return report.issues.flatMap((issue) => issue.messages.map((message) => ciSarifResult("ci_lock_drift", message, lockfilePath, issue.key)));
+}
+export function ciSarifResult(code, message, lockfilePath, subject = lockfilePath) {
+    return {
+        ruleId: code,
+        level: "error",
+        message: { text: message },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: { uri: lockfilePath },
+                },
+                logicalLocations: [
+                    {
+                        name: subject,
+                        fullyQualifiedName: subject,
+                        kind: "lockfileEntry",
+                    },
+                ],
+            },
+        ],
+        partialFingerprints: fingerprintParts(code, subject, message),
+    };
+}
+function resultFromScanFinding(finding) {
+    return {
+        ruleId: finding.code,
+        level: levelForSeverity(finding.severity),
+        message: { text: finding.message },
+        locations: [logicalLocation(finding.subject)],
+        partialFingerprints: fingerprintParts(finding.code, finding.subject, finding.message),
+    };
+}
+function resultFromTrustIssue(issue, fallbackSubject) {
+    const { subject, message } = splitSubject(issue.message, fallbackSubject);
+    return {
+        ruleId: issue.code,
+        level: levelForSeverity(issue.severity),
+        message: { text: message },
+        locations: [logicalLocation(subject)],
+        partialFingerprints: fingerprintParts(issue.code, subject, message),
+    };
+}
+function splitSubject(message, fallbackSubject) {
+    const match = /^(server|tool):([^:]+):\s+(.+)$/.exec(message);
+    if (!match)
+        return { subject: fallbackSubject, message };
+    return { subject: `${match[1]}:${match[2]}`, message: match[3] ?? message };
+}
+function logicalLocation(subject) {
+    const [kind, ...nameParts] = subject.split(":");
+    const name = nameParts.join(":") || subject;
+    return {
+        logicalLocations: [
+            {
+                name,
+                fullyQualifiedName: subject,
+                kind: kind || "server",
+            },
+        ],
+    };
+}
+function fingerprintParts(code, subject, message) {
+    return {
+        toolpinFindingId: createHash("sha256").update(`${code}\0${subject}\0${message}`).digest("hex"),
+    };
+}
+function dedupeKey(result) {
+    const subject = result.locations[0]?.logicalLocations?.[0]?.fullyQualifiedName ?? "";
+    return `${result.ruleId}\0${subject}\0${result.message.text}`;
+}
+function rulesForResults(results) {
+    const ids = new Set(results.map((result) => result.ruleId));
+    const selected = [...RULES];
+    for (const id of ids) {
+        if (!RULES.some((entry) => entry.id === id)) {
+            selected.push(rule(id, id, "ToolPin finding.", "verify", "warning"));
+        }
+    }
+    return selected;
+}
+function levelForSeverity(severity) {
+    if (severity === "critical")
+        return "error";
+    if (severity === "warning")
+        return "warning";
+    return "note";
+}
+function rule(id, name, description, category, severity) {
+    return {
+        id,
+        name,
+        shortDescription: { text: description },
+        helpUri: HELP_URI,
+        properties: {
+            category,
+            "problem.severity": severity,
+        },
+    };
+}

package/dist/scan.js

@@ -0,0 +1,113 @@
+const AGENT_DIRECTED_PATTERNS = [
+    {
+        code: "agent_instruction_override",
+        severity: "warning",
+        pattern: /\b(ignore|disregard|override)\s+(all\s+)?(previous|prior|above|system|developer)\s+instructions?\b/i,
+        label: "asks the agent to ignore higher-priority instructions",
+    },
+    {
+        code: "agent_hidden_behavior",
+        severity: "warning",
+        pattern: /\b(do\s+not|don't|never)\s+(tell|inform|notify|mention|reveal)\s+(the\s+)?user\b/i,
+        label: "asks the agent to hide behavior from the user",
+    },
+    {
+        code: "agent_forced_tool_order",
+        severity: "info",
+        pattern: /\b(always|must|required to)\s+(call|use|invoke|run)\s+[a-zA-Z0-9_.:/-]+(\s+first)?\b/i,
+        label: "forces tool ordering in descriptive metadata",
+    },
+];
+const HIDDEN_CHARACTER_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u061C\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/u;
+export function scanServerMetadata(server, generatedAt = new Date().toISOString()) {
+    return scanToolDescriptions([{ name: server.name, description: server.description }], {
+        generatedAt,
+        subjectPrefix: "server",
+    });
+}
+export function scanToolDescriptions(tools, options = {}) {
+    const entries = tools.map((tool) => ({
+        subject: `${options.subjectPrefix ?? "tool"}:${tool.name}`,
+        text: `${tool.name}\n${tool.description ?? ""}`,
+    }));
+    const findings = [];
+    for (const entry of entries) {
+        findings.push(...scanEntry(entry));
+    }
+    findings.push(...duplicateToolFindings(tools, options.subjectPrefix ?? "tool"));
+    findings.push(...toolReferenceFindings(tools, options.subjectPrefix ?? "tool"));
+    return {
+        version: 1,
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        scannedDescriptions: tools.length,
+        findings: findings.sort((left, right) => `${left.subject}:${left.code}:${left.message}`.localeCompare(`${right.subject}:${right.code}:${right.message}`)),
+    };
+}
+export function scanFindingsToTrustIssues(scan) {
+    return scan.findings.map((finding) => ({
+        severity: finding.severity,
+        code: finding.code,
+        message: `${finding.subject}: ${finding.message}`,
+    }));
+}
+function scanEntry(entry) {
+    const findings = [];
+    if (HIDDEN_CHARACTER_PATTERN.test(entry.text)) {
+        findings.push({
+            severity: "warning",
+            code: "hidden_control_characters",
+            subject: entry.subject,
+            message: "description contains hidden or control characters",
+        });
+    }
+    for (const detector of AGENT_DIRECTED_PATTERNS) {
+        if (detector.pattern.test(entry.text)) {
+            findings.push({
+                severity: detector.severity,
+                code: detector.code,
+                subject: entry.subject,
+                message: detector.label,
+            });
+        }
+    }
+    return findings;
+}
+function duplicateToolFindings(tools, subjectPrefix) {
+    const counts = new Map();
+    for (const tool of tools) {
+        counts.set(tool.name, (counts.get(tool.name) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([name, count]) => ({
+        severity: "warning",
+        code: "duplicate_tool_name",
+        subject: `${subjectPrefix}:${name}`,
+        message: `tool name appears ${count} times in this server's tools/list response`,
+    }));
+}
+function toolReferenceFindings(tools, subjectPrefix) {
+    const names = new Set(tools.map((tool) => tool.name));
+    const findings = [];
+    for (const tool of tools) {
+        const description = tool.description ?? "";
+        for (const name of names) {
+            if (name === tool.name)
+                continue;
+            const escapedName = escapeRegExp(name);
+            const pattern = new RegExp(`\\b(always\\s+)?(call|use|invoke|run)\\s+${escapedName}\\b`, "i");
+            if (pattern.test(description)) {
+                findings.push({
+                    severity: "info",
+                    code: "cross_tool_instruction",
+                    subject: `${subjectPrefix}:${tool.name}`,
+                    message: `description instructs the agent to use sibling tool ${name}`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/search.js

@@ -0,0 +1,44 @@
+import { scoreServer, trustRankingScore } from "./trust.js";
+export function searchServers(servers, query, limit = 10) {
+    const terms = tokenize(query);
+    const knownSources = new Set(servers.map((server) => server.registrySource));
+    const sourceTerms = new Set(terms.filter((term) => knownSources.has(term)));
+    const textTerms = terms.filter((term) => !sourceTerms.has(term));
+    const scoringTerms = textTerms.length ? textTerms : terms;
+    return servers
+        .filter((server) => !sourceTerms.size || sourceTerms.has(server.registrySource))
+        .map((server) => {
+        const relevance = scoreRelevance(server, scoringTerms);
+        return { server, relevance, trust: scoreServer(server) };
+    })
+        .filter((result) => result.relevance > 0)
+        .sort((a, b) => b.relevance + trustSortScore(b) / 100 - (a.relevance + trustSortScore(a) / 100))
+        .slice(0, limit);
+}
+function trustSortScore(result) {
+    return trustRankingScore(result.trust);
+}
+function scoreRelevance(server, terms) {
+    const haystacks = [
+        { value: server.name, weight: 8 },
+        { value: server.title, weight: 6 },
+        { value: server.description, weight: 3 },
+        { value: server.registrySource, weight: 5 },
+        { value: server.packageTypes.join(" "), weight: 2 },
+        { value: server.transports.join(" "), weight: 2 },
+        { value: server.repositoryUrl ?? "", weight: 1 },
+    ];
+    return terms.reduce((score, term) => {
+        const termScore = haystacks.reduce((inner, haystack) => {
+            return inner + (haystack.value.toLowerCase().includes(term) ? haystack.weight : 0);
+        }, 0);
+        return score + termScore;
+    }, 0);
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter(Boolean);
+}