@kya-os/contracts 1.5.3-canary.16 → 1.5.3-canary.18

package/dist/tool-protection/index.js

@@ -9,7 +9,7 @@
  * @module @kya-os/contracts/tool-protection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = void 0;
+exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = exports.AuthorizationRequirementSchema = void 0;
 exports.isToolProtection = isToolProtection;
 exports.isToolProtectionMap = isToolProtectionMap;
 exports.isToolProtectionResponse = isToolProtectionResponse;
@@ -22,15 +22,42 @@ exports.toolRequiresDelegation = toolRequiresDelegation;
 exports.getToolRequiredScopes = getToolRequiredScopes;
 exports.getToolRiskLevel = getToolRiskLevel;
 exports.createDelegationRequiredError = createDelegationRequiredError;
+exports.normalizeToolProtection = normalizeToolProtection;
 const zod_1 = require("zod");
 /**
  * Zod Schemas for Validation
  */
+exports.AuthorizationRequirementSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({
+        type: zod_1.z.literal('oauth'),
+        provider: zod_1.z.string(),
+        requiredScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('mdl'),
+        issuer: zod_1.z.string(),
+        credentialType: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('idv'),
+        provider: zod_1.z.string(),
+        verificationLevel: zod_1.z.enum(['basic', 'enhanced', 'loa3']).optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('credential'),
+        credentialType: zod_1.z.string(),
+        issuer: zod_1.z.string().optional(),
+    }),
+    zod_1.z.object({
+        type: zod_1.z.literal('none'),
+    }),
+]);
 exports.ToolProtectionSchema = zod_1.z.object({
     requiresDelegation: zod_1.z.boolean(),
     requiredScopes: zod_1.z.array(zod_1.z.string()),
     riskLevel: zod_1.z.enum(['low', 'medium', 'high', 'critical']).optional(),
-    oauthProvider: zod_1.z.string().optional() // Phase 2: Tool-specific OAuth provider
+    oauthProvider: zod_1.z.string().optional(), // Phase 2: Tool-specific OAuth provider
+    authorization: exports.AuthorizationRequirementSchema.optional(),
 });
 exports.ToolProtectionMapSchema = zod_1.z.record(zod_1.z.string(), exports.ToolProtectionSchema);
 exports.ToolProtectionResponseSchema = zod_1.z.object({
@@ -112,3 +139,35 @@ function createDelegationRequiredError(toolName, requiredScopes, consentUrl) {
         authorizationUrl: consentUrl // Include both for compatibility
     };
 }
+/**
+ * Normalize tool protection configuration
+ * Migrates legacy oauthProvider field to authorization object
+ *
+ * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
+ */
+function normalizeToolProtection(raw) {
+    // If authorization is already present, return as is
+    if (raw.authorization) {
+        return raw;
+    }
+    // Migrate oauthProvider to authorization
+    if (raw.oauthProvider) {
+        return {
+            ...raw,
+            authorization: {
+                type: 'oauth',
+                provider: raw.oauthProvider,
+            },
+            // Keep oauthProvider for backward compatibility until Phase 3
+        };
+    }
+    // Default for requiresDelegation=true without specific auth: type='none' (consent only)
+    // But ONLY if authorization is missing entirely
+    if (raw.requiresDelegation && !raw.authorization && !raw.oauthProvider) {
+        // We don't automatically set type='none' here to allow
+        // ProviderResolver to do its scope inference fallback logic.
+        // The fallback logic will eventually be moved into an AuthorizationService.
+        return raw;
+    }
+    return raw;
+}

package/dist/well-known/index.d.ts

@@ -209,12 +209,12 @@ export declare const AgentDocumentSchema: z.ZodObject<{
         description?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
     capabilities: {
         'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
     } & {
         [k: string]: string[];
     };
+    id: string;
     metadata?: {
         version?: string | undefined;
         name?: string | undefined;
@@ -222,12 +222,12 @@ export declare const AgentDocumentSchema: z.ZodObject<{
         description?: string | undefined;
     } | undefined;
 }, {
-    id: string;
     capabilities: {
         'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
     } & {
         [k: string]: string[];
     };
+    id: string;
     metadata?: {
         version?: string | undefined;
         name?: string | undefined;

package/package.json

@@ -1,161 +1,69 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.5.3-canary.16",
-  "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.18",
+  "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"
+    "test:watch": "vitest",
+    "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",
+    "@vitest/coverage-v8": "^1.6.0",
+    "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
+}