@proofofwork-agency/toolpin 0.2.3

package/dist/secrets.js

@@ -0,0 +1,165 @@
+import { readInstalledServerConfig } from "./doctor.js";
+import { resolveConfigTarget } from "./install.js";
+import { readLockfile } from "./plan.js";
+const SECRET_PREFIXES = [
+    { label: "GitHub token", pattern: /^(ghp_|github_pat_)/ },
+    { label: "OpenAI-style token", pattern: /^sk-[A-Za-z0-9_-]{8,}/ },
+    { label: "AWS access key", pattern: /^AKIA[A-Z0-9]{12,}/ },
+    { label: "Slack token", pattern: /^xox[baprs]-/ },
+    { label: "Google API key", pattern: /^AIza[0-9A-Za-z_-]{8,}/ },
+    { label: "private key", pattern: /^-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+];
+export async function auditSecrets(lockfilePath = "mcp-lock.json", scope = "all") {
+    const lockfile = await readLockfile(lockfilePath);
+    const findings = [];
+    const entries = Object.entries(lockfile.servers);
+    for (const [key, plan] of entries) {
+        const missing = [];
+        const invalidScopes = [];
+        let foundConfig = false;
+        let foundUnreadable = false;
+        for (const currentScope of scopesToAudit(scope)) {
+            let target;
+            try {
+                target = resolveConfigTarget(plan.client, currentScope);
+            }
+            catch (error) {
+                invalidScopes.push(`${currentScope}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const actual = await readInstalledServerConfig(target.file, plan.name, plan.client);
+            if (actual.kind === "missing") {
+                missing.push({ scope: currentScope, file: target.file });
+                continue;
+            }
+            if (actual.kind === "unreadable") {
+                foundUnreadable = true;
+                findings.push({
+                    kind: "unreadable_config",
+                    key,
+                    client: plan.client,
+                    serverName: plan.name,
+                    file: target.file,
+                    scope: currentScope,
+                    message: actual.message,
+                });
+                continue;
+            }
+            foundConfig = true;
+            findings.push(...auditConfigSecrets(key, plan.client, plan.name, target.file, currentScope, actual.config, plan.capabilityManifest?.secrets ?? []));
+        }
+        if (!foundConfig && !foundUnreadable && missing.length > 0) {
+            findings.push({
+                kind: "missing_config",
+                key,
+                client: plan.client,
+                serverName: plan.name,
+                file: missing.map((entry) => entry.file).join(", "),
+                scope: scope === "all" ? undefined : missing[0]?.scope,
+                message: scope === "all"
+                    ? `missing ${plan.client} config entry for ${plan.name} in checked scopes: ${missing.map((entry) => entry.scope).join(", ")}`
+                    : `missing ${plan.client} config entry for ${plan.name}`,
+            });
+            continue;
+        }
+        if (!foundConfig && !foundUnreadable && missing.length === 0 && invalidScopes.length > 0) {
+            findings.push({
+                kind: "invalid_scope",
+                key,
+                client: plan.client,
+                serverName: plan.name,
+                file: "",
+                message: `cannot audit ${plan.client} at ${scope} scope: ${invalidScopes.join("; ")}`,
+            });
+        }
+    }
+    return {
+        ok: findings.length === 0,
+        checked: entries.length,
+        findings,
+    };
+}
+function auditConfigSecrets(key, client, serverName, file, scope, config, secretHints) {
+    const findings = [];
+    const plaintextKeys = new Set();
+    for (const secret of secretHints) {
+        const value = secretValue(config, secret);
+        if (typeof value !== "string" || !value)
+            continue;
+        if (!isSecretReference(value, secret.name)) {
+            plaintextKeys.add(`${secret.source}:${secret.name}`);
+            findings.push({
+                kind: "plaintext_secret",
+                key,
+                client,
+                serverName,
+                file,
+                scope,
+                secretName: secret.name,
+                secretSource: secret.source,
+                message: `${secret.source}:${secret.name} is stored as a plaintext value; replace it with a placeholder or external secret reference`,
+                redactedValue: redact(value),
+            });
+        }
+    }
+    for (const candidate of collectSecretCandidates(config)) {
+        if (plaintextKeys.has(`${candidate.source}:${candidate.name}`))
+            continue;
+        const matched = SECRET_PREFIXES.find((prefix) => prefix.pattern.test(candidate.value));
+        if (matched) {
+            findings.push({
+                kind: "secret_prefix",
+                key,
+                client,
+                serverName,
+                file,
+                scope,
+                secretName: candidate.name,
+                secretSource: candidate.source,
+                message: `${candidate.source}:${candidate.name} resembles a ${matched.label}; replace it with a placeholder or external secret reference`,
+                redactedValue: redact(candidate.value),
+            });
+        }
+    }
+    return findings;
+}
+function scopesToAudit(scope) {
+    return scope === "all" ? ["project", "global"] : [scope];
+}
+function secretValue(config, secret) {
+    const root = asRecord(config);
+    if (secret.source === "env")
+        return asRecord(root.env)[secret.name] ?? asRecord(root.environment)[secret.name];
+    return asRecord(root.headers)[secret.name] ?? asRecord(root.http_headers)[secret.name] ?? asRecord(asRecord(root.requestOptions).headers)[secret.name];
+}
+function collectSecretCandidates(config) {
+    const root = asRecord(config);
+    return [
+        ...valuesFromObject(asRecord(root.env), "env"),
+        ...valuesFromObject(asRecord(root.environment), "env"),
+        ...valuesFromObject(asRecord(root.headers), "header"),
+        ...valuesFromObject(asRecord(root.http_headers), "header"),
+        ...valuesFromObject(asRecord(asRecord(root.requestOptions).headers), "header"),
+    ];
+}
+function valuesFromObject(value, source) {
+    return Object.entries(value).flatMap(([name, child]) => (typeof child === "string" ? [{ source, name, value: child }] : []));
+}
+function isSecretReference(value, name) {
+    const trimmed = value.trim();
+    const escaped = escapeRegExp(name);
+    return (trimmed === `<${name}>` ||
+        new RegExp(`^\\$\\{env:${escaped}\\}$`).test(trimmed) ||
+        new RegExp(`^\\$\\{${escaped}\\}$`).test(trimmed) ||
+        new RegExp(`^\\$\\{\\{\\s*secrets\\.${escaped}\\s*\\}\\}$`).test(trimmed) ||
+        /^(op|vault|doppler):\/\//.test(trimmed));
+}
+function redact(_value) {
+    return "[REDACTED]";
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function asRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/dist/signing.js

@@ -0,0 +1,146 @@
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { readLockfileDigest } from "./plan.js";
+import { readPolicyDigest } from "./policy.js";
+import { canonicalJson } from "./canonicalJson.js";
+export async function signLockfile(lockfilePath = "mcp-lock.json", privateKeyPath, signaturePath = "mcp-lock.sig", options = {}) {
+    const lockfileDigest = await readLockfileDigest(lockfilePath);
+    const policyDigest = options.policyPath ? await readPolicyDigest(options.policyPath) : undefined;
+    const key = createPrivateKey(await readFile(privateKeyPath, "utf8"));
+    const publicKeyFingerprint = keyFingerprint(createPublicKey(key));
+    const payload = signingPayload({
+        lockfileDigest,
+        policyDigest,
+        publicKeyFingerprint,
+        signedAt: new Date().toISOString(),
+    });
+    const signature = sign(null, Buffer.from(canonicalJson(payload), "utf8"), key).toString("base64");
+    const envelope = {
+        schema: "dev.toolpin.lock-signature",
+        version: 2,
+        algorithm: "ed25519",
+        lockfileDigest,
+        ...(policyDigest ? { policyDigest } : {}),
+        publicKeyFingerprint,
+        signedAt: payload.signedAt,
+        signature,
+    };
+    await writeFile(signaturePath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+    return envelope;
+}
+export async function verifyLockfileSignature(lockfilePath = "mcp-lock.json", publicKeyPath, signaturePath = "mcp-lock.sig", options = {}) {
+    const actualDigest = await readLockfileDigest(lockfilePath);
+    const actualPolicyDigest = options.policyPath ? await readPolicyDigest(options.policyPath) : undefined;
+    const envelope = await readSignatureEnvelope(signaturePath);
+    if (envelope.lockfileDigest !== actualDigest) {
+        return {
+            ok: false,
+            lockfileDigest: actualDigest,
+            signatureDigest: envelope.lockfileDigest,
+            message: `Lockfile digest mismatch: signature covers ${envelope.lockfileDigest}, current lockfile is ${actualDigest}`,
+        };
+    }
+    if (envelope.policyDigest !== actualPolicyDigest) {
+        return {
+            ok: false,
+            lockfileDigest: actualDigest,
+            signatureDigest: envelope.lockfileDigest,
+            policyDigest: actualPolicyDigest,
+            message: `Policy digest mismatch: signature covers ${envelope.policyDigest ?? "no policy"}, current policy is ${actualPolicyDigest ?? "no policy"}`,
+        };
+    }
+    const key = createPublicKey(await readFile(publicKeyPath, "utf8"));
+    const actualFingerprint = keyFingerprint(key);
+    if (envelope.publicKeyFingerprint !== actualFingerprint) {
+        return {
+            ok: false,
+            lockfileDigest: actualDigest,
+            signatureDigest: envelope.lockfileDigest,
+            policyDigest: actualPolicyDigest,
+            publicKeyFingerprint: actualFingerprint,
+            message: `Public key fingerprint mismatch: signature requires ${envelope.publicKeyFingerprint}, provided key is ${actualFingerprint}`,
+        };
+    }
+    const payload = signingPayload({
+        lockfileDigest: envelope.lockfileDigest,
+        policyDigest: envelope.policyDigest,
+        publicKeyFingerprint: envelope.publicKeyFingerprint,
+        signedAt: envelope.signedAt,
+    });
+    const valid = verify(null, Buffer.from(canonicalJson(payload), "utf8"), key, Buffer.from(envelope.signature, "base64"));
+    return {
+        ok: valid,
+        lockfileDigest: actualDigest,
+        signatureDigest: envelope.lockfileDigest,
+        policyDigest: actualPolicyDigest,
+        publicKeyFingerprint: actualFingerprint,
+        message: valid ? "Signature valid." : "Signature verification failed.",
+    };
+}
+async function readSignatureEnvelope(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid lock signature JSON in ${path}: ${error.message}`);
+        }
+        throw error;
+    }
+    return parseSignatureEnvelope(parsed, path);
+}
+function parseSignatureEnvelope(value, path) {
+    if (!isRecord(value))
+        throw new Error(`Invalid lock signature schema in ${path}: expected object`);
+    if (value.schema !== "dev.toolpin.lock-signature")
+        throw new Error(`Invalid lock signature schema in ${path}: unsupported schema`);
+    if (value.version !== 2)
+        throw new Error(`Invalid lock signature schema in ${path}: unsupported version`);
+    if (value.algorithm !== "ed25519")
+        throw new Error(`Invalid lock signature schema in ${path}: unsupported algorithm`);
+    if (typeof value.lockfileDigest !== "string" || !value.lockfileDigest.startsWith("sha256-")) {
+        throw new Error(`Invalid lock signature schema in ${path}: invalid lockfileDigest`);
+    }
+    if (value.policyDigest !== undefined && (typeof value.policyDigest !== "string" || !value.policyDigest.startsWith("sha256-"))) {
+        throw new Error(`Invalid lock signature schema in ${path}: invalid policyDigest`);
+    }
+    if (typeof value.publicKeyFingerprint !== "string" || !value.publicKeyFingerprint.startsWith("sha256-")) {
+        throw new Error(`Invalid lock signature schema in ${path}: invalid publicKeyFingerprint`);
+    }
+    if (typeof value.signedAt !== "string")
+        throw new Error(`Invalid lock signature schema in ${path}: invalid signedAt`);
+    if (typeof value.signature !== "string" || !value.signature)
+        throw new Error(`Invalid lock signature schema in ${path}: invalid signature`);
+    return {
+        schema: "dev.toolpin.lock-signature",
+        version: 2,
+        algorithm: "ed25519",
+        lockfileDigest: value.lockfileDigest,
+        policyDigest: value.policyDigest,
+        publicKeyFingerprint: value.publicKeyFingerprint,
+        signedAt: value.signedAt,
+        signature: value.signature,
+    };
+}
+function signingPayload(input) {
+    return {
+        schema: "dev.toolpin.lock-signature",
+        version: 2,
+        algorithm: "ed25519",
+        lockfileDigest: input.lockfileDigest,
+        ...(input.policyDigest ? { policyDigest: input.policyDigest } : {}),
+        publicKeyFingerprint: input.publicKeyFingerprint,
+        signedAt: input.signedAt,
+    };
+}
+function keyFingerprint(key) {
+    const der = key.export({ type: "spki", format: "der" });
+    return `sha256-${createHash("sha256").update(der).digest("base64")}`;
+}
+export async function readPublicKeyFingerprint(publicKeyPath) {
+    return keyFingerprint(createPublicKey(await readFile(publicKeyPath, "utf8")));
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/tester.js

@@ -0,0 +1,240 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { selectLaunchTarget } from "./config.js";
+import { TOOLPIN_VERSION } from "./version.js";
+export async function testServer(server, timeoutMs = 15000) {
+    const startedAt = Date.now();
+    const launch = selectLaunchTarget(server);
+    if (!launch) {
+        return fail(server, "none", startedAt, `No launch target is available for ${server.name}.`);
+    }
+    let client;
+    try {
+        if (launch.kind === "remote") {
+            const headers = resolveRemoteHeaders(launch.remote);
+            if (headers.missing.length) {
+                return fail(server, `remote:${launch.remote.type}`, startedAt, `Missing required header/env value: ${headers.missing.join(", ")}`);
+            }
+            const transport = launch.remote.type === "sse"
+                ? new SSEClientTransport(new URL(launch.remote.url), { requestInit: { headers: headers.values } })
+                : new StreamableHTTPClientTransport(new URL(launch.remote.url), { requestInit: { headers: headers.values } });
+            client = new Client({ name: "toolpin", version: TOOLPIN_VERSION });
+            await withTimeout(client.connect(transport), timeoutMs, "Timed out connecting to remote MCP server.");
+        }
+        else {
+            const local = packageToStdio(launch.pkg);
+            if (local.missing.length) {
+                return fail(server, `stdio:${local.command}`, startedAt, `Missing required env value: ${local.missing.join(", ")}`);
+            }
+            const transport = new StdioClientTransport({
+                command: local.command,
+                args: local.args,
+                env: { ...definedProcessEnv(), ...local.env },
+                stderr: "pipe",
+            });
+            client = new Client({ name: "toolpin", version: TOOLPIN_VERSION });
+            await withTimeout(client.connect(transport), timeoutMs, "Timed out starting local MCP server.");
+        }
+        const response = await withTimeout(client.listTools(), timeoutMs, "Timed out listing MCP tools.");
+        const tools = response.tools.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }));
+        return {
+            ok: true,
+            serverName: server.name,
+            target: launch.kind === "remote" ? `remote:${launch.remote.type}` : `stdio:${launch.pkg.registryType}`,
+            durationMs: Date.now() - startedAt,
+            tools,
+            message: `Connected and listed ${tools.length} tool(s).`,
+        };
+    }
+    catch (error) {
+        return fail(server, launch.kind === "remote" ? `remote:${launch.remote.type}` : `stdio:${launch.pkg.registryType}`, startedAt, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await client?.close().catch(() => undefined);
+    }
+}
+export async function testInstalledClientConfig(serverName, config, timeoutMs = 15000) {
+    const startedAt = Date.now();
+    const launch = installedConfigToLaunch(config);
+    if (!launch) {
+        return {
+            ok: false,
+            serverName,
+            target: "installed-config",
+            durationMs: Date.now() - startedAt,
+            tools: [],
+            message: `No stdio or remote launch target is available in the installed config for ${serverName}.`,
+        };
+    }
+    let client;
+    try {
+        if (launch.kind === "remote") {
+            const transport = launch.type === "sse"
+                ? new SSEClientTransport(new URL(launch.url), { requestInit: { headers: launch.headers } })
+                : new StreamableHTTPClientTransport(new URL(launch.url), { requestInit: { headers: launch.headers } });
+            client = new Client({ name: "toolpin", version: TOOLPIN_VERSION });
+            await withTimeout(client.connect(transport), timeoutMs, "Timed out connecting to installed remote MCP server.");
+        }
+        else {
+            const transport = new StdioClientTransport({
+                command: launch.command,
+                args: launch.args,
+                env: { ...definedProcessEnv(), ...launch.env },
+                stderr: "pipe",
+            });
+            client = new Client({ name: "toolpin", version: TOOLPIN_VERSION });
+            await withTimeout(client.connect(transport), timeoutMs, "Timed out starting installed local MCP server.");
+        }
+        const response = await withTimeout(client.listTools(), timeoutMs, "Timed out listing MCP tools.");
+        const tools = response.tools.map((tool) => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }));
+        return {
+            ok: true,
+            serverName,
+            target: launch.kind === "remote" ? `installed-remote:${launch.type}` : `installed-stdio:${launch.command}`,
+            durationMs: Date.now() - startedAt,
+            tools,
+            message: `Connected and listed ${tools.length} tool(s).`,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            serverName,
+            target: launch.kind === "remote" ? `installed-remote:${launch.type}` : `installed-stdio:${launch.command}`,
+            durationMs: Date.now() - startedAt,
+            tools: [],
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await client?.close().catch(() => undefined);
+    }
+}
+function installedConfigToLaunch(config) {
+    const record = asRecord(config);
+    const url = firstString(record.url, record.httpUrl, record.serverUrl);
+    if (url) {
+        const headers = asStringRecord(record.headers) ?? asStringRecord(record.http_headers) ?? asStringRecord(asRecord(record.requestOptions).headers) ?? {};
+        return { kind: "remote", type: typeof record.type === "string" ? record.type : "streamable-http", url, headers };
+    }
+    const commandArray = Array.isArray(record.command) ? record.command.filter((value) => typeof value === "string") : undefined;
+    const command = typeof record.command === "string" ? record.command : commandArray?.[0];
+    if (!command)
+        return undefined;
+    const args = Array.isArray(record.args)
+        ? record.args.filter((value) => typeof value === "string")
+        : commandArray?.slice(1) ?? [];
+    const env = asStringRecord(record.env) ?? asStringRecord(record.environment) ?? {};
+    return { kind: "stdio", command, args, env };
+}
+function packageToStdio(pkg) {
+    const env = resolvePackageEnv(pkg.environmentVariables ?? []);
+    if (typeof pkg.command === "string" && pkg.command.length > 0) {
+        return { command: pkg.command, args: Array.isArray(pkg.args) ? pkg.args.filter(isNonEmptyString) : [], env: env.values, missing: env.missing };
+    }
+    const packageArgs = Array.isArray(pkg.packageArguments) ? pkg.packageArguments.filter(isNonEmptyString) : [];
+    switch (pkg.registryType) {
+        case "npm": {
+            const spec = pkg.version ? `${pkg.identifier}@${pkg.version}` : pkg.identifier;
+            return pkg.runtimeHint === "bun"
+                ? { command: "bunx", args: [spec, ...packageArgs], env: env.values, missing: env.missing }
+                : { command: "npx", args: ["-y", spec, ...packageArgs], env: env.values, missing: env.missing };
+        }
+        case "pypi": {
+            const spec = pkg.version ? `${pkg.identifier}==${pkg.version}` : pkg.identifier;
+            return { command: "uvx", args: [spec], env: env.values, missing: env.missing };
+        }
+        case "nuget": {
+            const spec = pkg.version ? `${pkg.identifier}@${pkg.version}` : pkg.identifier;
+            return { command: "dnx", args: [spec], env: env.values, missing: env.missing };
+        }
+        case "cargo":
+            return { command: pkg.identifier, args: packageArgs, env: env.values, missing: env.missing };
+        case "oci":
+            return { command: "docker", args: ["run", "--rm", "-i", pkg.identifier], env: env.values, missing: env.missing };
+        case "mcpb":
+            return { command: "mcpb", args: ["run", pkg.identifier], env: env.values, missing: env.missing };
+        default:
+            return { command: pkg.identifier, args: packageArgs, env: env.values, missing: env.missing };
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function resolvePackageEnv(variables) {
+    const values = {};
+    const missing = [];
+    for (const variable of variables) {
+        const current = process.env[variable.name] ?? variable.default;
+        if (current) {
+            values[variable.name] = current;
+        }
+        else if (variable.isRequired !== false) {
+            missing.push(variable.name);
+        }
+    }
+    return { values, missing };
+}
+function resolveRemoteHeaders(remote) {
+    const values = {};
+    const missing = [];
+    for (const header of remote.headers ?? []) {
+        const rawValue = typeof header.value === "string" ? header.value : undefined;
+        const envName = typeof header.env === "string" ? header.env : extractEnvName(rawValue);
+        const envValue = envName ? process.env[envName] : process.env[header.name];
+        const resolved = rawValue && envName && envValue ? rawValue.replace(`\${${envName}}`, envValue) : envValue;
+        if (resolved) {
+            values[header.name] = resolved;
+        }
+        else if (header.isRequired !== false) {
+            missing.push(envName ?? header.name);
+        }
+    }
+    return { values, missing };
+}
+function extractEnvName(value) {
+    const match = value?.match(/\$\{([^}]+)\}/);
+    return match?.[1];
+}
+function definedProcessEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter((entry) => typeof entry[1] === "string"));
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function asStringRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length ? Object.fromEntries(entries) : {};
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+async function withTimeout(promise, timeoutMs, message) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function fail(server, target, startedAt, message) {
+    return {
+        ok: false,
+        serverName: server.name,
+        target,
+        durationMs: Date.now() - startedAt,
+        tools: [],
+        message,
+    };
+}