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

package/src/dashboard-config/schemas.ts

@@ -0,0 +1,286 @@
+/**
+ * Dashboard Configuration Zod Schemas
+ * 
+ * Runtime validation schemas for dashboard configuration types.
+ * Used for validating API requests and responses.
+ * 
+ * @package @kya-os/contracts/dashboard-config
+ */
+
+import { z } from 'zod';
+import { ToolProtectionSchema, ToolProtectionMapSchema } from '../tool-protection/index.js';
+
+/**
+ * Identity configuration schema
+ */
+export const identityConfigSchema = z.object({
+  /**
+   * @deprecated Use serverDid instead. Will be removed in v2.0
+   */
+  agentDid: z.string().min(1).optional(),
+  serverDid: z.string().min(1),
+  environment: z.enum(['development', 'production']),
+  storageLocation: z.enum(['cloudflare-kv', 'file-system', 'env-vars']),
+});
+
+/**
+ * Proofing configuration schema
+ */
+export const proofingConfigSchema = z.object({
+  enabled: z.boolean(),
+  destinations: z.array(
+    z.object({
+      type: z.enum(['agentshield', 'kta', 'custom']),
+      apiUrl: z.string().url(),
+      apiKey: z.string().optional(),
+    })
+  ),
+  batchQueue: z.object({
+    maxBatchSize: z.number().int().positive().default(10),
+    flushIntervalMs: z.number().int().positive().default(5000),
+    maxRetries: z.number().int().nonnegative().default(3),
+  }),
+});
+
+/**
+ * Delegation verifier type schema
+ */
+const delegationVerifierTypeSchema = z.enum([
+  'agentshield',
+  'kta',
+  'memory',
+  'cloudflare-kv',
+  'redis',
+  'dynamodb',
+  'custom',
+]);
+
+/**
+ * Delegation configuration schema
+ */
+export const delegationConfigSchema = z.object({
+  enabled: z.boolean(),
+  enforceStrictly: z.boolean(),
+  verifier: z.object({
+    type: delegationVerifierTypeSchema,
+    apiUrl: z.string().url().optional(),
+    cacheTtl: z.number().int().positive().optional(),
+  }),
+  authorization: z.object({
+    authorizationUrl: z.string().url().optional(),
+    minReputationScore: z.number().int().min(0).max(100).optional(),
+    resumeTokenTtl: z.number().int().positive().optional(),
+    requireAuthForUnknown: z.boolean().optional(),
+  }),
+});
+
+/**
+ * Tool protection configuration schema
+ */
+export const toolProtectionConfigSchema = z.object({
+  source: z.enum(['agentshield', 'inline', 'file']),
+  agentShield: z.object({
+    apiUrl: z.string().url(),
+    cacheTtl: z.number().int().positive(),
+  }).optional(),
+  fallback: ToolProtectionMapSchema.optional(),
+});
+
+/**
+ * Audit configuration schema
+ */
+export const auditConfigSchema = z.object({
+  enabled: z.boolean(),
+  includeProofHashes: z.boolean(),
+  includePayloads: z.boolean(),
+});
+
+/**
+ * Session configuration schema
+ */
+export const sessionConfigSchema = z.object({
+  timestampSkewSeconds: z.number().int().positive().default(120),
+  ttlMinutes: z.number().int().positive().default(30),
+  absoluteLifetime: z.number().int().positive().optional(),
+});
+
+/**
+ * Cloudflare platform configuration schema
+ */
+export const cloudflarePlatformConfigSchema = z.object({
+  workers: z.object({
+    cpuMs: z.number().int().positive().default(50),
+    memoryMb: z.number().int().positive().default(128),
+  }),
+  kvNamespaces: z.array(
+    z.object({
+      name: z.string().min(1),
+      purpose: z.enum(['sessions', 'delegations', 'cache', 'general']),
+    })
+  ),
+  environmentVariables: z.array(
+    z.object({
+      name: z.string().min(1),
+      value: z.string(),
+      source: z.enum(['wrangler.toml', 'secrets', '.dev.vars']),
+    })
+  ),
+});
+
+/**
+ * Node.js platform configuration schema
+ */
+export const nodePlatformConfigSchema = z.object({
+  server: z.object({
+    port: z.number().int().positive().default(3000),
+    host: z.string().default('0.0.0.0'),
+    cors: z.boolean().default(true),
+    timeout: z.number().int().positive().default(30000),
+  }),
+  storage: z.object({
+    type: z.enum(['memory', 'redis', 'postgres', 'mongodb']),
+    connection: z.object({
+      host: z.string().optional(),
+      port: z.number().int().positive().optional(),
+      database: z.string().optional(),
+    }).optional(),
+  }),
+});
+
+/**
+ * Vercel platform configuration schema
+ */
+export const vercelPlatformConfigSchema = z.object({
+  environmentVariables: z.array(
+    z.object({
+      name: z.string().min(1),
+      value: z.string(),
+      source: z.enum(['vercel-dashboard', '.env.local']),
+    })
+  ),
+  edgeRuntime: z.object({
+    maxDuration: z.number().int().positive().optional(),
+    regions: z.array(z.string()).optional(),
+  }).optional(),
+});
+
+/**
+ * Platform configuration schema
+ */
+export const platformConfigSchema = z.object({
+  type: z.enum(['cloudflare', 'node', 'vercel']),
+  cloudflare: cloudflarePlatformConfigSchema.optional(),
+  node: nodePlatformConfigSchema.optional(),
+  vercel: vercelPlatformConfigSchema.optional(),
+});
+
+/**
+ * Metadata schema
+ */
+export const configMetadataSchema = z.object({
+  version: z.string(),
+  lastUpdated: z.string(),
+  source: z.enum(['dashboard', 'code', 'mixed']),
+  serverUrl: z.string().url().optional(),
+  deploymentStatus: z.enum(['active', 'inactive', 'error']).optional(),
+});
+
+/**
+ * Complete MCP-I Server Configuration schema
+ */
+export const mcpIServerConfigSchema = z.object({
+  identity: identityConfigSchema,
+  proofing: proofingConfigSchema,
+  delegation: delegationConfigSchema,
+  toolProtection: toolProtectionConfigSchema,
+  audit: auditConfigSchema,
+  session: sessionConfigSchema,
+  platform: platformConfigSchema,
+  metadata: configMetadataSchema,
+});
+
+/**
+ * Get server config request schema
+ */
+export const getServerConfigRequestSchema = z.object({
+  projectId: z.string().min(1),
+});
+
+/**
+ * Get server config response schema
+ */
+export const getServerConfigResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.object({
+    config: mcpIServerConfigSchema,
+  }),
+  metadata: z.object({
+    requestId: z.string().optional(),
+    timestamp: z.string().optional(),
+  }).optional(),
+});
+
+/**
+ * Update server config request schema
+ */
+export const updateServerConfigRequestSchema = z.object({
+  projectId: z.string().min(1),
+  config: mcpIServerConfigSchema.partial(),
+});
+
+/**
+ * Update server config response schema
+ */
+export const updateServerConfigResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.object({
+    config: mcpIServerConfigSchema,
+    changes: z.array(
+      z.object({
+        path: z.string(),
+        oldValue: z.unknown(),
+        newValue: z.unknown(),
+      })
+    ),
+  }),
+  metadata: z.object({
+    requestId: z.string().optional(),
+    timestamp: z.string().optional(),
+  }).optional(),
+});
+
+/**
+ * Validate server config request schema
+ */
+export const validateServerConfigRequestSchema = z.object({
+  projectId: z.string().min(1),
+  config: mcpIServerConfigSchema.partial(),
+});
+
+/**
+ * Validate server config response schema
+ */
+export const validateServerConfigResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.object({
+    valid: z.boolean(),
+    errors: z.array(
+      z.object({
+        path: z.string(),
+        message: z.string(),
+        code: z.string(),
+      })
+    ).optional(),
+    warnings: z.array(
+      z.object({
+        path: z.string(),
+        message: z.string(),
+      })
+    ).optional(),
+  }),
+  metadata: z.object({
+    requestId: z.string().optional(),
+    timestamp: z.string().optional(),
+  }).optional(),
+});
+

package/src/dashboard-config/types.ts

@@ -0,0 +1,404 @@
+/**
+ * Dashboard Configuration Types
+ * 
+ * Type definitions for AgentShield dashboard server configuration management API.
+ * These types ensure parity between xmcp-i and AgentShield dashboard implementations.
+ * 
+ * @package @kya-os/contracts/dashboard-config
+ */
+
+import type { ToolProtectionMap } from '../tool-protection/index.js';
+import type { ProofDestination } from '../config/proofing.js';
+import type { DelegationVerifierType } from '../config/delegation.js';
+
+/**
+ * MCP-I Server Configuration (Dashboard View Model)
+ * 
+ * This is a flattened, UI-friendly representation of server configuration
+ * used by the AgentShield dashboard for configuration management.
+ * 
+ * This type differs from MCPIConfig in that it:
+ * - Includes platform-specific details
+ * - Includes read-only metadata
+ * - Flattens nested structures for easier UI rendering
+ * - Includes deployment status information
+ */
+export interface MCPIServerConfig {
+  // ============================================
+  // 1. IDENTITY CONFIGURATION
+  // ============================================
+  identity: {
+    /**
+     * MCP-I Server DID (public identifier)
+     * Identifies this server instance
+     * @deprecated Use serverDid instead. Will be removed in v2.0
+     */
+    agentDid?: string;
+
+    /**
+     * MCP-I Server DID (public identifier)
+     * Identifies this server instance
+     * Read-only, displayed for reference
+     */
+    serverDid: string;
+    
+    /**
+     * Environment mode
+     * Controls identity source: 'development' | 'production'
+     */
+    environment: 'development' | 'production';
+    
+    /**
+     * Identity storage location (read-only)
+     * Shows where identity is stored based on platform
+     */
+    storageLocation: 'cloudflare-kv' | 'file-system' | 'env-vars';
+  };
+
+  // ============================================
+  // 2. PROOFING CONFIGURATION
+  // ============================================
+  proofing: {
+    /**
+     * Enable proof submission
+     */
+    enabled: boolean;
+    
+    /**
+     * Proof destinations
+     * Where proofs are sent (AgentShield, KTA, etc.)
+     */
+    destinations: Array<{
+      type: 'agentshield' | 'kta' | 'custom';
+      apiUrl: string;
+      apiKey?: string; // Masked, only show if user has permission
+    }>;
+    
+    /**
+     * Batch queue settings
+     */
+    batchQueue: {
+      maxBatchSize: number; // Default: 10
+      flushIntervalMs: number; // Default: 5000
+      maxRetries: number; // Default: 3
+    };
+  };
+
+  // ============================================
+  // 3. DELEGATION CONFIGURATION
+  // ============================================
+  delegation: {
+    /**
+     * Enable delegation enforcement
+     */
+    enabled: boolean;
+    
+    /**
+     * Strict enforcement mode
+     * When true, blocks tools without delegation
+     * When false, logs warnings but allows execution
+     */
+    enforceStrictly: boolean;
+    
+    /**
+     * Delegation verifier settings
+     */
+    verifier: {
+      type: DelegationVerifierType;
+      apiUrl?: string;
+      cacheTtl?: number; // Default: 300000 (5 minutes)
+    };
+    
+    /**
+     * Authorization flow settings
+     */
+    authorization: {
+      authorizationUrl?: string;
+      minReputationScore?: number; // 0-100, default: 80
+      resumeTokenTtl?: number; // milliseconds, default: 3600000
+      requireAuthForUnknown?: boolean;
+    };
+  };
+
+  // ============================================
+  // 4. TOOL PROTECTION CONFIGURATION
+  // ============================================
+  toolProtection: {
+    /**
+     * Source of tool protection config
+     * 'agentshield' = Fetched from AgentShield API (dashboard-controlled)
+     * 'inline' = Defined in code/config file
+     * 'file' = Loaded from external file
+     */
+    source: 'agentshield' | 'inline' | 'file';
+    
+    /**
+     * AgentShield API settings (if source is 'agentshield')
+     */
+    agentShield?: {
+      apiUrl: string; // Default: 'https://kya.vouched.id'
+      cacheTtl: number; // Default: 300000 (5 minutes)
+    };
+    
+    /**
+     * Fallback configuration
+     * Used when API is unavailable
+     * Displayed as read-only (managed via /tools page)
+     */
+    fallback?: ToolProtectionMap;
+  };
+
+  // ============================================
+  // 5. AUDIT & LOGGING
+  // ============================================
+  audit: {
+    /**
+     * Enable audit logging
+     */
+    enabled: boolean;
+    
+    /**
+     * Include proof hashes in logs
+     */
+    includeProofHashes: boolean;
+    
+    /**
+     * Include full payloads in logs
+     * WARNING: May include sensitive data
+     */
+    includePayloads: boolean;
+  };
+
+  // ============================================
+  // 6. SESSION CONFIGURATION
+  // ============================================
+  session: {
+    /**
+     * Maximum time skew allowed (seconds)
+     * Default: 120
+     */
+    timestampSkewSeconds: number;
+    
+    /**
+     * Session TTL (minutes)
+     * Default: 30
+     */
+    ttlMinutes: number;
+    
+    /**
+     * Absolute session lifetime (minutes)
+     * Optional, max lifetime regardless of activity
+     */
+    absoluteLifetime?: number;
+  };
+
+  // ============================================
+  // 7. PLATFORM-SPECIFIC CONFIGURATION
+  // ============================================
+  platform: {
+    /**
+     * Platform type
+     */
+    type: 'cloudflare' | 'node' | 'vercel';
+    
+    /**
+     * Cloudflare-specific settings
+     */
+    cloudflare?: {
+      /**
+       * Workers runtime settings
+       */
+      workers: {
+        cpuMs: number; // Default: 50
+        memoryMb: number; // Default: 128
+      };
+      
+      /**
+       * KV namespace bindings (read-only)
+       * Shows which KV namespaces are configured
+       */
+      kvNamespaces: Array<{
+        name: string;
+        purpose: 'sessions' | 'delegations' | 'cache' | 'general';
+      }>;
+      
+      /**
+       * Environment variables (masked)
+       */
+      environmentVariables: Array<{
+        name: string;
+        value: string; // Masked (e.g., "sk_***")
+        source: 'wrangler.toml' | 'secrets' | '.dev.vars';
+      }>;
+    };
+    
+    /**
+     * Node.js-specific settings
+     */
+    node?: {
+      /**
+       * Server configuration
+       */
+      server: {
+        port: number; // Default: 3000
+        host: string; // Default: '0.0.0.0'
+        cors: boolean; // Default: true
+        timeout: number; // Default: 30000
+      };
+      
+      /**
+       * Storage configuration
+       */
+      storage: {
+        type: 'memory' | 'redis' | 'postgres' | 'mongodb';
+        connection?: {
+          host?: string;
+          port?: number;
+          database?: string;
+        };
+      };
+    };
+    
+    /**
+     * Vercel-specific settings
+     */
+    vercel?: {
+      /**
+       * Environment variables (masked)
+       */
+      environmentVariables: Array<{
+        name: string;
+        value: string; // Masked
+        source: 'vercel-dashboard' | '.env.local';
+      }>;
+      
+      /**
+       * Edge runtime configuration
+       */
+      edgeRuntime?: {
+        maxDuration?: number;
+        regions?: string[];
+      };
+    };
+  };
+
+  // ============================================
+  // 8. METADATA
+  // ============================================
+  metadata: {
+    /**
+     * Configuration version
+     */
+    version: string;
+    
+    /**
+     * Last updated timestamp
+     */
+    lastUpdated: string;
+    
+    /**
+     * Configuration source
+     * 'dashboard' = Managed via AgentShield dashboard
+     * 'code' = Defined in code (mcpi-runtime-config.ts)
+     * 'mixed' = Partially managed via dashboard
+     */
+    source: 'dashboard' | 'code' | 'mixed';
+    
+    /**
+     * Server deployment URL
+     */
+    serverUrl?: string;
+    
+    /**
+     * Server deployment status
+     */
+    deploymentStatus?: 'active' | 'inactive' | 'error';
+  };
+}
+
+/**
+ * API Request/Response types for dashboard config endpoints
+ */
+
+/**
+ * Request to get server configuration
+ * GET /api/v1/bouncer/projects/{projectId}/config
+ */
+export interface GetServerConfigRequest {
+  projectId: string;
+}
+
+/**
+ * Response from get server configuration endpoint
+ */
+export interface GetServerConfigResponse {
+  success: boolean;
+  data: {
+    config: MCPIServerConfig;
+  };
+  metadata?: {
+    requestId?: string;
+    timestamp?: string;
+  };
+}
+
+/**
+ * Request to update server configuration
+ * PUT /api/v1/bouncer/projects/{projectId}/config
+ */
+export interface UpdateServerConfigRequest {
+  projectId: string;
+  config: Partial<MCPIServerConfig>;
+}
+
+/**
+ * Response from update server configuration endpoint
+ */
+export interface UpdateServerConfigResponse {
+  success: boolean;
+  data: {
+    config: MCPIServerConfig;
+    changes: Array<{
+      path: string;
+      oldValue: unknown;
+      newValue: unknown;
+    }>;
+  };
+  metadata?: {
+    requestId?: string;
+    timestamp?: string;
+  };
+}
+
+/**
+ * Request to validate server configuration without saving
+ * POST /api/v1/bouncer/projects/{projectId}/config/validate
+ */
+export interface ValidateServerConfigRequest {
+  projectId: string;
+  config: Partial<MCPIServerConfig>;
+}
+
+/**
+ * Response from validate server configuration endpoint
+ */
+export interface ValidateServerConfigResponse {
+  success: boolean;
+  data: {
+    valid: boolean;
+    errors?: Array<{
+      path: string;
+      message: string;
+      code: string;
+    }>;
+    warnings?: Array<{
+      path: string;
+      message: string;
+    }>;
+  };
+  metadata?: {
+    requestId?: string;
+    timestamp?: string;
+  };
+}
+