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

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

package/src/delegation/constraints.ts

@@ -0,0 +1,267 @@
+/**
+ * CRISP Delegation Constraints
+ *
+ * Types and schemas for CRISP (Constrained Resource Intent Specification Protocol)
+ * constraints on delegations. CRISP enables fine-grained authorization control.
+ *
+ * Related Spec: MCP-I §4.2
+ * Python Reference: Delegation-Documentation.md
+ */
+
+import { z } from 'zod';
+
+/**
+ * Currency types for CRISP budgets
+ */
+export const CurrencySchema = z.enum(['USD', 'ops', 'points']);
+export type Currency = z.infer<typeof CurrencySchema>;
+
+/**
+ * Window kind for budget enforcement
+ */
+export const WindowKindSchema = z.enum(['rolling', 'fixed']);
+export type WindowKind = z.infer<typeof WindowKindSchema>;
+
+/**
+ * Budget Window Schema
+ *
+ * Defines the time window for budget enforcement
+ */
+export const BudgetWindowSchema = z.object({
+  /** Type of window (rolling or fixed) */
+  kind: WindowKindSchema,
+
+  /** Duration in seconds */
+  durationSec: z.number().int().positive(),
+});
+
+export type BudgetWindow = z.infer<typeof BudgetWindowSchema>;
+
+/**
+ * CRISP Budget Schema
+ *
+ * Defines spending/usage limits for a delegation
+ */
+export const CrispBudgetSchema = z.object({
+  /** Unit of the budget */
+  unit: CurrencySchema,
+
+  /** Cap/limit for the budget */
+  cap: z.number().nonnegative(),
+
+  /** Optional time window for the budget */
+  window: BudgetWindowSchema.optional(),
+});
+
+export type CrispBudget = z.infer<typeof CrispBudgetSchema>;
+
+/**
+ * Scope matcher types
+ */
+export const ScopeMatcherSchema = z.enum(['exact', 'prefix', 'regex']);
+export type ScopeMatcher = z.infer<typeof ScopeMatcherSchema>;
+
+/**
+ * CRISP Scope Schema
+ *
+ * Defines what resources/actions are allowed in a delegation
+ */
+export const CrispScopeSchema = z.object({
+  /** Resource identifier (e.g., "api:users", "data:emails") */
+  resource: z.string().min(1),
+
+  /** How to match the resource */
+  matcher: ScopeMatcherSchema,
+
+  /** Optional additional constraints on this scope */
+  constraints: z.record(z.any()).optional(),
+});
+
+export type CrispScope = z.infer<typeof CrispScopeSchema>;
+
+/**
+ * Delegation Constraints Schema (CRISP)
+ *
+ * Complete constraint specification for a delegation
+ */
+export const DelegationConstraintsSchema = z.object({
+  /** Not valid before (Unix timestamp in seconds) */
+  notBefore: z.number().int().optional(),
+
+  /** Not valid after (Unix timestamp in seconds) */
+  notAfter: z.number().int().optional(),
+
+  /** Simple scopes array (for Phase 1 bouncer - simplified model) */
+  scopes: z.array(z.string()).optional(),
+
+  /**
+   * Optional target server DID(s) for this delegation
+   * If omitted, delegation is valid on any server accepting the scopes
+   * If specified, delegation is only valid on the specified server(s)
+   */
+  audience: z.union([
+    z.string().startsWith("did:"),
+    z.array(z.string().startsWith("did:"))
+  ]).optional(),
+
+  /** CRISP-specific constraints (full model) */
+  crisp: z.object({
+    /** Optional budget constraint */
+    budget: CrispBudgetSchema.optional(),
+
+    /** Required: at least one scope */
+    scopes: z.array(CrispScopeSchema).min(1),
+
+    /** Optional additional CRISP fields */
+  }).passthrough().optional(),
+}).passthrough(); // Allow extensibility
+
+export type DelegationConstraints = z.infer<typeof DelegationConstraintsSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate delegation constraints
+ *
+ * @param constraints - The constraints to validate
+ * @returns Validation result
+ */
+export function validateDelegationConstraints(constraints: unknown) {
+  return DelegationConstraintsSchema.safeParse(constraints);
+}
+
+/**
+ * Check if constraints have a valid time range
+ *
+ * @param constraints - The constraints to check
+ * @returns true if time range is valid or no time range specified
+ */
+export function hasValidTimeRange(constraints: DelegationConstraints): boolean {
+  if (constraints.notBefore === undefined && constraints.notAfter === undefined) {
+    return true;
+  }
+
+  if (constraints.notBefore !== undefined && constraints.notAfter !== undefined) {
+    return constraints.notBefore < constraints.notAfter;
+  }
+
+  return true;
+}
+
+/**
+ * Check if child constraints are within parent constraints
+ *
+ * This performs basic structural checks. Full chain validation
+ * requires runtime implementation.
+ *
+ * @param parent - Parent delegation constraints
+ * @param child - Child delegation constraints
+ * @returns true if child is within parent bounds
+ */
+export function areChildConstraintsValid(
+  parent: DelegationConstraints,
+  child: DelegationConstraints
+): boolean {
+  // Time bounds: child must be within parent
+  if (parent.notBefore !== undefined && child.notBefore !== undefined) {
+    if (child.notBefore < parent.notBefore) {
+      return false;
+    }
+  }
+
+  if (parent.notAfter !== undefined && child.notAfter !== undefined) {
+    if (child.notAfter > parent.notAfter) {
+      return false;
+    }
+  }
+
+  // Budget: child must be ≤ parent (if same unit)
+  if (
+    parent.crisp?.budget &&
+    child.crisp?.budget &&
+    parent.crisp.budget.unit === child.crisp.budget.unit
+  ) {
+    if (child.crisp.budget.cap > parent.crisp.budget.cap) {
+      return false;
+    }
+  }
+
+  // Scopes: child scopes must be subset of parent scopes
+  // This is a simplified check - full validation is complex
+  if (parent.crisp && child.crisp) {
+    const parentResources = new Set(
+      parent.crisp.scopes.map((s) => s.resource)
+    );
+    const allChildResourcesInParent = child.crisp.scopes.every((childScope) => {
+      // Check if child resource matches any parent resource
+      return parent.crisp!.scopes.some((parentScope) => {
+        if (parentScope.matcher === 'exact') {
+          return parentScope.resource === childScope.resource;
+        }
+        if (parentScope.matcher === 'prefix') {
+          return childScope.resource.startsWith(parentScope.resource);
+        }
+        // regex matching would require runtime regex evaluation
+        return true; // Can't validate regex at type level
+      });
+    });
+
+    return allChildResourcesInParent;
+  }
+
+  return true; // Can't validate if crisp is not present
+}
+
+/**
+ * Check if a resource matches a scope
+ *
+ * @param resource - The resource to check
+ * @param scope - The scope to match against
+ * @returns true if resource matches scope
+ */
+export function doesResourceMatchScope(
+  resource: string,
+  scope: CrispScope
+): boolean {
+  switch (scope.matcher) {
+    case 'exact':
+      return resource === scope.resource;
+    case 'prefix':
+      return resource.startsWith(scope.resource);
+    case 'regex':
+      try {
+        const regex = new RegExp(scope.resource);
+        return regex.test(resource);
+      } catch {
+        return false;
+      }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Constants
+ */
+
+/**
+ * Supported currency types
+ */
+export const SUPPORTED_CURRENCIES: Currency[] = ['USD', 'ops', 'points'];
+
+/**
+ * Supported scope matchers
+ */
+export const SUPPORTED_MATCHERS: ScopeMatcher[] = ['exact', 'prefix', 'regex'];
+
+/**
+ * Maximum reasonable budget cap (for validation)
+ */
+export const MAX_BUDGET_CAP = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Maximum reasonable window duration (10 years in seconds)
+ */
+export const MAX_WINDOW_DURATION_SEC = 10 * 365 * 24 * 60 * 60;

package/src/delegation/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Delegation Module Exports
+ *
+ * Types and schemas for delegation records and CRISP constraints
+ */
+
+export * from './schemas.js';
+export * from './constraints.js';