@kya-os/contracts 1.5.3-canary.2 → 1.5.3-canary.20

package/src/well-known/index.ts

@@ -0,0 +1,237 @@
+/**
+ * MCP-I Well-Known Endpoints Specification
+ *
+ * This module defines the types for well-known endpoints as specified in the
+ * MCP-I protocol. These endpoints provide identity discovery and verification
+ * capabilities for MCP-I agents.
+ *
+ * @module @kya-os/contracts/well-known
+ */
+
+import { z } from 'zod';
+
+/**
+ * DID Document as per W3C DID specification
+ * Returned from /.well-known/did.json
+ */
+export interface DIDDocument {
+  '@context': string[];
+  id: string;
+  verificationMethod: Array<{
+    id: string;
+    type: string;
+    controller: string;
+    publicKeyBase64?: string;
+    publicKeyMultibase?: string;
+  }>;
+  authentication?: string[];
+  assertionMethod?: string[];
+  capabilityInvocation?: string[];
+  capabilityDelegation?: string[];
+  keyAgreement?: string[];
+  service?: Array<{
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+  }>;
+}
+
+/**
+ * Agent Document for MCP-I capability discovery
+ * Returned from /.well-known/agent.json
+ */
+export interface AgentDocument {
+  /** The agent's DID */
+  id: string;
+
+  /** Capabilities supported by this agent */
+  capabilities: {
+    'mcp-i': Array<'handshake' | 'signing' | 'verification' | 'delegation' | 'proof-generation'>;
+    [key: string]: string[];
+  };
+
+  /** Optional metadata about the agent */
+  metadata?: {
+    name?: string;
+    serviceEndpoint?: string;
+    version?: string;
+    description?: string;
+  };
+}
+
+/**
+ * MCP Identity information
+ * Returned from /.well-known/mcp-identity
+ */
+export interface MCPIdentity {
+  /** The agent's DID */
+  did: string;
+
+  /** The agent's public key */
+  publicKey: string;
+
+  /** Service name */
+  serviceName: string;
+
+  /** Service endpoint URL */
+  serviceEndpoint: string;
+
+  /** Timestamp of when this was generated */
+  timestamp: number;
+
+  /** Optional additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Well-known endpoint handler configuration
+ */
+export interface WellKnownConfig {
+  /** Service name to advertise */
+  serviceName?: string;
+
+  /** Service endpoint URL */
+  serviceEndpoint?: string;
+
+  /** Additional metadata to include */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Well-known endpoint response
+ */
+export interface WellKnownResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/**
+ * Well-known endpoint paths
+ */
+export enum WellKnownPath {
+  DID_DOCUMENT = '/.well-known/did.json',
+  AGENT_DOCUMENT = '/.well-known/agent.json',
+  MCP_IDENTITY = '/.well-known/mcp-identity',
+  TOOL_PROTECTIONS = '/.well-known/tool-protections.json',
+}
+
+/**
+ * Zod Schemas for Validation
+ */
+
+export const DIDDocumentSchema = z.object({
+  '@context': z.array(z.string()),
+  id: z.string(),
+  verificationMethod: z.array(z.object({
+    id: z.string(),
+    type: z.string(),
+    controller: z.string(),
+    publicKeyBase64: z.string().optional(),
+    publicKeyMultibase: z.string().optional()
+  })),
+  authentication: z.array(z.string()).optional(),
+  assertionMethod: z.array(z.string()).optional(),
+  capabilityInvocation: z.array(z.string()).optional(),
+  capabilityDelegation: z.array(z.string()).optional(),
+  keyAgreement: z.array(z.string()).optional(),
+  service: z.array(z.object({
+    id: z.string(),
+    type: z.string(),
+    serviceEndpoint: z.string()
+  })).optional()
+});
+
+export const AgentDocumentSchema = z.object({
+  id: z.string(),
+  capabilities: z.object({
+    'mcp-i': z.array(z.enum(['handshake', 'signing', 'verification', 'delegation', 'proof-generation']))
+  }).catchall(z.array(z.string())),
+  metadata: z.object({
+    name: z.string().optional(),
+    serviceEndpoint: z.string().optional(),
+    version: z.string().optional(),
+    description: z.string().optional()
+  }).optional()
+});
+
+export const MCPIdentitySchema = z.object({
+  did: z.string(),
+  publicKey: z.string(),
+  serviceName: z.string(),
+  serviceEndpoint: z.string(),
+  timestamp: z.number(),
+  metadata: z.record(z.unknown()).optional()
+});
+
+export const WellKnownConfigSchema = z.object({
+  serviceName: z.string().optional(),
+  serviceEndpoint: z.string().optional(),
+  metadata: z.record(z.unknown()).optional()
+});
+
+export const WellKnownResponseSchema = z.object({
+  status: z.number(),
+  headers: z.record(z.string()),
+  body: z.string()
+});
+
+/**
+ * Type Guards
+ */
+
+export function isDIDDocument(obj: any): obj is DIDDocument {
+  return DIDDocumentSchema.safeParse(obj).success;
+}
+
+export function isAgentDocument(obj: any): obj is AgentDocument {
+  return AgentDocumentSchema.safeParse(obj).success;
+}
+
+export function isMCPIdentity(obj: any): obj is MCPIdentity {
+  return MCPIdentitySchema.safeParse(obj).success;
+}
+
+/**
+ * Validation Functions
+ */
+
+export function validateDIDDocument(obj: any): DIDDocument {
+  return DIDDocumentSchema.parse(obj);
+}
+
+export function validateAgentDocument(obj: any): AgentDocument {
+  return AgentDocumentSchema.parse(obj);
+}
+
+export function validateMCPIdentity(obj: any): MCPIdentity {
+  return MCPIdentitySchema.parse(obj);
+}
+
+/**
+ * Utility Functions
+ */
+
+/**
+ * Check if a path is a well-known endpoint
+ */
+export function isWellKnownPath(path: string): boolean {
+  return Object.values(WellKnownPath).includes(path as WellKnownPath);
+}
+
+/**
+ * Get the content type for a well-known endpoint
+ */
+export function getWellKnownContentType(path: WellKnownPath | string): string {
+  switch (path) {
+    case WellKnownPath.DID_DOCUMENT:
+      return 'application/did+json';
+    case WellKnownPath.AGENT_DOCUMENT:
+    case WellKnownPath.TOOL_PROTECTIONS:
+      return 'application/json';
+    case WellKnownPath.MCP_IDENTITY:
+      return 'application/json';
+    default:
+      return 'application/json';
+  }
+}