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

package/src/consent/types.ts

@@ -0,0 +1,199 @@
+/**
+ * Consent Types
+ *
+ * TypeScript type definitions for consent page configuration and approval handling.
+ * These types are used for server-hosted consent pages in HTTP/SSE transports.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+
+/**
+ * Consent Branding Configuration
+ *
+ * Customization options for consent page appearance
+ */
+export interface ConsentBranding {
+  /** Primary brand color (hex format, e.g., '#0066CC') */
+  primaryColor?: string;
+
+  /** Logo URL for display on consent page */
+  logoUrl?: string;
+
+  /** Company/application name */
+  companyName?: string;
+
+  /** Theme preference ('light', 'dark', or 'auto' for system preference) */
+  theme?: 'light' | 'dark' | 'auto';
+}
+
+/**
+ * Consent Terms Configuration
+ *
+ * Terms of service or privacy policy information
+ */
+export interface ConsentTerms {
+  /** Full terms text (displayed on page) */
+  text?: string;
+
+  /** URL to terms document */
+  url?: string;
+
+  /** Version identifier for terms */
+  version?: string;
+
+  /** Whether terms acceptance is required */
+  required?: boolean;
+}
+
+/**
+ * Consent Custom Field
+ *
+ * Additional fields to collect during consent (e.g., email, preferences)
+ */
+export interface ConsentCustomField {
+  /** Field name (used as form field name, must be valid identifier) */
+  name: string;
+
+  /** Display label for the field */
+  label: string;
+
+  /** Field type */
+  type: 'text' | 'textarea' | 'checkbox' | 'select';
+
+  /** Whether field is required */
+  required: boolean;
+
+  /** Placeholder text */
+  placeholder?: string;
+
+  /** Options for select fields */
+  options?: Array<{ value: string; label: string }>;
+
+  /** Validation pattern (regex) */
+  pattern?: string;
+}
+
+/**
+ * Consent Page Configuration
+ *
+ * Complete configuration for rendering a consent page
+ */
+export interface ConsentPageConfig {
+  /** Tool name requiring authorization */
+  tool: string;
+
+  /** Description of what the tool does */
+  toolDescription: string;
+
+  /** Scopes being requested */
+  scopes: string[];
+
+  /** Agent DID requesting authorization */
+  agentDid: string;
+
+  /** Session ID for tracking */
+  sessionId: string;
+
+  /** Project ID from AgentShield */
+  projectId: string;
+
+  /** Branding configuration */
+  branding?: ConsentBranding;
+
+  /** Terms configuration */
+  terms?: ConsentTerms;
+
+  /** Custom fields to collect */
+  customFields?: ConsentCustomField[];
+
+  /** Server URL for form submission */
+  serverUrl: string;
+
+  /** Whether to auto-close window after success */
+  autoClose?: boolean;
+}
+
+/**
+ * Consent Approval Request
+ *
+ * Request payload when user approves consent
+ */
+export interface ConsentApprovalRequest {
+  /** Tool name */
+  tool: string;
+
+  /** Approved scopes */
+  scopes: string[];
+
+  /** Agent DID (snake_case for API compatibility) */
+  agent_did: string;
+
+  /** Session ID (snake_case for API compatibility) */
+  session_id: string;
+
+  /** Project ID (snake_case for API compatibility) */
+  project_id: string;
+
+  /** Whether terms were accepted */
+  termsAccepted: boolean;
+
+  /** Terms version (if applicable) */
+  termsVersion?: string;
+
+  /** Custom field values */
+  customFields?: Record<string, string | boolean>;
+}
+
+/**
+ * Consent Approval Response
+ *
+ * Response after processing consent approval
+ */
+export interface ConsentApprovalResponse {
+  /** Whether approval was successful */
+  success: boolean;
+
+  /** Delegation ID (if successful) */
+  delegation_id?: string;
+
+  /** Delegation token (if successful) */
+  delegation_token?: string;
+
+  /** Error message (if failed) */
+  error?: string;
+
+  /** Error code (if failed) */
+  error_code?: string;
+}
+
+/**
+ * Consent Configuration
+ *
+ * Complete consent configuration fetched from AgentShield or defaults
+ */
+export interface ConsentConfig {
+  /** Branding configuration */
+  branding?: ConsentBranding;
+
+  /** Terms configuration */
+  terms?: ConsentTerms;
+
+  /** Custom fields configuration */
+  customFields?: ConsentCustomField[];
+
+  /** UI preferences */
+  ui?: {
+    /** Theme preference */
+    theme?: 'light' | 'dark' | 'auto';
+
+    /** Whether popup mode is enabled */
+    popupEnabled?: boolean;
+
+    /** Whether to auto-close after success */
+    autoClose?: boolean;
+
+    /** Delay before auto-close (milliseconds) */
+    autoCloseDelay?: number;
+  };
+}
+

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

@@ -0,0 +1,86 @@
+{
+  "identity": {
+    "agentDid": "",
+    "environment": "development",
+    "storageLocation": "env-vars"
+  },
+  "proofing": {
+    "enabled": true,
+    "destinations": [
+      {
+        "type": "agentshield",
+        "apiUrl": "https://kya.vouched.id"
+      }
+    ],
+    "batchQueue": {
+      "maxBatchSize": 10,
+      "flushIntervalMs": 5000,
+      "maxRetries": 3
+    }
+  },
+  "delegation": {
+    "enabled": true,
+    "enforceStrictly": false,
+    "verifier": {
+      "type": "agentshield",
+      "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",
+    "agentShield": {
+      "apiUrl": "https://kya.vouched.id",
+      "cacheTtl": 300000
+    },
+    "fallback": {}
+  },
+  "audit": {
+    "enabled": true,
+    "includeProofHashes": false,
+    "includePayloads": false
+  },
+  "session": {
+    "timestampSkewSeconds": 120,
+    "ttlMinutes": 30
+  },
+  "platform": {
+    "type": "node",
+    "node": {
+      "server": {
+        "port": 3000,
+        "host": "0.0.0.0",
+        "cors": true,
+        "timeout": 30000
+      },
+      "storage": {
+        "type": "memory"
+      }
+    },
+    "cloudflare": {
+      "workers": {
+        "cpuMs": 50,
+        "memoryMb": 128
+      },
+      "kvNamespaces": [],
+      "environmentVariables": []
+    },
+    "vercel": {
+      "environmentVariables": [],
+      "edgeRuntime": {}
+    }
+  },
+  "metadata": {
+    "version": "1.0.0",
+    "lastUpdated": "",
+    "source": "dashboard",
+    "deploymentStatus": "inactive"
+  }
+}
+

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';
+