@proofofwork-agency/toolpin 0.2.3

package/action.yml

@@ -0,0 +1,134 @@
+name: ToolPin CI
+description: Verify an MCP lockfile with toolpin ci.
+
+inputs:
+  working-directory:
+    description: Directory that contains mcp-lock.json.
+    required: false
+    default: .
+  file:
+    description: Lockfile path, relative to working-directory.
+    required: false
+    default: mcp-lock.json
+  source:
+    description: Registry source passed to --source.
+    required: false
+    default: all
+  live:
+    description: Fetch live registry data instead of relying on local cache.
+    required: false
+    default: "true"
+  verify:
+    description: Run verification before comparing locked plans.
+    required: false
+    default: "false"
+  expect-digest:
+    description: Expected whole-lock digest from a trusted out-of-band source.
+    required: false
+    default: ""
+  signature:
+    description: Detached signature path.
+    required: false
+    default: ""
+  public-key:
+    description: Public key path used with signature.
+    required: false
+    default: ""
+  toolpin-version:
+    description: Optional npm version specifier for the @proofofwork-agency/toolpin npm package after public npm publish. Leave empty to install from this action source.
+    required: false
+    default: ""
+  policy:
+    description: Policy file path.
+    required: false
+    default: .toolpin/policy.json
+  no-policy:
+    description: Pass --no-policy and skip policy enforcement.
+    required: false
+    default: "false"
+  timeout:
+    description: Live verification timeout in milliseconds.
+    required: false
+    default: "15000"
+  skip-live-verification:
+    description: Pass --skip-live-verification when verify is enabled.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - name: Install ToolPin
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        if [[ -n "${TOOLPIN_VERSION}" ]]; then
+          npm install -g "@proofofwork-agency/toolpin@${TOOLPIN_VERSION}"
+        else
+          npm ci --prefix "$GITHUB_ACTION_PATH"
+          npm run --prefix "$GITHUB_ACTION_PATH" build
+          npm install -g "$GITHUB_ACTION_PATH"
+        fi
+      env:
+        TOOLPIN_VERSION: ${{ inputs.toolpin-version }}
+
+    - name: Run toolpin ci
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        set -euo pipefail
+
+        cmd=(toolpin ci --file "$TOOLPIN_FILE" --source "$TOOLPIN_SOURCE")
+
+        if [[ "$TOOLPIN_LIVE" == "true" ]]; then
+          cmd+=(--live)
+        fi
+
+        if [[ "$TOOLPIN_VERIFY" == "true" ]]; then
+          cmd+=(--verify --timeout "$TOOLPIN_TIMEOUT")
+        fi
+
+        if [[ "$TOOLPIN_SKIP_LIVE_VERIFICATION" == "true" ]]; then
+          cmd+=(--skip-live-verification)
+        fi
+
+        if [[ -n "$TOOLPIN_EXPECT_DIGEST" ]]; then
+          cmd+=(--expect-digest "$TOOLPIN_EXPECT_DIGEST")
+        fi
+
+        if [[ -n "$TOOLPIN_SIGNATURE" || -n "$TOOLPIN_PUBLIC_KEY" ]]; then
+          if [[ -z "$TOOLPIN_SIGNATURE" || -z "$TOOLPIN_PUBLIC_KEY" ]]; then
+            echo "ToolPin CI requires both signature and public-key when either is set." >&2
+            exit 2
+          fi
+          cmd+=(--signature "$TOOLPIN_SIGNATURE" --public-key "$TOOLPIN_PUBLIC_KEY")
+        fi
+
+        if [[ "$TOOLPIN_NO_POLICY" == "true" ]]; then
+          cmd+=(--no-policy)
+        elif [[ -n "$TOOLPIN_POLICY" ]]; then
+          cmd+=(--policy "$TOOLPIN_POLICY")
+        fi
+
+        printf 'Running:'
+        printf ' %q' "${cmd[@]}"
+        printf '\n'
+        "${cmd[@]}"
+      env:
+        TOOLPIN_FILE: ${{ inputs.file }}
+        TOOLPIN_SOURCE: ${{ inputs.source }}
+        TOOLPIN_LIVE: ${{ inputs.live }}
+        TOOLPIN_VERIFY: ${{ inputs.verify }}
+        TOOLPIN_EXPECT_DIGEST: ${{ inputs.expect-digest }}
+        TOOLPIN_SIGNATURE: ${{ inputs.signature }}
+        TOOLPIN_PUBLIC_KEY: ${{ inputs.public-key }}
+        TOOLPIN_POLICY: ${{ inputs.policy }}
+        TOOLPIN_NO_POLICY: ${{ inputs.no-policy }}
+        TOOLPIN_TIMEOUT: ${{ inputs.timeout }}
+        TOOLPIN_SKIP_LIVE_VERIFICATION: ${{ inputs.skip-live-verification }}

package/dist/canonicalJson.js

@@ -0,0 +1,38 @@
+export function canonicalJson(value, options = {}) {
+    return JSON.stringify(sortJson(value, options));
+}
+function sortJson(value, options) {
+    if (Array.isArray(value))
+        return value.map((entry) => sortJson(entry, options));
+    if (!isRecord(value))
+        return value;
+    const normalizedEntries = Object.entries(value).map(([key, child]) => [normalizeKey(key), child]);
+    ensureUniqueKeys(normalizedEntries.map(([key]) => key));
+    const entries = normalizedEntries
+        .sort(([left], [right]) => compareKeys(left, right))
+        .map(([key, child]) => [key, sortJson(child, options)])
+        .filter(([, child]) => !options.pruneEmptyObjects || !isRecord(child) || Object.keys(child).length > 0);
+    return Object.fromEntries(entries);
+}
+function normalizeKey(key) {
+    return key.normalize("NFC");
+}
+function compareKeys(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function ensureUniqueKeys(keys) {
+    const seen = new Set();
+    for (const key of keys) {
+        if (seen.has(key)) {
+            throw new Error(`Canonical JSON object has duplicate key after NFC normalization: ${key}`);
+        }
+        seen.add(key);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/capabilities.js

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./canonicalJson.js";
+const TOOLPIN_CAPABILITIES_META = "dev.toolpin/capabilities";
+const TOOLPIN_ATTESTATIONS_META = "dev.toolpin/attestations";
+export function deriveCapabilityManifest(server, options = {}) {
+    return {
+        version: 1,
+        serverName: server.name,
+        serverVersion: server.version,
+        registrySource: server.registrySource,
+        packageTypes: [...new Set(server.packageTypes)].sort(),
+        transports: [...new Set(server.transports)].sort(),
+        remoteHosts: remoteHosts(server).sort(),
+        secrets: capabilitySecrets(server).sort((left, right) => `${left.source}:${left.name}`.localeCompare(`${right.source}:${right.name}`)),
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        toolDescriptionHash: options.toolDescriptionHash,
+        toolManifestHash: options.toolManifestHash,
+        toolDescriptionScan: options.toolDescriptionScan,
+    };
+}
+export function hashToolDescriptions(tools, generatedAt = new Date().toISOString()) {
+    const normalized = tools
+        .map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    const value = createHash("sha256").update(canonicalJson(normalized)).digest("hex");
+    return {
+        algorithm: "sha256",
+        value,
+        toolCount: normalized.length,
+        generatedAt,
+    };
+}
+export function hashToolManifests(tools, generatedAt = new Date().toISOString()) {
+    const normalized = tools
+        .map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema ?? {},
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    const value = createHash("sha256").update(canonicalJson(normalized)).digest("hex");
+    return {
+        algorithm: "sha256",
+        value,
+        toolCount: normalized.length,
+        generatedAt,
+    };
+}
+export function readCapabilityManifest(server) {
+    const value = server.raw._meta?.[TOOLPIN_CAPABILITIES_META] ?? server.registryMeta?.[TOOLPIN_CAPABILITIES_META];
+    return isCapabilityManifest(value) ? value : undefined;
+}
+export function readAttestations(server) {
+    const value = server.raw._meta?.[TOOLPIN_ATTESTATIONS_META] ?? server.registryMeta?.[TOOLPIN_ATTESTATIONS_META];
+    return Array.isArray(value) ? value.filter(isAttestation) : [];
+}
+export function attestationBadge(attestation) {
+    return `${attestation.type}-declared`;
+}
+function remoteHosts(server) {
+    const hosts = [];
+    for (const remote of server.raw.remotes ?? []) {
+        try {
+            hosts.push(new URL(remote.url).host);
+        }
+        catch {
+            // Invalid URLs are reported by trust/verification; they cannot produce an egress host.
+        }
+    }
+    return [...new Set(hosts)];
+}
+function capabilitySecrets(server) {
+    const secrets = [];
+    for (const pkg of server.raw.packages ?? []) {
+        for (const variable of pkg.environmentVariables ?? []) {
+            if (variable.isSecret || variable.isRequired) {
+                secrets.push({
+                    name: variable.name,
+                    source: "env",
+                    required: variable.isRequired === true,
+                });
+            }
+        }
+    }
+    for (const remote of server.raw.remotes ?? []) {
+        for (const header of remote.headers ?? []) {
+            if (header.isSecret || header.isRequired) {
+                secrets.push({
+                    name: header.name,
+                    source: "header",
+                    required: header.isRequired === true,
+                });
+            }
+        }
+    }
+    return secrets;
+}
+export function isCapabilityManifest(value) {
+    if (!isRecord(value))
+        return false;
+    return (value.version === 1 &&
+        typeof value.serverName === "string" &&
+        typeof value.serverVersion === "string" &&
+        typeof value.registrySource === "string" &&
+        Array.isArray(value.packageTypes) &&
+        Array.isArray(value.transports) &&
+        Array.isArray(value.remoteHosts) &&
+        Array.isArray(value.secrets) &&
+        typeof value.generatedAt === "string" &&
+        (value.toolDescriptionHash === undefined || isToolDescriptionHash(value.toolDescriptionHash)) &&
+        (value.toolManifestHash === undefined || isToolManifestHash(value.toolManifestHash)) &&
+        (value.toolDescriptionScan === undefined || isToolDescriptionScan(value.toolDescriptionScan)));
+}
+function isToolDescriptionHash(value) {
+    return isToolManifestHash(value);
+}
+function isToolManifestHash(value) {
+    return (isRecord(value) &&
+        value.algorithm === "sha256" &&
+        typeof value.value === "string" &&
+        typeof value.toolCount === "number" &&
+        typeof value.generatedAt === "string");
+}
+function isToolDescriptionScan(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        typeof value.generatedAt === "string" &&
+        typeof value.scannedDescriptions === "number" &&
+        Array.isArray(value.findings));
+}
+function isAttestation(value) {
+    return isRecord(value) && typeof value.type === "string";
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/ci.js

@@ -0,0 +1,26 @@
+import { readLockfile, verifyAgainstLockfile } from "./plan.js";
+export async function verifyFrozenInstall(lockfilePath, resolveCurrentPlan) {
+    const lockfile = await readLockfile(lockfilePath);
+    const entries = Object.entries(lockfile.servers);
+    const issues = [];
+    for (const [key, locked] of entries) {
+        try {
+            const current = await resolveCurrentPlan(locked, key);
+            const verification = await verifyAgainstLockfile(current, lockfilePath);
+            if (!verification.ok) {
+                issues.push({ key, messages: verification.messages });
+            }
+        }
+        catch (error) {
+            issues.push({ key, messages: [error instanceof Error ? error.message : String(error)] });
+        }
+    }
+    if (entries.length === 0) {
+        issues.push({ key: lockfilePath, messages: ["lockfile has no server entries"] });
+    }
+    return {
+        ok: issues.length === 0,
+        checked: entries.length,
+        issues,
+    };
+}