@kya-os/contracts 1.0.0-alpha

package/dist/verifier.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+/**
+ * Verifier middleware schemas and headers
+ */
+export const AgentContextSchema = z.object({
+    did: z.string().min(1),
+    keyId: z.string().min(1),
+    subject: z.string().optional(),
+    scopes: z.array(z.string()).default([]),
+    session: z.string().min(1),
+    confidence: z.literal("verified"),
+    delegationRef: z.string().optional(),
+    registry: z.string().url(),
+    verifiedAt: z.number().int().positive(),
+});
+export const VerifierResultSchema = z.object({
+    success: z.boolean(),
+    headers: z.record(z.string()).optional(),
+    error: z
+        .object({
+        code: z.string(),
+        message: z.string(),
+        details: z.any().optional(),
+        httpStatus: z.number().int().min(400).max(599),
+    })
+        .optional(),
+});
+export const StructuredErrorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z
+        .object({
+        reason: z.string().optional(),
+        expected: z.any().optional(),
+        received: z.any().optional(),
+        remediation: z.string().optional(),
+    })
+        .optional(),
+});
+// Header constants (frozen names)
+export const AGENT_HEADERS = {
+    DID: "X-Agent-DID",
+    KEY_ID: "X-Agent-KeyId",
+    SUBJECT: "X-Agent-Subject",
+    SCOPES: "X-Agent-Scopes",
+    SESSION: "X-Agent-Session",
+    CONFIDENCE: "X-Agent-Confidence",
+    DELEGATION_REF: "X-Agent-Delegation-Ref",
+    REGISTRY: "X-Agent-Registry",
+    VERIFIED_AT: "X-Agent-Verified-At",
+};
+// HTTP status mappings
+export const ERROR_HTTP_STATUS = {
+    XMCP_I_EBADPROOF: 403,
+    XMCP_I_ENOIDENTITY: 500,
+    XMCP_I_EMIRRORPENDING: 200,
+    XMCP_I_EHANDSHAKE: 401,
+    XMCP_I_ESESSION: 401,
+    XMCP_I_ECLAIM: 400,
+    XMCP_I_ECONFIG: 500,
+    XMCP_I_ERUNTIME: 500,
+};
+//# sourceMappingURL=verifier.js.map

package/dist/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@kya-os/contracts",
+  "version": "1.0.0-alpha",
+  "description": "Shared types and schemas for XMCP-I ecosystem",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./handshake": {
+      "types": "./dist/handshake.d.ts",
+      "import": "./dist/handshake.js"
+    },
+    "./proof": {
+      "types": "./dist/proof.d.ts",
+      "import": "./dist/proof.js"
+    },
+    "./verifier": {
+      "types": "./dist/verifier.d.ts",
+      "import": "./dist/verifier.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./test": {
+      "types": "./dist/test.d.ts",
+      "import": "./dist/test.js"
+    },
+    "./schemas/*": "./schemas/*"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "keywords": [
+    "xmcp",
+    "mcp",
+    "identity",
+    "types",
+    "contracts"
+  ],
+  "author": "KYA OS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kya-os/xmcp-i.git",
+    "directory": "packages/contracts"
+  }
+}

package/schemas/cli/register-output/v1.0.0.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.com/xmcp-i/cli/register-output/v1.0.0",
+  "title": "XMCP-I CLI Register Output",
+  "description": "Schema for xmcpi register command JSON output",
+  "type": "object",
+  "properties": {
+    "agentDID": {
+      "type": "string",
+      "description": "Agent DID",
+      "minLength": 1
+    },
+    "agentURL": {
+      "type": "string",
+      "format": "uri",
+      "description": "Agent URL"
+    },
+    "agentId": {
+      "type": "string",
+      "description": "Agent identifier",
+      "minLength": 1
+    },
+    "agentSlug": {
+      "type": "string",
+      "description": "Agent slug",
+      "minLength": 1
+    },
+    "claimURL": {
+      "type": "string",
+      "format": "uri",
+      "description": "Claim URL (when draft)"
+    },
+    "verificationEndpoint": {
+      "type": "string",
+      "format": "uri",
+      "description": "Verification endpoint URL"
+    },
+    "conformanceCapabilities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["handshake", "signing", "verification"]
+      },
+      "minItems": 3,
+      "maxItems": 3,
+      "description": "Exactly the three MCP-I capabilities"
+    },
+    "mirrorStatus": {
+      "type": "string",
+      "enum": ["pending", "success", "error"],
+      "description": "MCP Registry mirror status"
+    },
+    "mirrorLink": {
+      "type": "string",
+      "format": "uri",
+      "description": "MCP Registry mirror link"
+    }
+  },
+  "required": [
+    "agentDID",
+    "agentURL",
+    "agentId",
+    "agentSlug",
+    "verificationEndpoint",
+    "conformanceCapabilities",
+    "mirrorStatus"
+  ],
+  "additionalProperties": false
+}

package/schemas/proof/v1.0.0.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.com/xmcp-i/proof/v1.0.0",
+  "title": "XMCP-I Detached Proof",
+  "description": "Schema for detached proofs in XMCP-I protocol",
+  "type": "object",
+  "properties": {
+    "jws": {
+      "type": "string",
+      "description": "Compact JWS format detached signature",
+      "minLength": 1
+    },
+    "meta": {
+      "type": "object",
+      "properties": {
+        "did": {
+          "type": "string",
+          "description": "Agent DID",
+          "minLength": 1
+        },
+        "kid": {
+          "type": "string",
+          "description": "Key identifier",
+          "minLength": 1
+        },
+        "ts": {
+          "type": "integer",
+          "description": "Unix timestamp",
+          "minimum": 1
+        },
+        "nonce": {
+          "type": "string",
+          "description": "Session nonce",
+          "minLength": 1
+        },
+        "audience": {
+          "type": "string",
+          "description": "Intended audience",
+          "minLength": 1
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Session identifier",
+          "minLength": 1
+        },
+        "requestHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of canonical request"
+        },
+        "responseHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of canonical response"
+        },
+        "scopeId": {
+          "type": "string",
+          "description": "Optional scope identifier"
+        },
+        "delegationRef": {
+          "type": "string",
+          "description": "Optional delegation reference"
+        }
+      },
+      "required": [
+        "did",
+        "kid",
+        "ts",
+        "nonce",
+        "audience",
+        "sessionId",
+        "requestHash",
+        "responseHash"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": ["jws", "meta"],
+  "additionalProperties": false
+}

package/schemas/registry/receipt-v1.0.0.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya.dev/xmcpi/receipt/v1.0.0.json",
+  "title": "XMCP-I Receipt",
+  "description": "Receipt object returned by KTA for verifiable operations",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://schemas.kya.dev/xmcpi/receipt/v1.0.0.json"
+    },
+    "ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique reference identifier for the receipt"
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 hash of the content with sha256: prefix"
+    },
+    "action": {
+      "type": "string",
+      "enum": ["issue", "revoke"],
+      "description": "The action performed (issue or revoke)"
+    },
+    "ts": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Unix timestamp when the action was performed"
+    },
+    "logIndex": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Index in the KTA log for this receipt"
+    },
+    "logRoot": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Merkle log root hash for verification"
+    },
+    "inclusionProof": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Merkle inclusion proof for verifying the receipt against the log root"
+    }
+  },
+  "required": [
+    "ref",
+    "contentHash",
+    "action",
+    "ts",
+    "logIndex",
+    "logRoot",
+    "inclusionProof"
+  ],
+  "additionalProperties": false
+}

package/schemas/verifier/verify-page/v1.0.0.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.com/xmcp-i/verifier/verify-page/v1.0.0",
+  "title": "XMCP-I Verify Page Payload",
+  "description": "Schema for /verify debug page payload",
+  "type": "object",
+  "properties": {
+    "canonicalHashes": {
+      "type": "object",
+      "properties": {
+        "requestHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of canonical request"
+        },
+        "responseHash": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "SHA-256 hash of canonical response"
+        }
+      },
+      "required": ["requestHash", "responseHash"],
+      "additionalProperties": false
+    },
+    "proof": {
+      "type": "object",
+      "properties": {
+        "jws": {
+          "type": "string",
+          "description": "Compact JWS format detached signature",
+          "minLength": 1
+        },
+        "meta": {
+          "$ref": "https://schemas.kya-os.com/xmcp-i/proof/v1.0.0#/properties/meta"
+        }
+      },
+      "required": ["jws", "meta"],
+      "additionalProperties": false
+    },
+    "didDocumentLink": {
+      "type": "string",
+      "format": "uri",
+      "description": "Link to DID document"
+    },
+    "ktaURL": {
+      "type": "string",
+      "format": "uri",
+      "description": "Know-That-AI URL"
+    },
+    "mcpMirrorStatus": {
+      "type": "string",
+      "enum": ["pending", "success", "error"],
+      "description": "MCP Registry mirror status"
+    },
+    "protocolCapabilities": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["handshake", "signing", "verification"]
+      },
+      "minItems": 3,
+      "maxItems": 3,
+      "description": "Advertised protocol capabilities"
+    },
+    "localVerificationResult": {
+      "type": "object",
+      "properties": {
+        "valid": {
+          "type": "boolean",
+          "description": "Local verification result"
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Validation errors if any"
+        }
+      },
+      "required": ["valid"],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "canonicalHashes",
+    "proof",
+    "didDocumentLink",
+    "ktaURL",
+    "mcpMirrorStatus",
+    "protocolCapabilities",
+    "localVerificationResult"
+  ],
+  "additionalProperties": false
+}

package/schemas/well-known/agent/v1.0.0.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.com/xmcp-i/well-known/agent/v1.0.0",
+  "title": "XMCP-I Agent Well-Known Document",
+  "description": "Schema for /.well-known/agent.json endpoint",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Agent DID",
+      "minLength": 1
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "mcp-i": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["handshake", "signing", "verification"]
+          },
+          "minItems": 3,
+          "maxItems": 3,
+          "description": "Exactly the three MCP-I capabilities"
+        }
+      },
+      "required": ["mcp-i"],
+      "additionalProperties": true
+    },
+    "registry": {
+      "type": "object",
+      "properties": {
+        "kta": {
+          "type": "string",
+          "format": "uri",
+          "description": "Know-That-AI registry URL"
+        },
+        "mcp": {
+          "type": "string",
+          "format": "uri",
+          "description": "MCP Registry URL"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["id", "capabilities"],
+  "additionalProperties": true
+}