@kya-os/contracts 1.5.3-canary.15 → 1.5.3-canary.17

package/package.json

@@ -1,161 +1,67 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.5.3-canary.15",
-  "description": "Shared types and schemas for XMCP-I ecosystem",
-  "type": "commonjs",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "version": "1.5.3-canary.17",
+  "description": "Shared contracts, types, and schemas for MCP-I framework",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     },
-    "./handshake": {
-      "types": "./dist/handshake.d.ts",
-      "import": "./dist/handshake.js",
-      "require": "./dist/handshake.js"
-    },
-    "./proof": {
-      "types": "./dist/proof/index.d.ts",
-      "import": "./dist/proof/index.js",
-      "require": "./dist/proof/index.js"
-    },
-    "./verifier": {
-      "types": "./dist/verifier.d.ts",
-      "import": "./dist/verifier.js",
-      "require": "./dist/verifier.js"
-    },
-    "./registry": {
-      "types": "./dist/registry.d.ts",
-      "import": "./dist/registry.js",
-      "require": "./dist/registry.js"
-    },
-    "./cli": {
-      "types": "./dist/cli.d.ts",
-      "import": "./dist/cli.js",
-      "require": "./dist/cli.js"
-    },
-    "./test": {
-      "types": "./dist/test.d.ts",
-      "import": "./dist/test.js",
-      "require": "./dist/test.js"
-    },
-    "./did": {
-      "types": "./dist/did/index.d.ts",
-      "import": "./dist/did/index.js",
-      "require": "./dist/did/index.js"
-    },
-    "./vc": {
-      "types": "./dist/vc/index.d.ts",
-      "import": "./dist/vc/index.js",
-      "require": "./dist/vc/index.js"
+    "./consent": {
+      "types": "./dist/consent/index.d.ts",
+      "default": "./dist/consent/index.js"
     },
     "./delegation": {
       "types": "./dist/delegation/index.d.ts",
-      "import": "./dist/delegation/index.js",
-      "require": "./dist/delegation/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js",
-      "require": "./dist/runtime/index.js"
-    },
-    "./tlkrc": {
-      "types": "./dist/tlkrc/index.d.ts",
-      "import": "./dist/tlkrc/index.js",
-      "require": "./dist/tlkrc/index.js"
-    },
-    "./env": {
-      "types": "./dist/env/index.d.ts",
-      "import": "./dist/env/index.js",
-      "require": "./dist/env/index.js"
+      "default": "./dist/delegation/index.js"
     },
     "./agentshield-api": {
       "types": "./dist/agentshield-api/index.d.ts",
-      "import": "./dist/agentshield-api/index.js",
-      "require": "./dist/agentshield-api/index.js"
+      "default": "./dist/agentshield-api/index.js"
     },
-    "./audit": {
-      "types": "./dist/audit/index.d.ts",
-      "import": "./dist/audit/index.js",
-      "require": "./dist/audit/index.js"
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./proof": {
+      "types": "./dist/proof/index.d.ts",
+      "default": "./dist/proof/index.js"
     },
     "./tool-protection": {
       "types": "./dist/tool-protection/index.d.ts",
-      "import": "./dist/tool-protection/index.js",
-      "require": "./dist/tool-protection/index.js"
-    },
-    "./well-known": {
-      "types": "./dist/well-known/index.d.ts",
-      "import": "./dist/well-known/index.js",
-      "require": "./dist/well-known/index.js"
+      "default": "./dist/tool-protection/index.js"
     },
     "./config": {
       "types": "./dist/config/index.d.ts",
-      "import": "./dist/config/index.js",
-      "require": "./dist/config/index.js"
-    },
-    "./dashboard-config": {
-      "types": "./dist/dashboard-config/index.d.ts",
-      "import": "./dist/dashboard-config/index.js",
-      "require": "./dist/dashboard-config/index.js"
+      "default": "./dist/config/index.js"
     },
-    "./consent": {
-      "types": "./dist/consent/index.d.ts",
-      "import": "./dist/consent/index.js",
-      "require": "./dist/consent/index.js"
+    "./audit": {
+      "types": "./dist/audit/index.d.ts",
+      "default": "./dist/audit/index.js"
     }
   },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "!dist/**/*.map",
-    "!dist/**/__tests__/**",
-    "!dist/**/__fixtures__/**",
-    "!dist/**/*.spec.*",
-    "!dist/**/*.test.*",
-    "!README.md",
-    "!*.md",
-    "!CHANGELOG.md"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && npm run emit-schemas",
     "emit-schemas": "node scripts/emit-schemas.js",
-    "clean": "rm -rf dist && rm -f *.tsbuildinfo",
-    "dev": "tsc -p tsconfig.build.json --watch",
-    "type-check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "npm run build && node ../create-mcpi-app/scripts/validate-dependencies.js"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@vitest/coverage-v8": "^4.0.5",
-    "ajv": "^8.12.0",
-    "ajv-formats": "^2.1.1",
-    "fast-check": "^3.15.0",
-    "typescript": "^5.0.0",
-    "vitest": "^4.0.5",
-    "zod-to-json-schema": "^3.22.0"
+    "lint": "eslint .",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "clean": "rm -rf dist .turbo node_modules",
+    "prepublishOnly": "npm run build && node ../create-mcpi-app/scripts/validate-no-workspace.js"
   },
   "dependencies": {
-    "zod": "^3.22.0"
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.9",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.3",
+    "vitest": "^1.6.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"
+  "publishConfig": {
+    "access": "public"
   }
 }

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.ai/xmcp-i/cli/register-output/v1.0.0",
+  "title": "XMCP-I CLI Register Output",
+  "description": "Schema for mcpi 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/identity/v1.0.0.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.ai/xmcp-i/identity/v1.0.0",
+  "title": "MCP-I Identity File",
+  "description": "Schema for .mcpi/identity.json file structure used in development mode",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Identity file format version"
+    },
+    "did": {
+      "type": "string",
+      "pattern": "^did:",
+      "description": "Decentralized Identifier (DID) for the agent"
+    },
+    "kid": {
+      "type": "string",
+      "pattern": "^z[1-9A-HJ-NP-Za-km-z]+$",
+      "description": "Key identifier in multibase format (z-prefix base58btc)"
+    },
+    "privateKey": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9+/]{43}=$",
+      "description": "Base64-encoded Ed25519 private key (32 bytes)"
+    },
+    "publicKey": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9+/]{43}=$",
+      "description": "Base64-encoded Ed25519 public key (32 bytes)"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of identity creation"
+    },
+    "lastRotated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last key rotation (optional)"
+    }
+  },
+  "required": ["version", "did", "kid", "privateKey", "publicKey", "createdAt"],
+  "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.ai/mcpi/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-os.ai/mcpi/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-os.ai/mcpi/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.ai/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.ai/mcpi/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,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.ai/xmcp-i/well-known/agent/v1.0.0",
+  "title": "MCP-I Agent Document",
+  "description": "Schema for /.well-known/agent.json endpoint (MCP-I capabilities). Top-level schema uses additionalProperties:false for strict validation - new top-level fields require explicit schema version bumps to ensure deliberate evolution. Vendor-specific extensions should be placed in the 'metadata' object which allows additionalProperties:true for backward-compatible extensibility.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Agent DID identifier",
+      "pattern": "^did:"
+    },
+    "capabilities": {
+      "type": "object",
+      "description": "Agent capabilities by protocol",
+      "properties": {
+        "mcp-i": {
+          "type": "array",
+          "description": "MCP-I protocol capabilities",
+          "items": {
+            "type": "string",
+            "enum": [
+              "handshake",
+              "signing",
+              "verification"
+            ]
+          },
+          "minItems": 3,
+          "maxItems": 3
+        }
+      },
+      "required": ["mcp-i"],
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional agent metadata. This object is the designated extensibility point - vendors can add custom fields here without requiring schema version changes. Use this for implementation-specific data, vendor identifiers, custom features, etc.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Human-readable service name"
+        },
+        "serviceEndpoint": {
+          "type": "string",
+          "description": "Service endpoint URL",
+          "format": "uri"
+        },
+        "description": {
+          "type": "string",
+          "description": "Service description"
+        },
+        "version": {
+          "type": "string",
+          "description": "Service version"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["id", "capabilities"],
+  "additionalProperties": false
+}