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

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
+}

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

@@ -0,0 +1,174 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.kya-os.ai/xmcp-i/well-known/did/v1.0.0",
+  "title": "W3C DID Document",
+  "description": "Schema for /.well-known/did.json endpoint (W3C DID Core specification)",
+  "type": "object",
+  "properties": {
+    "@context": {
+      "description": "JSON-LD context - must be W3C DID v1 string or array with W3C DID v1 as first element",
+      "oneOf": [
+        {
+          "type": "string",
+          "const": "https://www.w3.org/ns/did/v1"
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": {
+            "oneOf": [
+              {
+                "const": "https://www.w3.org/ns/did/v1"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "contains": {
+            "const": "https://www.w3.org/ns/did/v1"
+          }
+        }
+      ]
+
+    },
+    "id": {
+      "type": "string",
+      "description": "DID identifier",
+      "pattern": "^did:"
+    },
+    "verificationMethod": {
+      "type": "array",
+      "description": "Verification methods",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "controller"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Verification method ID"
+          },
+          "type": {
+            "type": "string",
+            "description": "Verification method type",
+            "enum": [
+              "Ed25519VerificationKey2020",
+              "Ed25519VerificationKey2018",
+              "JsonWebKey2020"
+            ]
+          },
+          "controller": {
+            "type": "string",
+            "description": "Controller DID",
+            "pattern": "^did:"
+          },
+          "publicKeyBase64": {
+            "type": "string",
+            "description": "Base64-encoded public key"
+          },
+          "publicKeyMultibase": {
+            "type": "string",
+            "description": "Multibase-encoded public key"
+          },
+          "publicKeyJwk": {
+            "type": "object",
+            "description": "JSON Web Key"
+          }
+        },
+        "anyOf": [
+          {
+            "properties": {
+              "publicKeyBase64": {
+                "type": "string"
+              }
+            },
+            "required": ["publicKeyBase64"]
+          },
+          {
+            "properties": {
+              "publicKeyMultibase": {
+                "type": "string"
+              }
+            },
+            "required": ["publicKeyMultibase"]
+          },
+          {
+            "properties": {
+              "publicKeyJwk": {
+                "type": "object"
+              }
+            },
+            "required": ["publicKeyJwk"]
+          }
+        ]
+      },
+      "minItems": 1
+    },
+    "authentication": {
+      "type": "array",
+      "description": "Authentication methods",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "assertionMethod": {
+      "type": "array",
+      "description": "Assertion methods",
+      "items": {
+        "type": "string"
+      }
+    },
+    "keyAgreement": {
+      "type": "array",
+      "description": "Key agreement methods",
+      "items": {
+        "type": "string"
+      }
+    },
+    "capabilityInvocation": {
+      "type": "array",
+      "description": "Capability invocation methods",
+      "items": {
+        "type": "string"
+      }
+    },
+    "capabilityDelegation": {
+      "type": "array",
+      "description": "Capability delegation methods",
+      "items": {
+        "type": "string"
+      }
+    },
+    "service": {
+      "type": "array",
+      "description": "Service endpoints",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "serviceEndpoint": {
+            "oneOf": [
+              {
+                "type": "string",
+                "format": "uri"
+              },
+              {
+                "type": "object"
+              }
+            ]
+          }
+        },
+        "required": ["id", "type", "serviceEndpoint"]
+      }
+    }
+  },
+  "required": ["@context", "id", "verificationMethod", "authentication"],
+  "additionalProperties": true
+}

package/scripts/emit-schemas.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Schema Emission Script
+ *
+ * This script generates JSON Schemas from Zod schemas for interoperability
+ * with other languages and validation tools.
+ */
+
+// Placeholder - will be implemented after Zod schemas are created
+console.log('Schema emission script - to be implemented');
+process.exit(0);

package/src/agentshield-api/admin-schemas.ts

@@ -0,0 +1,31 @@
+/**
+ * AgentShield Admin API Validation Schemas
+ *
+ * Zod schemas for administrative operations in AgentShield.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+import { z } from 'zod';
+
+/**
+ * Request schema for clearing agent cache
+ */
+export const clearCacheRequestSchema = z.object({
+  agent_did: z.string().min(1).describe('The DID of the agent whose cache should be cleared'),
+});
+
+/**
+ * Response schema for clear cache operation
+ */
+export const clearCacheResponseSchema = z.object({
+  message: z.string().describe('Human-readable message about the operation result'),
+  agent_did: z.string().describe('The agent DID that was cleared'),
+  project_id: z.string().nullable().describe('The project ID if available'),
+  cache_key: z.string().describe('The cache key that was cleared'),
+  old_cache_key: z.string().nullable().describe('Old cache key that was also cleared (for migration)'),
+  had_value: z.boolean().describe('Whether the cache entry existed before clearing'),
+  had_old_value: z.boolean().describe('Whether the old cache entry existed before clearing'),
+  cleared: z.boolean().describe('Whether the cache was successfully cleared'),
+});
+

package/src/agentshield-api/admin-types.ts

@@ -0,0 +1,47 @@
+/**
+ * AgentShield Admin API Type Definitions
+ *
+ * TypeScript interfaces for administrative operations in AgentShield.
+ * These types ensure parity between xmcp-i admin endpoints and the AgentShield service.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+/**
+ * Request to clear agent cache
+ * POST /admin/clear-cache
+ */
+export interface ClearCacheRequest {
+  /** The DID of the agent whose cache should be cleared */
+  agent_did: string;
+}
+
+/**
+ * Response from clear cache operation
+ */
+export interface ClearCacheResponse {
+  /** Human-readable message about the operation result */
+  message: string;
+  
+  /** The agent DID that was cleared */
+  agent_did: string;
+  
+  /** The project ID if available */
+  project_id: string | null;
+  
+  /** The cache key that was cleared */
+  cache_key: string;
+  
+  /** Old cache key that was also cleared (for migration) */
+  old_cache_key: string | null;
+  
+  /** Whether the cache entry existed before clearing */
+  had_value: boolean;
+  
+  /** Whether the old cache entry existed before clearing */
+  had_old_value: boolean;
+  
+  /** Whether the cache was successfully cleared */
+  cleared: boolean;
+}
+

package/src/agentshield-api/endpoints.ts

@@ -0,0 +1,60 @@
+/**
+ * AgentShield/Bouncer API Endpoint Constants
+ * 
+ * Centralized endpoint definitions to prevent hardcoded URLs
+ * and ensure consistency across all API clients.
+ * 
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+/**
+ * Base path for all AgentShield/Bouncer API endpoints
+ */
+export const AGENTSHIELD_API_BASE = '/api/v1/bouncer' as const;
+
+/**
+ * AgentShield API endpoint paths
+ * 
+ * These are relative paths that should be appended to the base API URL.
+ * Example: `${apiUrl}${AGENTSHIELD_ENDPOINTS.PROOFS}`
+ */
+export const AGENTSHIELD_ENDPOINTS = {
+  /** Submit proofs in batch */
+  PROOFS: `${AGENTSHIELD_API_BASE}/proofs` as const,
+  
+  /** Verify delegation by agent DID and scopes */
+  DELEGATIONS_VERIFY: `${AGENTSHIELD_API_BASE}/delegations/verify` as const,
+  
+  /** Get delegation by ID */
+  DELEGATIONS_GET: (id: string) => `${AGENTSHIELD_API_BASE}/delegations/${id}` as const,
+  
+  /** Create new delegation */
+  DELEGATIONS_CREATE: `${AGENTSHIELD_API_BASE}/delegations` as const,
+  
+  /** Revoke delegation */
+  DELEGATIONS_REVOKE: (id: string) => `${AGENTSHIELD_API_BASE}/delegations/${id}/revoke` as const,
+  
+  /** Get server configuration */
+  CONFIG: (projectId: string) => `${AGENTSHIELD_API_BASE}/projects/${projectId}/config` as const,
+} as const;
+
+/**
+ * HTTP methods for each endpoint
+ */
+export const AGENTSHIELD_METHODS = {
+  PROOFS: 'POST' as const,
+  DELEGATIONS_VERIFY: 'POST' as const,
+  DELEGATIONS_GET: 'GET' as const,
+  DELEGATIONS_CREATE: 'POST' as const,
+  DELEGATIONS_REVOKE: 'POST' as const,
+  CONFIG: 'GET' as const,
+} as const;
+
+/**
+ * Required headers for AgentShield API requests
+ */
+export interface AgentShieldAPIHeaders {
+  'Content-Type': 'application/json';
+  'Authorization': `Bearer ${string}`;
+}
+

package/src/agentshield-api/index.ts

@@ -0,0 +1,70 @@
+/**
+ * AgentShield/Bouncer API Contracts
+ *
+ * Centralized type definitions, validation schemas, and endpoint constants
+ * for the AgentShield dashboard API integration.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+// Type exports
+export type {
+  AgentShieldAPIResponse,
+  AgentShieldAPIErrorResponse,
+  ProofSubmissionRequest,
+  ProofSubmissionResponse,
+  ToolCallContext,
+  ConsentEventContext,
+  BouncerOutcome,
+  VerifyDelegationRequest,
+  VerifyDelegationResponse,
+  VerifyDelegationAPIResponse,
+  DelegationCredential,
+  AgentShieldToolProtection,
+  ToolProtectionConfigResponse,
+  ToolProtectionConfigAPIResponse,
+  CreateDelegationRequest,
+  CreateDelegationResponse,
+  CreateDelegationAPIResponse,
+  RevokeDelegationRequest,
+  RevokeDelegationResponse,
+  RevokeDelegationAPIResponse,
+} from "./types.js";
+
+export { AgentShieldAPIError } from "./types.js";
+export type { AgentShieldAPIHeaders } from "./endpoints.js";
+
+export type { ClearCacheRequest, ClearCacheResponse } from "./admin-types.js";
+
+// Schema exports
+export {
+  agentShieldAPIErrorSchema,
+  agentShieldAPIResponseSchema,
+  proofSubmissionRequestSchema,
+  proofSubmissionResponseSchema,
+  delegationCredentialSchema,
+  verifyDelegationRequestSchema,
+  verifyDelegationResponseSchema,
+  verifyDelegationAPIResponseSchema,
+  agentShieldToolProtectionSchema,
+  toolProtectionConfigResponseSchema,
+  toolProtectionConfigAPIResponseSchema,
+  createDelegationRequestSchema,
+  createDelegationResponseSchema,
+  createDelegationAPIResponseSchema,
+  revokeDelegationRequestSchema,
+  revokeDelegationResponseSchema,
+  revokeDelegationAPIResponseSchema,
+} from "./schemas.js";
+
+export {
+  clearCacheRequestSchema,
+  clearCacheResponseSchema,
+} from "./admin-schemas.js";
+
+// Endpoint exports
+export {
+  AGENTSHIELD_API_BASE,
+  AGENTSHIELD_ENDPOINTS,
+  AGENTSHIELD_METHODS,
+} from "./endpoints.js";