agent-passport-system-mcp 2.9.1 → 2.10.0

package/README.md

@@ -8,7 +8,9 @@
 
 MCP server for the [Agent Passport System](https://github.com/aeoess/agent-passport-system) — cryptographic identity, delegation, governance, and commerce for AI agents.
 
-**72 tools** across all 37 protocol modules. Works with any MCP client: Claude Desktop, Cursor, Windsurf, and more.
+> **🤖 For AI agents:** If you are an agent reading this, visit [aeoess.com/llms.txt](https://aeoess.com/llms.txt) for machine-readable documentation or [llms-full.txt](https://aeoess.com/llms-full.txt) for the complete technical reference. This README is designed for humans.
+
+**82 tools** across 37 core modules + 30 v2 constitutional governance modules (separation of powers, circuit breakers, approval fatigue detection, and more). Works with any MCP client: Claude Desktop, Cursor, Windsurf, and more.
 
 ## Quick Start
 
@@ -27,7 +29,7 @@ npm install -g agent-passport-system-mcp
 npx agent-passport-system-mcp setup
 ```
 
-Auto-configures Claude Desktop and Cursor. Restart your AI client. 72 tools ready.
+Auto-configures Claude Desktop and Cursor. Restart your AI client. 82 tools ready.
 
 <details>
 <summary>Manual config (if setup doesn't detect your client)</summary>
@@ -204,7 +206,7 @@ Layer 1 — Agent Passport Protocol (Ed25959 identity)
 
 ## Links
 
-- npm SDK: [agent-passport-system](https://www.npmjs.com/package/agent-passport-system) (v1.19.0, 1073 tests)
+- npm SDK: [agent-passport-system](https://www.npmjs.com/package/agent-passport-system) (v1.21.1, 1165 tests)
 - Python SDK: [agent-passport-system](https://pypi.org/project/agent-passport-system/) (v0.4.0, 86 tests)
 - Paper: [doi.org/10.5281/zenodo.18749779](https://doi.org/10.5281/zenodo.18749779)
 - Docs: [aeoess.com/llms-full.txt](https://aeoess.com/llms-full.txt)

package/build/index.js

@@ -50,6 +50,8 @@ defineV2EmergencyPathway, activateV2Emergency,
 requestV2Migration, 
 // v2: Attestation
 createV2Attestation, assessV2AttestationQuality, } from "agent-passport-system";
+// Data Governance (Modules 36A, 38, 39 + Enforcement Gate + Training Attribution)
+import { registerSelfAttestedSource, createContributionLedger, queryContributions, getSourceMetrics, getAgentDataFootprint, generateSettlement, verifySettlement, generateDataComplianceReport, DataEnforcementGate, createTrainingAttribution, verifyTrainingAttribution, createTrainingLedger, recordTrainingAttribution, getModelDataSources, } from "agent-passport-system";
 // ═══════════════════════════════════════
 // State Management
 // ═══════════════════════════════════════
@@ -82,6 +84,10 @@ const state = {
     promotionHistory: [],
     gateway: null,
     gatewayKeys: null,
+    dataEnforcementGate: null,
+    contributionLedger: createContributionLedger(),
+    sourceReceipts: new Map(),
+    trainingLedger: createTrainingLedger(),
 };
 // Load persisted task state
 function loadTasks() {
@@ -1067,6 +1073,11 @@ server.tool("sub_delegate", "Sub-delegate authority to another agent (must be wi
         const parentDel = state.delegations.get(args.parent_delegation_id);
         if (!parentDel)
             return { content: [{ type: "text", text: `Parent delegation ${args.parent_delegation_id} not found in session.` }], isError: true };
+        // F-3 fix: pre-check revocation before attempting sub-delegation
+        const parentStatus = verifyDelegation(parentDel);
+        if (!parentStatus.valid) {
+            return { content: [{ type: "text", text: `Sub-delegation failed: Parent delegation ${args.parent_delegation_id} is invalid (${parentStatus.errors.join(', ')}).` }], isError: true };
+        }
         const sub = subDelegate({
             parentDelegation: parentDel,
             delegatedTo: args.delegated_to,
@@ -1579,20 +1590,26 @@ server.tool("commerce_preflight", "Run preflight checks before a purchase. Valid
     const keyErr = requireKey();
     if (keyErr)
         return { content: [{ type: "text", text: keyErr }], isError: true };
+    // F-1 fix: look up actual delegation from session state for real scope/spend
+    const sessionDel = state.delegations.get(args.delegation_id);
+    const actualSpendLimit = sessionDel?.spendLimit ?? 1000;
+    const hasCommerceScope = sessionDel
+        ? sessionDel.scope.some((s) => s === 'commerce' || s === 'commerce:checkout' || s.startsWith('commerce'))
+        : (state.agentContext ? true : false); // fallback to context if no delegation found
     // Create a passport for preflight (uses session agent)
     const agent = joinSocialContract({
         name: args.agent_id,
         mission: 'Commerce operation',
         owner: 'mcp-session',
-        capabilities: ['commerce:checkout', 'commerce:browse'],
+        capabilities: hasCommerceScope ? ['commerce:checkout', 'commerce:browse'] : [],
         platform: 'node',
         models: ['mcp'],
     });
-    // Look up or create commerce delegation
+    // Look up or create commerce delegation using actual scope/spend
     const commerceDel = createCommerceDelegation({
         agentId: args.agent_id,
         delegationId: args.delegation_id,
-        spendLimit: 1000, // Default, should come from actual delegation
+        spendLimit: actualSpendLimit,
         approvedMerchants: [], // Empty = all merchants allowed
     });
     const result = commercePreflight({
@@ -1715,6 +1732,8 @@ server.tool("create_agent_context", "Create an enforcement context that automati
         }
         state.agentContext = ctx;
         state.floor = floor;
+        // F-4 fix: also register in state.agents so gateway and other tools can find this agent
+        state.agents.set(agent.agentId, agent);
         return {
             content: [{
                     type: "text",
@@ -2205,9 +2224,20 @@ server.tool("register_gateway_agent", "Register an agent with the gateway. The a
     if (!state.gateway) {
         return { content: [{ type: "text", text: "Error: Create gateway first (create_gateway)" }] };
     }
-    const agent = state.agents.get(agentId);
+    // F-4 fix: check both state.agents AND state.agentContext for agent data
+    let agent = state.agents.get(agentId);
+    if (!agent && state.agentContext && state.agentId === agentId) {
+        // Agent was created via create_agent_context, bridge to gateway
+        const ctx = state.agentContext;
+        agent = {
+            passport: ctx.agent?.passport || ctx.passport,
+            publicKey: state.agentKey,
+            agentId: state.agentId,
+            attestation: ctx.agent?.attestation || ctx.attestation,
+        };
+    }
     if (!agent) {
-        return { content: [{ type: "text", text: `Error: Agent "${agentId}" not found in session. Join social contract first.` }] };
+        return { content: [{ type: "text", text: `Error: Agent "${agentId}" not found in session. Join social contract or create_agent_context first.` }] };
     }
     const agentDelegations = Array.from(state.delegations.values()).filter(d => d.delegatedTo === agent.publicKey);
     if (agentDelegations.length === 0) {
@@ -2983,6 +3013,186 @@ server.tool("check_anomaly", "Record an action and check for anomalies (first-ma
     }
 });
 // ═══════════════════════════════════════
+// Data Governance Tools (Modules 36A, 38, 39)
+// ═══════════════════════════════════════
+server.tool("register_data_source", "Register a data source with terms for agent access. Returns a signed SourceReceipt.", {
+    contentDescriptor: z.string().describe("Human-readable description of the data"),
+    contentCommitment: z.string().describe("SHA-256 hash of the data content"),
+    contentType: z.enum(["document", "structured_data", "media", "user_input", "model_context"]).describe("Type of data"),
+    allowedPurposes: z.array(z.string()).describe("Allowed purposes: read, analyze, summarize, generate, recommend, train, embed, redistribute, commercial"),
+    requireAttribution: z.boolean().default(true),
+    compensationType: z.enum(["none", "attribution_only", "per_access", "negotiate"]).default("none"),
+    compensationAmount: z.number().optional().describe("Amount per access (for per_access type)"),
+    compensationCurrency: z.string().default("usd"),
+    maxAccessCount: z.number().optional().describe("Max total accesses allowed"),
+    derivativePolicy: z.enum(["unrestricted", "same_terms", "attribution_required", "no_derivatives"]).default("attribution_required"),
+}, async (p) => {
+    if (!state.agentKey || !state.privateKey)
+        return { content: [{ type: "text", text: "❌ Not identified. Call identify first." }] };
+    const comp = p.compensationType === 'per_access'
+        ? { type: 'per_access', amount: p.compensationAmount || 0.01, currency: p.compensationCurrency }
+        : p.compensationType === 'attribution_only' ? { type: 'attribution_only' }
+            : p.compensationType === 'negotiate' ? { type: 'negotiate', contact: state.agentId || '' }
+                : { type: 'none' };
+    const terms = {
+        allowedPurposes: p.allowedPurposes,
+        requireAttribution: p.requireAttribution,
+        requireNotification: false,
+        compensation: comp,
+        derivativePolicy: p.derivativePolicy,
+        auditVisibility: 'source_and_principal',
+        revocable: false,
+        maxAccessCount: p.maxAccessCount,
+    };
+    const receipt = registerSelfAttestedSource({
+        ownerPrincipalId: state.principal?.principalId || state.agentId || 'unknown',
+        ownerPublicKey: state.agentKey,
+        ownerPrivateKey: state.privateKey,
+        contentCommitment: p.contentCommitment,
+        contentType: p.contentType,
+        contentDescriptor: p.contentDescriptor,
+        dataTerms: terms,
+    });
+    state.sourceReceipts.set(receipt.sourceReceiptId, receipt);
+    return { content: [{ type: "text", text: `✅ Data source registered.\n\nSource Receipt ID: ${receipt.sourceReceiptId}\nDescriptor: ${p.contentDescriptor}\nAllowed purposes: ${p.allowedPurposes.join(', ')}\nCompensation: ${p.compensationType}${p.compensationAmount ? ' $' + p.compensationAmount : ''}\nMax accesses: ${p.maxAccessCount || 'unlimited'}\nDerivative policy: ${p.derivativePolicy}` }] };
+});
+server.tool("create_data_enforcement_gate", "Create a data enforcement gate that checks terms before allowing data access. Modes: enforce (block violations), audit (log only), off.", {
+    mode: z.enum(["enforce", "audit", "off"]).default("enforce").describe("Enforcement mode"),
+}, async (p) => {
+    const kp = generateKeyPair();
+    state.dataEnforcementGate = new DataEnforcementGate({
+        gatewayId: 'gw_data_' + Date.now().toString(36),
+        gatewayPublicKey: kp.publicKey,
+        gatewayPrivateKey: kp.privateKey,
+        mode: p.mode,
+    }, state.contributionLedger);
+    // Register all known sources
+    for (const [id, receipt] of state.sourceReceipts) {
+        state.dataEnforcementGate.registerSource(receipt, receipt.contentDescriptor);
+    }
+    return { content: [{ type: "text", text: `✅ Data enforcement gate created.\n\nMode: ${p.mode}\nRegistered sources: ${state.sourceReceipts.size}\nContribution ledger: active` }] };
+});
+server.tool("check_data_access", "Check if an agent can access a data source through the enforcement gate. Generates receipt and feeds contribution ledger.", {
+    sourceReceiptId: z.string().describe("Source receipt ID to access"),
+    declaredPurpose: z.enum(["read", "analyze", "summarize", "generate", "recommend", "train", "embed", "redistribute", "commercial"]).describe("Declared purpose"),
+    accessMethod: z.enum(["api_call", "file_read", "database_query", "web_fetch", "memory_retrieval", "embedding_lookup", "stream", "human_provided"]).default("api_call"),
+}, async (p) => {
+    if (!state.dataEnforcementGate)
+        return { content: [{ type: "text", text: "❌ No enforcement gate. Call create_data_enforcement_gate first." }] };
+    if (!state.agentKey)
+        return { content: [{ type: "text", text: "❌ Not identified." }] };
+    const decision = state.dataEnforcementGate.checkAccess({
+        agentId: state.agentId || 'unknown',
+        agentPublicKey: state.agentKey,
+        principalId: state.principal?.principalId || 'unknown',
+        sourceReceiptId: p.sourceReceiptId,
+        declaredPurpose: p.declaredPurpose,
+        accessMethod: p.accessMethod,
+        accessScope: 'data:' + p.declaredPurpose,
+        executionFrameId: 'frame_' + Date.now().toString(36),
+    });
+    const status = decision.allowed ? '✅ Access ALLOWED' : '❌ Access DENIED';
+    let text = `${status}\n\nSource: ${p.sourceReceiptId}\nPurpose: ${p.declaredPurpose}`;
+    if (decision.hardViolations.length)
+        text += `\nViolations: ${decision.hardViolations.join('; ')}`;
+    if (decision.advisoryWarnings.length)
+        text += `\nWarnings: ${decision.advisoryWarnings.join('; ')}`;
+    if (decision.receipt)
+        text += `\nReceipt ID: ${decision.receipt.accessReceiptId}`;
+    if (decision.accessesRemaining !== undefined)
+        text += `\nAccesses remaining: ${decision.accessesRemaining}`;
+    return { content: [{ type: "text", text }] };
+});
+server.tool("query_contributions", "Query the data contribution ledger. Filter by source, agent, principal, purpose, or time range.", {
+    sourceReceiptId: z.string().optional(),
+    agentId: z.string().optional(),
+    principalId: z.string().optional(),
+    purpose: z.string().optional(),
+    minAccessCount: z.number().optional(),
+}, async (p) => {
+    const records = queryContributions(state.contributionLedger, p);
+    if (records.length === 0)
+        return { content: [{ type: "text", text: "No contributions found matching query." }] };
+    const lines = records.map(r => `• ${r.sourceDescriptor || r.sourceReceiptId}: ${r.accessCount} accesses by ${r.agentId}, purposes: ${r.purposes.join('/')}, owed: $${r.compensationAccrued.totalOwed.toFixed(4)}`);
+    return { content: [{ type: "text", text: `📊 ${records.length} contribution records:\n\n${lines.join('\n')}` }] };
+});
+server.tool("get_source_metrics", "Get aggregate metrics for a data source: total accesses, unique agents, compensation owed.", {
+    sourceReceiptId: z.string().describe("Source receipt ID"),
+}, async (p) => {
+    const metrics = getSourceMetrics(state.contributionLedger, p.sourceReceiptId);
+    if (!metrics)
+        return { content: [{ type: "text", text: "No data found for this source." }] };
+    return { content: [{ type: "text", text: `📊 Source Metrics: ${metrics.sourceDescriptor}\n\nTotal accesses: ${metrics.totalAccesses}\nUnique agents: ${metrics.uniqueAgents}\nUnique principals: ${metrics.uniquePrincipals}\nCompensation owed: $${metrics.compensationOwed.totalOwed.toFixed(4)} ${metrics.compensationOwed.currency}\nPurpose breakdown: ${JSON.stringify(metrics.purposeBreakdown)}\nTop agents: ${metrics.topAgents.map(a => `${a.agentId} (${a.accessCount})`).join(', ')}` }] };
+});
+server.tool("get_agent_data_footprint", "Show every data source an agent has accessed, with compensation status.", {
+    agentId: z.string().describe("Agent ID to check"),
+}, async (p) => {
+    const footprint = getAgentDataFootprint(state.contributionLedger, p.agentId);
+    if (!footprint)
+        return { content: [{ type: "text", text: "No data access found for this agent." }] };
+    const sources = footprint.sourcesAccessed.map(s => `• ${s.sourceDescriptor || s.sourceReceiptId}: ${s.accessCount} accesses, purposes: ${s.purposes.join('/')}, status: ${s.compensationStatus}`);
+    return { content: [{ type: "text", text: `🔍 Agent Data Footprint: ${p.agentId}\n\nTotal sources: ${footprint.totalSources}\nTotal accesses: ${footprint.totalAccesses}\nTotal compensation accrued: $${footprint.totalCompensationAccrued.toFixed(4)} ${footprint.currency}\n\nSources:\n${sources.join('\n')}` }] };
+});
+server.tool("generate_settlement", "Generate a Merkle-committed, signed settlement record for a period. Shows what's owed to each data source.", {
+    startDate: z.string().describe("Period start (YYYY-MM-DD)"),
+    endDate: z.string().describe("Period end (YYYY-MM-DD)"),
+    periodLabel: z.string().describe("Label (e.g. '2026-Q1', '2026-03')"),
+}, async (p) => {
+    const kp = generateKeyPair();
+    const settlement = generateSettlement(state.contributionLedger, { startDate: p.startDate, endDate: p.endDate, periodLabel: p.periodLabel }, kp.publicKey, kp.privateKey);
+    const verification = verifySettlement(settlement);
+    const lines = settlement.lineItems.map(li => `• ${li.sourceDescriptor || li.sourceReceiptId}: ${li.accessCount} accesses, $${li.amount.toFixed(4)} (${li.compensationModel})`);
+    return { content: [{ type: "text", text: `📋 Settlement Record: ${settlement.settlementId}\n\nPeriod: ${p.periodLabel}\nTotal: $${settlement.totalAmount.toFixed(4)} ${settlement.currency}\nTotal accesses: ${settlement.totalAccesses}\nUnique sources: ${settlement.uniqueSources}\nUnique payers: ${settlement.uniquePayers}\nMerkle root: ${settlement.merkleRoot.slice(0, 16)}...\nVerification: ${verification.valid ? '✅ VALID' : '❌ INVALID'}\n\nLine items:\n${lines.join('\n')}` }] };
+});
+server.tool("generate_compliance_report", "Generate a GDPR Article 30 / EU AI Act Article 10 / SOC 2 compliance report.", {
+    reportType: z.enum(["gdpr_article30", "euai_article10", "soc2_data", "general"]).describe("Report type"),
+    startDate: z.string().describe("Period start"),
+    endDate: z.string().describe("Period end"),
+    periodLabel: z.string().describe("Label"),
+    agentId: z.string().optional().describe("Filter by agent"),
+    principalId: z.string().optional().describe("Filter by principal"),
+}, async (p) => {
+    const kp = generateKeyPair();
+    const report = generateDataComplianceReport(state.contributionLedger, { startDate: p.startDate, endDate: p.endDate, periodLabel: p.periodLabel }, p.reportType, kp.privateKey, { agentId: p.agentId, principalId: p.principalId });
+    return { content: [{ type: "text", text: `📋 Compliance Report: ${report.reportId}\n\nType: ${p.reportType}\nPeriod: ${p.periodLabel}\nTotal data accesses: ${report.summary.totalDataAccesses}\nUnique data sources: ${report.summary.uniqueDataSources}\nPurpose breakdown: ${JSON.stringify(report.summary.purposeBreakdown)}\nCompensation: $${report.summary.compensationSummary.total.toFixed(4)} (pending: $${report.summary.compensationSummary.pending.toFixed(4)})\nTerms violations: ${report.summary.termsViolations}\nAdvisory warnings: ${report.summary.advisoryWarnings}\nSigned: ✅` }] };
+});
+server.tool("record_training_use", "Record that agent output derived from data sources was used for training/fine-tuning/embedding. Creates a signed training attribution receipt.", {
+    trainingUseType: z.enum(["fine_tune", "lora_adapter", "embedding", "rag_index", "distillation", "evaluation", "synthetic_data"]).describe("Type of training use"),
+    modelId: z.string().describe("Model being trained"),
+    sourceAccessReceiptIds: z.array(z.string()).describe("Access receipt IDs of source data used"),
+    outputContentHash: z.string().describe("SHA-256 of the output used for training"),
+    contributionWeights: z.record(z.number()).optional().describe("Fractional weights per source (sum to 1.0)"),
+    datasetSize: z.number().optional().describe("Number of training examples"),
+}, async (p) => {
+    if (!state.agentKey || !state.privateKey)
+        return { content: [{ type: "text", text: "❌ Not identified." }] };
+    const receipt = createTrainingAttribution({
+        trainingUseType: p.trainingUseType,
+        modelId: p.modelId,
+        trainerId: state.agentId || 'unknown',
+        trainerPublicKey: state.agentKey,
+        trainerPrivateKey: state.privateKey,
+        sourceAccessReceiptIds: p.sourceAccessReceiptIds,
+        executionFrameId: 'frame_train_' + Date.now().toString(36),
+        outputContentHash: p.outputContentHash,
+        inputDataHashes: p.sourceAccessReceiptIds.map(id => id), // simplified
+        contributionWeights: p.contributionWeights,
+        datasetSize: p.datasetSize,
+    });
+    recordTrainingAttribution(state.trainingLedger, receipt);
+    const v = verifyTrainingAttribution(receipt);
+    return { content: [{ type: "text", text: `✅ Training attribution recorded.\n\nReceipt: ${receipt.trainingReceiptId}\nType: ${p.trainingUseType}\nModel: ${p.modelId}\nSources: ${p.sourceAccessReceiptIds.length}\nDataset size: ${p.datasetSize || 'N/A'}\nWeights: ${p.contributionWeights ? JSON.stringify(p.contributionWeights) : 'equal'}\nVerification: ${v.valid ? '✅' : '❌'}` }] };
+});
+server.tool("get_model_data_sources", "Show which data sources contributed to a model's training, with fractional weights.", {
+    modelId: z.string().describe("Model ID to check"),
+}, async (p) => {
+    const sources = getModelDataSources(state.trainingLedger, p.modelId);
+    if (sources.length === 0)
+        return { content: [{ type: "text", text: "No training data found for this model." }] };
+    const lines = sources.map(s => `• ${s.accessReceiptId}: weight ${s.weight.toFixed(4)}, type: ${s.trainingUseType}`);
+    return { content: [{ type: "text", text: `🧠 Model Training Sources: ${p.modelId}\n\n${sources.length} data sources contributed:\n${lines.join('\n')}` }] };
+});
+// ═══════════════════════════════════════
 // MCP Prompts — Role-Specific
 // ═══════════════════════════════════════
 server.prompt("coordination_role", "Get instructions for your assigned coordination role", {}, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-passport-system-mcp",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "mcpName": "io.github.aeoess/agent-passport-mcp",
   "description": "MCP server for Agent Passport System — cryptographic identity, delegation, governance, and deliberation for AI agents",
   "type": "module",
@@ -48,15 +48,12 @@
   },
   "homepage": "https://github.com/aeoess/agent-passport-mcp",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "agent-passport-system": "^1.19.0",
-    "zod": "^3.25.0"
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "agent-passport-system": "^1.21.1",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
+    "@types/node": "^22.19.15",
     "typescript": "^5.9.3"
-  },
-  "peerDependencies": {
-    "zod": "^3.25.0"
   }
 }