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

package/src/dashboard-config/default-config.ts

@@ -0,0 +1,266 @@
+/**
+ * Default Configuration for MCP-I Servers
+ *
+ * Provides safe, production-ready defaults for new user configurations.
+ * Used by AgentShield Dashboard, Scaffolder, and Runtime fallbacks.
+ *
+ * @package @kya-os/contracts/dashboard-config
+ */
+
+import type { MCPIServerConfig } from "./types.js";
+import { mcpIServerConfigSchema } from "./schemas.js";
+import { z } from "zod";
+
+/**
+ * Default configuration JSON content
+ * Embedded here to avoid TypeScript JSON import issues in build
+ */
+const defaultConfigJson = {
+  identity: {
+    // agentDid removed - deprecated, use serverDid instead
+    serverDid: "", // New field - will be populated when identity is generated
+    environment: "development" as const,
+    storageLocation: "env-vars" as const,
+  },
+  proofing: {
+    enabled: true,
+    destinations: [
+      {
+        type: "agentshield" as const,
+        apiUrl: "https://kya.vouched.id",
+      },
+    ],
+    batchQueue: {
+      maxBatchSize: 10,
+      flushIntervalMs: 5000,
+      maxRetries: 3,
+    },
+  },
+  delegation: {
+    enabled: true,
+    enforceStrictly: false,
+    verifier: {
+      type: "agentshield" as const,
+      apiUrl: "https://kya.vouched.id/api/v1/bouncer/delegations/verify",
+      cacheTtl: 300000,
+    },
+    authorization: {
+      authorizationUrl:
+        "https://kya.vouched.id/api/v1/bouncer/delegations/authorize",
+      minReputationScore: 80,
+      resumeTokenTtl: 3600000,
+      requireAuthForUnknown: false,
+    },
+  },
+  toolProtection: {
+    source: "agentshield" as const,
+    agentShield: {
+      apiUrl: "https://kya.vouched.id",
+      cacheTtl: 300000,
+    },
+    fallback: {},
+  },
+  audit: {
+    enabled: true,
+    includeProofHashes: false,
+    includePayloads: false,
+  },
+  session: {
+    timestampSkewSeconds: 120,
+    ttlMinutes: 30,
+  },
+  platform: {
+    type: "node" as const,
+    node: {
+      server: {
+        port: 3000,
+        host: "0.0.0.0",
+        cors: true,
+        timeout: 30000,
+      },
+      storage: {
+        type: "memory" as const,
+      },
+    },
+    cloudflare: {
+      workers: {
+        cpuMs: 50,
+        memoryMb: 128,
+      },
+      kvNamespaces: [],
+      environmentVariables: [],
+    },
+    vercel: {
+      environmentVariables: [],
+      edgeRuntime: {},
+    },
+  },
+  metadata: {
+    version: "1.0.0",
+    lastUpdated: "",
+    source: "dashboard" as const,
+    deploymentStatus: "inactive" as const,
+  },
+};
+
+/**
+ * Relaxed schema for default config validation
+ * Allows empty strings for fields that will be populated later
+ *
+ * Note: Empty `agentDid` is valid for new/incomplete configurations.
+ * This allows users to create configs before registering their agent DID.
+ * The base schema (mcpIServerConfigSchema) requires non-empty agentDid for
+ * complete configurations, but defaults allow empty to support progressive
+ * configuration.
+ */
+const defaultConfigSchema = mcpIServerConfigSchema.extend({
+  identity: mcpIServerConfigSchema.shape.identity.extend({
+    agentDid: z.string().optional(), // Allow empty string or undefined for defaults (deprecated)
+    serverDid: z.string(), // Allow empty string for defaults (will be populated later)
+  }),
+  metadata: mcpIServerConfigSchema.shape.metadata.extend({
+    lastUpdated: z.string(), // Allow empty string (will be set dynamically)
+  }),
+});
+
+/**
+ * Default configuration object
+ *
+ * This is the base default configuration used when creating new user configs.
+ * Platform-specific defaults are available via getDefaultConfigForPlatform().
+ */
+export const defaultConfig: MCPIServerConfig = defaultConfigSchema.parse(
+  defaultConfigJson
+) as MCPIServerConfig;
+
+/**
+ * Platform-specific default configurations
+ */
+const platformDefaults = {
+  node: {
+    platform: {
+      type: "node" as const,
+      node: {
+        server: {
+          port: 3000,
+          host: "0.0.0.0",
+          cors: true,
+          timeout: 30000,
+        },
+        storage: {
+          type: "memory" as const,
+        },
+      },
+    },
+  },
+  cloudflare: {
+    platform: {
+      type: "cloudflare" as const,
+      cloudflare: {
+        workers: {
+          cpuMs: 50,
+          memoryMb: 128,
+        },
+        kvNamespaces: [],
+        environmentVariables: [],
+      },
+    },
+  },
+  vercel: {
+    platform: {
+      type: "vercel" as const,
+      vercel: {
+        environmentVariables: [],
+        edgeRuntime: {},
+      },
+    },
+  },
+};
+
+/**
+ * Get default configuration for a specific platform
+ *
+ * Returns the base default config merged with platform-specific defaults.
+ *
+ * @param platform - Platform type ('node', 'cloudflare', or 'vercel')
+ * @returns Platform-specific default configuration
+ *
+ * @example
+ * ```typescript
+ * const nodeConfig = getDefaultConfigForPlatform('node');
+ * const cloudflareConfig = getDefaultConfigForPlatform('cloudflare');
+ * ```
+ */
+export function getDefaultConfigForPlatform(
+  platform: "node" | "cloudflare" | "vercel"
+): MCPIServerConfig {
+  const platformDefault = platformDefaults[platform];
+
+  return {
+    ...defaultConfig,
+    platform: platformDefault.platform,
+  } as MCPIServerConfig;
+}
+
+/**
+ * Deep merge utility for objects
+ */
+function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  source: Partial<T>
+): T {
+  const result = { ...target } as T;
+
+  for (const key in source) {
+    const sourceValue = source[key];
+    if (
+      sourceValue &&
+      typeof sourceValue === "object" &&
+      !Array.isArray(sourceValue) &&
+      sourceValue !== null
+    ) {
+      const targetValue = target[key];
+      if (
+        targetValue &&
+        typeof targetValue === "object" &&
+        !Array.isArray(targetValue) &&
+        targetValue !== null
+      ) {
+        result[key] = deepMerge(
+          targetValue as Record<string, unknown>,
+          sourceValue as Record<string, unknown>
+        ) as T[Extract<keyof T, string>];
+      }
+    } else if (sourceValue !== undefined) {
+      result[key] = sourceValue as T[Extract<keyof T, string>];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge partial configuration with defaults
+ *
+ * Deep merges a partial configuration object with the base defaults,
+ * ensuring all required fields are present.
+ *
+ * @param partial - Partial configuration to merge with defaults
+ * @returns Complete configuration with defaults applied
+ *
+ * @example
+ * ```typescript
+ * const config = mergeWithDefaults({
+ *   proofing: { enabled: false },
+ *   identity: { environment: 'production' }
+ * });
+ * ```
+ */
+export function mergeWithDefaults(
+  partial: Partial<MCPIServerConfig>
+): MCPIServerConfig {
+  return deepMerge(
+    defaultConfig as unknown as Record<string, unknown>,
+    partial as unknown as Record<string, unknown>
+  ) as unknown as MCPIServerConfig;
+}

package/src/dashboard-config/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Dashboard Configuration Module
+ * 
+ * Central export point for dashboard configuration types and schemas.
+ * 
+ * @package @kya-os/contracts/dashboard-config
+ */
+
+// Type exports
+export type {
+  MCPIServerConfig,
+  GetServerConfigRequest,
+  GetServerConfigResponse,
+  UpdateServerConfigRequest,
+  UpdateServerConfigResponse,
+  ValidateServerConfigRequest,
+  ValidateServerConfigResponse,
+} from './types.js';
+
+// Schema exports
+export {
+  identityConfigSchema,
+  proofingConfigSchema,
+  delegationConfigSchema,
+  toolProtectionConfigSchema,
+  auditConfigSchema,
+  sessionConfigSchema,
+  platformConfigSchema,
+  cloudflarePlatformConfigSchema,
+  nodePlatformConfigSchema,
+  vercelPlatformConfigSchema,
+  configMetadataSchema,
+  mcpIServerConfigSchema,
+  getServerConfigRequestSchema,
+  getServerConfigResponseSchema,
+  updateServerConfigRequestSchema,
+  updateServerConfigResponseSchema,
+  validateServerConfigRequestSchema,
+  validateServerConfigResponseSchema,
+} from './schemas.js';
+
+// Default configuration exports
+export {
+  defaultConfig,
+  getDefaultConfigForPlatform,
+  mergeWithDefaults,
+} from './default-config.js';
+

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(),
+});
+