@scopeblind/verify-mcp 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @scopeblind/verify-mcp
+
+MCP server for offline verification of ScopeBlind and Veritas Acta artifacts.
+
+It is deliberately narrow:
+- verify a single signed receipt or artifact
+- verify an audit bundle offline
+- explain a signed artifact in normalized form
+- run a packaged self-test so clients can prove the verifier works
+
+This is the registry-worthy MCP surface for the verification lane. It is not a gateway, not a builder, and not a hosted verification service.
+
+## Install
+
+```bash
+npm install -g @scopeblind/verify-mcp
+```
+
+## Claude Desktop / MCP config
+
+```json
+{
+  "mcpServers": {
+    "scopeblind-verify": {
+      "command": "npx",
+      "args": ["-y", "@scopeblind/verify-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `self_test`
+Runs packaged sample verification.
+
+Returns:
+- sample receipt valid / invalid
+- sample bundle valid / invalid
+- total receipts in the sample bundle
+
+### `verify_receipt`
+Inputs:
+- `artifact_json` or `path`
+- optional `public_key_hex`
+
+Returns:
+- valid / invalid
+- type
+- format
+- issuer
+- kid
+- canonical hash
+
+### `verify_bundle`
+Inputs:
+- `bundle_json` or `path`
+
+Returns:
+- valid / invalid
+- total receipts
+- passed
+- failed
+
+### `explain_artifact`
+Inputs:
+- `artifact_json` or `path`
+
+Returns a normalized summary of:
+- type
+- format
+- issuer
+- kid
+- issued_at / timestamp
+- payload keys
+
+## Notes
+
+- No ScopeBlind servers are contacted.
+- This server verifies local JSON artifacts only.
+- `protect-mcp` remains the local policy gateway.
+- `@scopeblind/passport` remains the local pack builder.
+- `@scopeblind/red-team` remains the local benchmark runner.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@scopeblind/verify-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for offline verification of ScopeBlind and Veritas Acta artifacts.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "scopeblind-verify-mcp": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md",
+    "server.json",
+    "samples/"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@veritasacta/artifacts": "^0.2.0",
+    "zod": "^3.24.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "scopeblind",
+    "veritasacta",
+    "artifact-verification",
+    "receipts",
+    "offline-verification"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomjwxf/scopeblind-gateway.git"
+  },
+  "homepage": "https://scopeblind.com/verify",
+  "bugs": {
+    "url": "https://github.com/tomjwxf/scopeblind-gateway/issues"
+  },
+  "mcpName": "io.github.tomjwxf/verify-mcp",
+  "scripts": {
+    "check": "node --check server.js",
+    "smoke": "node test/smoke.mjs",
+    "prepublishOnly": "npm run check && npm run smoke"
+  }
+}

package/samples/sample-bundle.json

@@ -0,0 +1,78 @@
+{
+  "format": "scopeblind:audit-bundle:v1",
+  "generated_at": "2026-03-22T00:00:00Z",
+  "issuer": "protect-mcp",
+  "description": "Sample audit bundle with 3 receipts from a protect-mcp session.",
+  "verification": {
+    "signing_keys": [
+      {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
+        "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
+        "use": "sig"
+      }
+    ]
+  },
+  "receipts": [
+    {
+      "v": 2,
+      "type": "decision_receipt",
+      "algorithm": "ed25519",
+      "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
+      "issuer": "sb:test",
+      "issued_at": "2026-01-01T00:00:00Z",
+      "payload": {
+        "decision": "allow",
+        "policy_digest": "sha256:abcdef0123456789",
+        "scope": "my-service",
+        "tool": "read_database",
+        "tier": "signed-known",
+        "mode": "shadow",
+        "reason_code": "policy_match",
+        "request_id": "req_test_001"
+      },
+      "signature": "324a966f8d4e6652e2270311c9682157d5adc01f1f019d84b24a1125220869a5c5a0fc0096ed3afffaa66ac36cfbbd97e60d9c5f7ad632a2cf11c45c2c50fd0d"
+    },
+    {
+      "v": 2,
+      "type": "gateway_restraint",
+      "algorithm": "ed25519",
+      "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
+      "issuer": "sb:protect",
+      "issued_at": "2026-01-01T00:01:00Z",
+      "payload": {
+        "tool": "delete_user",
+        "decision": "deny",
+        "reason_code": "tier_insufficient",
+        "policy_digest": "sha256:abcdef0123456789",
+        "agent_id": "sb:agent:test-bot",
+        "tier": "unknown",
+        "mode": "enforce"
+      },
+      "signature": "e0acddfd57dac1d1cd1a7b48d4554c81cede6bf44aa40f97ed5cbf8825e4157ec1fb44527b0b2cc17b24e5853b2190e02e5c7a826c3919592e693f09c04fac0e"
+    },
+    {
+      "v": 2,
+      "type": "trust_ticket",
+      "algorithm": "ed25519",
+      "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
+      "issuer": "sb:trust-authority",
+      "issued_at": "2026-01-15T12:00:00Z",
+      "payload": {
+        "tier": "evidenced",
+        "scope": "production",
+        "expires_at": "2026-02-01T00:00:00Z",
+        "agent_id": "sb:agent:verified-bot",
+        "manifest_hash": "sha256:manifest_hash_example",
+        "evidence_summary": {
+          "receipt_count": 150,
+          "epoch_span": 30,
+          "issuer_count": 5
+        }
+      },
+      "signature": "c4e5b0048449d0f6757877410d3066f285dc07d1f73ec1e4f6222ec2f3a95a3953db3f3c9a3079c7a7cef837e36d522791a095884633f52d42876b1b25ae6600"
+    }
+  ],
+  "_note": "Verify with: npx @veritasacta/verify sample-bundle.json --bundle"
+}

package/samples/sample-receipt.json

@@ -0,0 +1,19 @@
+{
+  "v": 2,
+  "type": "decision_receipt",
+  "algorithm": "ed25519",
+  "kid": "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k",
+  "issuer": "sb:test",
+  "issued_at": "2026-01-01T00:00:00Z",
+  "payload": {
+    "decision": "allow",
+    "policy_digest": "sha256:abcdef0123456789",
+    "scope": "my-service",
+    "tool": "read_database",
+    "tier": "signed-known",
+    "mode": "shadow",
+    "reason_code": "policy_match",
+    "request_id": "req_test_001"
+  },
+  "signature": "324a966f8d4e6652e2270311c9682157d5adc01f1f019d84b24a1125220869a5c5a0fc0096ed3afffaa66ac36cfbbd97e60d9c5f7ad632a2cf11c45c2c50fd0d"
+}

package/server.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import {
+  verifyArtifact,
+  canonicalHash,
+  bytesToHex,
+  base64urlToBytes,
+} from '@veritasacta/artifacts';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function readJsonInput(path, raw) {
+  if (raw && raw.trim()) return JSON.parse(raw);
+  if (path && path.trim()) return JSON.parse(readFileSync(path, 'utf-8'));
+  throw new Error('Provide either raw JSON input or a file path.');
+}
+
+function isPassportEnvelope(obj) {
+  return obj && typeof obj === 'object'
+    && obj.payload && typeof obj.payload === 'object'
+    && obj.signature && typeof obj.signature === 'object'
+    && typeof obj.signature.sig === 'string';
+}
+
+function convertPassportToV1(envelope) {
+  return {
+    artifact: { ...envelope.payload, signature: envelope.signature.sig },
+    kid: envelope.signature.kid || null,
+    format: 'passport',
+  };
+}
+
+function deriveEmbeddedKey(artifact) {
+  const payload = artifact?.payload || artifact;
+  if (payload?.public_key && typeof payload.public_key === 'string' && payload.public_key.length === 64) {
+    return payload.public_key;
+  }
+  return null;
+}
+
+function formatArtifact(artifact) {
+  if (isPassportEnvelope(artifact)) return 'passport';
+  if (artifact?.v === 2) return 'v2';
+  return 'v1';
+}
+
+function getArtifactCore(artifact) {
+  if (isPassportEnvelope(artifact)) {
+    return convertPassportToV1(artifact);
+  }
+  return {
+    artifact,
+    kid: artifact?.kid || null,
+    format: formatArtifact(artifact),
+  };
+}
+
+function resolveBundleKeyMap(bundle) {
+  const keys = bundle?.verification?.signing_keys || [];
+  const map = new Map();
+  for (const jwk of keys) {
+    if (jwk?.kid && jwk?.x) {
+      map.set(jwk.kid, bytesToHex(base64urlToBytes(jwk.x)));
+    }
+  }
+  return map;
+}
+
+function verifySingle(artifact, publicKeyHex) {
+  const core = getArtifactCore(artifact);
+  const key = publicKeyHex || deriveEmbeddedKey(artifact);
+  if (!key) {
+    return {
+      valid: false,
+      error: 'no_public_key',
+      type: artifact?.type || core.artifact?.type || 'unknown',
+      format: core.format,
+      kid: core.kid,
+      issuer: artifact?.issuer || null,
+      hash: null,
+    };
+  }
+
+  const result = verifyArtifact(core.artifact, key);
+  const unsigned = { ...core.artifact };
+  delete unsigned.signature;
+
+  return {
+    valid: !!result.valid,
+    error: result.valid ? null : (result.error || 'invalid_signature'),
+    type: artifact?.type || core.artifact?.type || 'unknown',
+    format: core.format,
+    kid: core.kid,
+    issuer: artifact?.issuer || null,
+    hash: canonicalHash(unsigned),
+  };
+}
+
+function verifyBundle(bundle) {
+  if (!bundle?.receipts || !Array.isArray(bundle.receipts)) {
+    throw new Error('Invalid bundle: missing receipts array');
+  }
+  const keyMap = resolveBundleKeyMap(bundle);
+  let passed = 0;
+  const receipts = bundle.receipts.map((receipt, index) => {
+    const key = receipt?.kid ? keyMap.get(receipt.kid) : deriveEmbeddedKey(receipt);
+    const result = verifySingle(receipt, key || null);
+    if (result.valid) passed += 1;
+    return {
+      index,
+      type: result.type,
+      kid: result.kid,
+      valid: result.valid,
+      error: result.error,
+    };
+  });
+  return {
+    valid: passed === bundle.receipts.length,
+    total: bundle.receipts.length,
+    passed,
+    failed: bundle.receipts.length - passed,
+    receipts,
+  };
+}
+
+function explainArtifact(artifact) {
+  const core = getArtifactCore(artifact);
+  const payload = artifact?.payload || core.artifact?.payload || core.artifact;
+  const payloadKeys = payload && typeof payload === 'object'
+    ? Object.keys(payload).filter((k) => k !== 'signature').sort()
+    : [];
+
+  return {
+    type: artifact?.type || core.artifact?.type || 'unknown',
+    format: core.format,
+    issuer: artifact?.issuer || null,
+    kid: core.kid,
+    issued_at: artifact?.issued_at || artifact?.timestamp || payload?.issued_at || null,
+    payload_keys: payloadKeys,
+  };
+}
+
+function loadSelfTestArtifacts() {
+  return {
+    receipt: JSON.parse(readFileSync(join(__dirname, 'samples', 'sample-receipt.json'), 'utf-8')),
+    bundle: JSON.parse(readFileSync(join(__dirname, 'samples', 'sample-bundle.json'), 'utf-8')),
+    publicKeyHex: 'd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a',
+  };
+}
+
+function textResult(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+const server = new McpServer({
+  name: 'scopeblind-verify',
+  version: '0.1.0',
+  description: 'Offline verification MCP server for ScopeBlind and Veritas Acta artifacts.',
+});
+
+server.tool(
+  'self_test',
+  'Verify the packaged sample receipt and sample bundle to prove the verifier works offline.',
+  {},
+  async () => {
+    try {
+      const { receipt, bundle, publicKeyHex } = loadSelfTestArtifacts();
+      const receiptResult = verifySingle(receipt, publicKeyHex);
+      const bundleResult = verifyBundle(bundle);
+      return textResult({
+        ok: receiptResult.valid && bundleResult.valid,
+        receipt: receiptResult,
+        bundle: {
+          valid: bundleResult.valid,
+          total: bundleResult.total,
+          passed: bundleResult.passed,
+          failed: bundleResult.failed,
+        },
+        note: 'No ScopeBlind servers were contacted.',
+      });
+    } catch (error) {
+      return textResult({ ok: false, error: error.message });
+    }
+  }
+);
+
+server.tool(
+  'verify_receipt',
+  'Verify a single signed artifact or receipt using an explicit public key or any embedded public key.',
+  {
+    artifact_json: z.string().optional().describe('Raw JSON artifact string.'),
+    path: z.string().optional().describe('Path to a local JSON artifact file.'),
+    public_key_hex: z.string().optional().describe('Optional Ed25519 public key hex (64 bytes as hex).'),
+  },
+  async (args) => {
+    try {
+      const artifact = readJsonInput(args.path, args.artifact_json);
+      return textResult(verifySingle(artifact, args.public_key_hex || null));
+    } catch (error) {
+      return textResult({ ok: false, error: error.message });
+    }
+  }
+);
+
+server.tool(
+  'verify_bundle',
+  'Verify a ScopeBlind audit bundle offline using the embedded verification keys.',
+  {
+    bundle_json: z.string().optional().describe('Raw JSON bundle string.'),
+    path: z.string().optional().describe('Path to a local JSON bundle file.'),
+  },
+  async (args) => {
+    try {
+      const bundle = readJsonInput(args.path, args.bundle_json);
+      return textResult(verifyBundle(bundle));
+    } catch (error) {
+      return textResult({ ok: false, error: error.message });
+    }
+  }
+);
+
+server.tool(
+  'explain_artifact',
+  'Explain the format and top-level contents of a signed artifact without requiring a verification key.',
+  {
+    artifact_json: z.string().optional().describe('Raw JSON artifact string.'),
+    path: z.string().optional().describe('Path to a local JSON artifact file.'),
+  },
+  async (args) => {
+    try {
+      const artifact = readJsonInput(args.path, args.artifact_json);
+      return textResult(explainArtifact(artifact));
+    } catch (error) {
+      return textResult({ ok: false, error: error.message });
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.tomjwxf/verify-mcp",
+  "description": "Offline verification MCP server for ScopeBlind and Veritas Acta artifacts, including receipts, bundles, manifests, and trust tickets.",
+  "repository": {
+    "url": "https://github.com/tomjwxf/scopeblind-gateway",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@scopeblind/verify-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtime": "node",
+      "runtimeArgs": []
+    }
+  ]
+}