@kya-os/mcp 1.2.0

package/schemas/delegation-credential.json

@@ -0,0 +1,312 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.modelcontextprotocol-identity.io/xmcp-i/credentials/delegation-credential.v1.0.0.json",
+  "title": "MCP-I Delegation Credential",
+  "description": "W3C Verifiable Credential containing an MCP-I delegation with CRISP constraints.",
+  "type": "object",
+  "required": ["@context", "type", "issuer", "issuanceDate", "credentialSubject"],
+  "properties": {
+    "@context": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string", "format": "uri" },
+          { "type": "object" }
+        ]
+      },
+      "minItems": 2,
+      "description": "JSON-LD context. MUST include W3C VC context as first element and MCP-I delegation context."
+    },
+    "id": {
+      "type": "string",
+      "format": "uri",
+      "description": "Unique credential identifier (URN or URL)."
+    },
+    "type": {
+      "type": "array",
+      "items": { "type": "string" },
+      "contains": { "const": "VerifiableCredential" },
+      "minItems": 2,
+      "description": "Credential types. MUST include 'VerifiableCredential' and 'DelegationCredential'."
+    },
+    "issuer": {
+      "oneOf": [
+        { "type": "string", "pattern": "^did:.+$" },
+        {
+          "type": "object",
+          "required": ["id"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^did:.+$" }
+          }
+        }
+      ],
+      "description": "Issuer DID or issuer object containing id."
+    },
+    "issuanceDate": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime when the credential was issued."
+    },
+    "expirationDate": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime when the credential expires."
+    },
+    "credentialSubject": {
+      "$ref": "#/$defs/DelegationCredentialSubject"
+    },
+    "credentialStatus": {
+      "$ref": "#/$defs/CredentialStatus"
+    },
+    "proof": {
+      "$ref": "#/$defs/Proof"
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "DelegationCredentialSubject": {
+      "type": "object",
+      "required": ["id", "delegation"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^did:.+$",
+          "description": "Subject DID (the delegate receiving the authorization)."
+        },
+        "delegation": {
+          "type": "object",
+          "required": ["id", "issuerDid", "subjectDid", "constraints", "status"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "description": "Unique delegation identifier."
+            },
+            "issuerDid": {
+              "type": "string",
+              "pattern": "^did:.+$",
+              "description": "DID of the delegation issuer (delegator)."
+            },
+            "subjectDid": {
+              "type": "string",
+              "pattern": "^did:.+$",
+              "description": "DID of the delegation subject (delegate)."
+            },
+            "userDid": {
+              "type": "string",
+              "pattern": "^did:.+$",
+              "description": "DID of the end user on whose behalf the delegation acts."
+            },
+            "userIdentifier": {
+              "type": "string",
+              "description": "Alternative user identifier (e.g., email, username)."
+            },
+            "sessionId": {
+              "type": "string",
+              "description": "Session binding for session-scoped delegations."
+            },
+            "scopes": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Authorized scope strings."
+            },
+            "controller": {
+              "type": "string",
+              "pattern": "^did:.+$",
+              "description": "Controller DID for delegation management."
+            },
+            "parentId": {
+              "type": "string",
+              "description": "Parent delegation ID for chained delegations."
+            },
+            "constraints": {
+              "$ref": "#/$defs/DelegationConstraints"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["active", "revoked", "expired"],
+              "description": "Current delegation status."
+            },
+            "createdAt": {
+              "type": "integer",
+              "description": "Unix timestamp when delegation was created."
+            },
+            "metadata": {
+              "type": "object",
+              "description": "Additional delegation metadata.",
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    },
+    "DelegationConstraints": {
+      "type": "object",
+      "properties": {
+        "notBefore": {
+          "type": "integer",
+          "description": "Unix timestamp before which the delegation is not valid."
+        },
+        "notAfter": {
+          "type": "integer",
+          "description": "Unix timestamp after which the delegation expires."
+        },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Authorized scope strings."
+        },
+        "audience": {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ],
+          "description": "Intended audience DID(s) for the delegation."
+        },
+        "crisp": {
+          "type": "object",
+          "required": ["scopes"],
+          "properties": {
+            "budget": {
+              "type": "object",
+              "required": ["unit", "cap"],
+              "properties": {
+                "unit": {
+                  "type": "string",
+                  "enum": ["USD", "ops", "points"],
+                  "description": "Budget unit type."
+                },
+                "cap": {
+                  "type": "number",
+                  "minimum": 0,
+                  "description": "Maximum budget amount."
+                },
+                "window": {
+                  "type": "object",
+                  "required": ["kind", "durationSec"],
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": ["rolling", "fixed"]
+                    },
+                    "durationSec": {
+                      "type": "integer",
+                      "minimum": 1
+                    }
+                  }
+                }
+              }
+            },
+            "scopes": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["resource", "matcher"],
+                "properties": {
+                  "resource": { "type": "string" },
+                  "matcher": {
+                    "type": "string",
+                    "enum": ["exact", "prefix", "regex"]
+                  },
+                  "constraints": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "CredentialStatus": {
+      "type": "object",
+      "required": ["id", "type", "statusPurpose", "statusListIndex", "statusListCredential"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri",
+          "description": "Status entry identifier."
+        },
+        "type": {
+          "type": "string",
+          "const": "StatusList2021Entry"
+        },
+        "statusPurpose": {
+          "type": "string",
+          "enum": ["revocation", "suspension"]
+        },
+        "statusListIndex": {
+          "type": "string",
+          "pattern": "^[0-9]+$",
+          "description": "Index in the status list bitstring."
+        },
+        "statusListCredential": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the StatusList2021 credential."
+        }
+      }
+    },
+    "Proof": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Proof type (e.g., 'Ed25519Signature2020', 'JsonWebSignature2020')."
+        },
+        "created": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "verificationMethod": {
+          "type": "string",
+          "description": "DID URL of the verification key."
+        },
+        "proofPurpose": {
+          "type": "string",
+          "description": "Purpose of the proof (e.g., 'assertionMethod')."
+        },
+        "proofValue": {
+          "type": "string",
+          "description": "Base64-encoded signature value."
+        },
+        "jws": {
+          "type": "string",
+          "description": "Compact JWS signature."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "examples": [
+    {
+      "@context": [
+        "https://www.w3.org/2018/credentials/v1",
+        "https://schema.modelcontextprotocol-identity.io/xmcp-i/credentials/delegation.v1.0.0.json"
+      ],
+      "id": "urn:uuid:12345678-1234-1234-1234-123456789abc",
+      "type": ["VerifiableCredential", "DelegationCredential"],
+      "issuer": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+      "issuanceDate": "2024-03-12T00:00:00Z",
+      "expirationDate": "2024-03-13T00:00:00Z",
+      "credentialSubject": {
+        "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
+        "delegation": {
+          "id": "del-001",
+          "issuerDid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+          "subjectDid": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
+          "scopes": ["read:documents", "write:documents"],
+          "constraints": {
+            "notBefore": 1710201600,
+            "notAfter": 1710288000
+          },
+          "status": "active"
+        }
+      }
+    }
+  ]
+}

package/schemas/detached-proof.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.modelcontextprotocol-identity.io/xmcp-i/proof/detached-proof.v1.0.0.json",
+  "title": "MCP-I Detached Proof",
+  "description": "Cryptographic proof binding an MCP tool request/response pair to an agent's identity and session context.",
+  "type": "object",
+  "required": ["jws", "meta"],
+  "properties": {
+    "jws": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$",
+      "description": "Compact JWS (header.payload.signature) signed with Ed25519. The payload contains canonicalized proof metadata."
+    },
+    "meta": {
+      "$ref": "#/$defs/ProofMeta"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProofMeta": {
+      "type": "object",
+      "required": ["did", "kid", "ts", "nonce", "audience", "sessionId", "requestHash", "responseHash"],
+      "properties": {
+        "did": {
+          "type": "string",
+          "pattern": "^did:(key|web):.+$",
+          "description": "Signer's DID."
+        },
+        "kid": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Key identifier for the signing key (matches JWS header kid)."
+        },
+        "ts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Unix timestamp in seconds when the proof was generated."
+        },
+        "nonce": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Session nonce from the handshake, binding proof to session."
+        },
+        "audience": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Intended audience (server DID or URL)."
+        },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Session identifier from handshake response."
+        },
+        "requestHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of JCS-canonicalized request. Format: 'sha256:<64 hex chars>'."
+        },
+        "responseHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of JCS-canonicalized response. Format: 'sha256:<64 hex chars>'."
+        },
+        "scopeId": {
+          "type": "string",
+          "description": "Optional scope identifier for fine-grained authorization tracking."
+        },
+        "delegationRef": {
+          "type": "string",
+          "description": "Optional reference to delegation credential authorizing this action."
+        },
+        "clientDid": {
+          "type": "string",
+          "pattern": "^did:.+$",
+          "description": "Optional client DID for multi-party scenarios."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "jws": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa2hhWGdCWkR2b3REa0w1MjU3ZmFpenRpR2lDMlF0S0xHcGJubkVHdGEyZG9LI3o2TWtoYVhnQlpEdm90RGtMNTI1N2ZhaXp0aUdpQzJRdEtMR3Bibm5FR3RhMmRvSyJ9.eyJhdWQiOiJkaWQ6d2ViOmV4YW1wbGUuY29tIiwic3ViIjoiZGlkOmtleTp6Nk1raGFYZ0JaRHZvdERrTDUyNTdmYWl6dGlHaUMyUXRLTEdwYm5uRUd0YTJkb0siLCJpc3MiOiJkaWQ6a2V5Ono2TWtoYVhnQlpEdm90RGtMNTI1N2ZhaXp0aUdpQzJRdEtMR3Bibm5FR3RhMmRvSyIsInJlcXVlc3RIYXNoIjoic2hhMjU2OjcyYjgwYTRhYTZhYjlmNTNhZThmZTcyN2I2N2I5Y2I3ZjQ5OTk3ZjM2MjE3OTg5OTI3MTI1OGMzMjY1YmZiMWMiLCJyZXNwb25zZUhhc2giOiJzaGEyNTY6MWI0ZjBhMWVlNzcwOGQ0YzM5OGZmOWE0OTM3YjI0MjFhNmQzYTQ4MjRiNmE2ZjFhNmJlOGJhY2I3ZWYyNzlkYSIsInRzIjoxNzEwMjY4ODAwLCJub25jZSI6Ims3SHk5bU5wUXJTdFV2V3hZejAxQWEiLCJzZXNzaW9uSWQiOiJzZXNzX2FiYzEyM3h5eiJ9.signature",
+      "meta": {
+        "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+        "kid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK#z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+        "ts": 1710268800,
+        "nonce": "k7Hy9mNpQrStUvWxYz01Aa",
+        "audience": "did:web:example.com",
+        "sessionId": "sess_abc123xyz",
+        "requestHash": "sha256:72b80a4aa6ab9f53ae8fe727b67b9cb7f49997f362179899271258c3265bfb1c",
+        "responseHash": "sha256:1b4f0a1ee7708d4c398ff9a4937b2421a6d3a4824b6a6f1a6be8bacb7ef279da"
+      }
+    }
+  ]
+}

package/schemas/handshake-request.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.modelcontextprotocol-identity.io/xmcp-i/handshake/handshake-request.v1.0.0.json",
+  "title": "MCP-I Handshake Request",
+  "description": "Client-initiated handshake request to establish an MCP-I session with nonce-based replay protection.",
+  "type": "object",
+  "required": ["nonce", "audience", "timestamp"],
+  "properties": {
+    "nonce": {
+      "type": "string",
+      "minLength": 22,
+      "description": "Base64url-encoded random value (minimum 16 bytes) for replay prevention. Each nonce MUST be unique per session."
+    },
+    "audience": {
+      "type": "string",
+      "description": "The intended recipient's DID (did:key or did:web). MUST match the server's DID for the request to be accepted."
+    },
+    "timestamp": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Unix timestamp in seconds. Server MAY reject requests with timestamps outside acceptable skew window (default: 120 seconds)."
+    },
+    "agentDid": {
+      "type": "string",
+      "pattern": "^did:(key|web):.+$",
+      "description": "The agent's DID if authenticated. Required for authenticated sessions."
+    },
+    "clientInfo": {
+      "type": "object",
+      "description": "Optional client metadata for session context.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Client application name."
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable client title."
+        },
+        "version": {
+          "type": "string",
+          "description": "Client version string."
+        },
+        "platform": {
+          "type": "string",
+          "description": "Operating system or platform identifier."
+        },
+        "vendor": {
+          "type": "string",
+          "description": "Client vendor or organization."
+        },
+        "persistentId": {
+          "type": "string",
+          "description": "Persistent client identifier across sessions."
+        },
+        "clientId": {
+          "type": "string",
+          "description": "Unique client instance identifier."
+        }
+      },
+      "required": ["name"]
+    },
+    "clientProtocolVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Client's supported MCP-I protocol version (e.g., '1.0')."
+    },
+    "clientCapabilities": {
+      "type": "object",
+      "description": "Client capability flags for feature negotiation.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "nonce": "k7Hy9mNpQrStUvWxYz01Aa",
+      "audience": "did:web:example.com",
+      "timestamp": 1710268800,
+      "agentDid": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+      "clientProtocolVersion": "1.0"
+    }
+  ]
+}

package/schemas/handshake-response.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.modelcontextprotocol-identity.io/xmcp-i/handshake/handshake-response.v1.0.0.json",
+  "title": "MCP-I Handshake Response",
+  "description": "Server response to a successful handshake request, establishing session context.",
+  "type": "object",
+  "required": ["sessionId", "serverDid", "protocolVersion"],
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique session identifier. Clients MUST include this in subsequent requests."
+    },
+    "serverDid": {
+      "type": "string",
+      "pattern": "^did:(key|web):.+$",
+      "description": "The server's DID used for proof verification."
+    },
+    "protocolVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Negotiated MCP-I protocol version (e.g., '1.0')."
+    },
+    "serverCapabilities": {
+      "type": "object",
+      "description": "Server capability flags indicating supported features.",
+      "properties": {
+        "proofs": {
+          "type": "boolean",
+          "description": "Server supports detached proofs on tool responses."
+        },
+        "delegation": {
+          "type": "boolean",
+          "description": "Server supports W3C delegation credentials."
+        },
+        "statusList": {
+          "type": "boolean",
+          "description": "Server supports StatusList2021 revocation checking."
+        }
+      },
+      "additionalProperties": true
+    },
+    "sessionTtl": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Session time-to-live in seconds. Client SHOULD refresh before expiration."
+    },
+    "nonce": {
+      "type": "string",
+      "description": "Echo of the client's nonce for binding verification."
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "sessionId": "sess_abc123xyz",
+      "serverDid": "did:web:api.example.com",
+      "protocolVersion": "1.0",
+      "serverCapabilities": {
+        "proofs": true,
+        "delegation": true,
+        "statusList": true
+      },
+      "sessionTtl": 1800
+    }
+  ]
+}