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

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";

package/src/agentshield-api/schemas.ts

@@ -0,0 +1,304 @@
+/**
+ * AgentShield/Bouncer API Zod Validation Schemas
+ *
+ * Runtime validation schemas matching the API contract types.
+ * These schemas ensure request/response validation before sending/receiving.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+import { z } from "zod";
+import { DetachedProofSchema } from "../proof.js";
+import { DelegationRecordSchema } from "../delegation/index.js";
+
+/**
+ * Standard error schema
+ */
+export const agentShieldAPIErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Standard API response wrapper schema
+ */
+export const agentShieldAPIResponseSchema = <T extends z.ZodTypeAny>(
+  dataSchema: T
+) =>
+  z.object({
+    success: z.boolean(),
+    data: dataSchema,
+    metadata: z
+      .object({
+        requestId: z.string(),
+        timestamp: z.string(),
+      })
+      .optional(),
+  });
+
+// ============================================================================
+// Proof Submission Schemas
+// ============================================================================
+
+/**
+ * Tool Call Context Schema (AgentShield Extension)
+ * Optional plaintext context for dashboard enrichment
+ */
+const toolCallContextSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  args: z.record(z.unknown()),
+  result: z.unknown().optional(),
+  scopeId: z.string().min(1, "scopeId is required to link context to proof"),
+  userIdentifier: z.string().optional(),
+});
+
+/**
+ * Consent Event Context Schema
+ * Represents consent-related events for audit tracking
+ */
+const consentEventContextSchema = z.object({
+  eventType: z.enum([
+    "consent:page_viewed",
+    "consent:approved",
+    "consent:delegation_created",
+    "consent:credential_required"
+  ]),
+  timestamp: z.number().int().positive(),
+  sessionId: z.string().min(1),
+  userDid: z.string().optional(),
+  agentDid: z.string().min(1),
+  targetTools: z.array(z.string()).min(1), // ALWAYS array
+  scopes: z.array(z.string()).min(0),
+  delegationId: z.string().uuid().optional(),
+  projectId: z.string().uuid(),
+  termsAccepted: z.boolean().optional(),
+  credentialStatus: z.enum(["present", "required", "obtained"]).optional(),
+  oauthIdentity: z.object({
+    provider: z.string(),
+    identifier: z.string(),
+  }).optional(),
+});
+
+/**
+ * Proof submission request schema
+ */
+export const proofSubmissionRequestSchema = z.object({
+  session_id: z.string().max(100), // AgentShield session ID (may differ from MCP-I sessionId)
+  delegation_id: z.string().uuid().nullish(),
+  proofs: z.array(DetachedProofSchema).min(1),
+  // AgentShield extension: Optional context for dashboard enrichment
+  context: z
+    .object({
+      toolCalls: z.array(toolCallContextSchema).optional(),
+      consentEvents: z.array(consentEventContextSchema).optional(), // NEW: Consent events for audit tracking
+      mcpServerUrl: z.string().url().optional(), // MCP server URL for tool discovery
+    })
+    .optional(),
+});
+
+/**
+ * Proof submission response schema
+ */
+export const proofSubmissionResponseSchema = z.object({
+  success: z.boolean(),
+  accepted: z.number().int().min(0),
+  rejected: z.number().int().min(0),
+  outcomes: z.record(z.string(), z.number().int().min(0)).optional(), // Record<BouncerOutcome, number> - Optional because API may return empty object or omit it
+  errors: z
+    .array(
+      z.object({
+        proof_index: z.number().int().min(0),
+        error: z.object({
+          code: z.string(),
+          message: z.string(),
+          details: z.record(z.unknown()).optional(),
+        }),
+      })
+    )
+    .optional(),
+});
+
+// ============================================================================
+// Delegation Verification Schemas
+// ============================================================================
+
+/**
+ * Delegation credential schema
+ */
+export const delegationCredentialSchema = z.object({
+  agent_did: z.string(),
+  user_id: z.string().optional(),
+  user_identifier: z.string().optional(),
+  scopes: z.array(z.string()),
+  constraints: z.record(z.unknown()).optional(),
+  issued_at: z.number().int().positive(),
+  created_at: z.number().int().positive(),
+});
+
+/**
+ * Delegation verification request schema
+ */
+export const verifyDelegationRequestSchema = z.object({
+  agent_did: z.string(),
+  credential_jwt: z.string().optional(), // Optional, omit (don't set to empty string) when not available for OAuth flow
+  delegation_token: z.string().optional(), // Optional, for stateless MCP servers
+  scopes: z.array(z.string()).optional(), // Optional, can be empty array
+  timestamp: z.number().int().positive().optional(),
+  client_info: z
+    .object({
+      ip_address: z.string().ip().optional(),
+      origin: z.string().url().optional(),
+      user_agent: z.string().optional(),
+    })
+    .optional(),
+}).partial({ scopes: true }); // Make scopes truly optional by using partial
+
+/**
+ * Delegation verification response schema
+ */
+export const verifyDelegationResponseSchema = z.object({
+  valid: z.boolean(),
+  delegation: DelegationRecordSchema.optional(),
+  delegation_id: z.string().uuid().optional(),
+  credential: delegationCredentialSchema.optional(),
+  error: agentShieldAPIErrorSchema.optional(),
+  reason: z.string().optional(),
+});
+
+/**
+ * Wrapped verification response schema
+ */
+export const verifyDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  verifyDelegationResponseSchema
+);
+
+// ============================================================================
+// Tool Protection Configuration Schemas
+// ============================================================================
+
+/**
+ * AgentShield tool protection schema (supports both snake_case and camelCase)
+ * This is the API-specific format, not the MCP-I spec schema
+ */
+export const agentShieldToolProtectionSchema = z
+  .object({
+    scopes: z.array(z.string()),
+    requires_delegation: z.boolean().optional(),
+    requiresDelegation: z.boolean().optional(),
+    required_scopes: z.array(z.string()).optional(),
+  })
+  .passthrough(); // Allow additional properties
+
+/**
+ * Tool protection config response schema
+ */
+export const toolProtectionConfigResponseSchema = z.object({
+  agent_did: z.string(),
+  tools: z.record(z.string(), agentShieldToolProtectionSchema),
+  reputation_threshold: z.number().min(0).max(1).optional(),
+  denied_agents: z.array(z.string()).optional(),
+  crisp_budget: z
+    .object({
+      max_tokens: z.number(),
+      max_cost: z.number(),
+      currency: z.string(),
+      time_window: z.string(),
+    })
+    .optional(),
+});
+
+/**
+ * Wrapped config response schema
+ */
+export const toolProtectionConfigAPIResponseSchema =
+  agentShieldAPIResponseSchema(toolProtectionConfigResponseSchema);
+
+// ============================================================================
+// Delegation Management Schemas
+// ============================================================================
+
+/**
+ * Create delegation request schema
+ *
+ * Note: AgentShield API accepts a simplified format, not the full DelegationRecord.
+ * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, user_identifier, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+export const createDelegationRequestSchema = z
+  .object({
+    agent_did: z.string().min(1),
+    scopes: z.array(z.string()).min(1),
+    expires_in_days: z.number().int().positive().optional(),
+    expires_at: z.string().datetime().optional(),
+    session_id: z.string().optional(),
+    project_id: z.string().uuid().optional(),
+    user_identifier: z.string().max(200).optional(), // Matches AgentShield's max(200)
+    custom_fields: z.record(z.unknown()).optional(),
+  })
+  .passthrough()
+  .refine(
+    (data) => {
+      // expires_in_days and expires_at are mutually exclusive
+      const hasExpiresInDays = data.expires_in_days !== undefined;
+      const hasExpiresAt = data.expires_at !== undefined;
+      return !(hasExpiresInDays && hasExpiresAt);
+    },
+    {
+      message:
+        "expires_in_days and expires_at are mutually exclusive - use one or the other, not both",
+      path: ["expires_in_days", "expires_at"],
+    }
+  );
+
+/**
+ * Create delegation response schema
+ *
+ * Canonical format returned by POST /api/v1/bouncer/delegations
+ *
+ * IMPORTANT: delegation_token is NOT returned by this endpoint.
+ * delegation_token is only available via OAuth callback flow (/api/v1/bouncer/oauth/callback)
+ * and is passed as a URL parameter, not in the API response body.
+ */
+export const createDelegationResponseSchema = z.object({
+  delegation_id: z.string().uuid(),
+  agent_did: z.string().min(1),
+  user_id: z.string().optional(),
+  user_identifier: z.string().optional(),
+  scopes: z.array(z.string()),
+  status: z.enum(['active', 'expired', 'revoked']), // Matches AgentShield's actual API behavior
+  issued_at: z.string().datetime(),
+  expires_at: z.string().datetime().nullable().optional(), // AgentShield allows null values
+  created_at: z.string().datetime(),
+});
+
+/**
+ * Wrapped creation response schema
+ */
+export const createDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  createDelegationResponseSchema
+);
+
+/**
+ * Revoke delegation request schema
+ */
+export const revokeDelegationRequestSchema = z.object({
+  reason: z.string().optional(),
+});
+
+/**
+ * Revoke delegation response schema
+ */
+export const revokeDelegationResponseSchema = z.object({
+  delegation_id: z.string().uuid(),
+  revoked: z.boolean(),
+  revoked_at: z.number().int().positive(),
+});
+
+/**
+ * Wrapped revocation response schema
+ */
+export const revokeDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  revokeDelegationResponseSchema
+);