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

package/src/dashboard-config/types.ts

@@ -1,404 +0,0 @@
-/**
- * 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

@@ -1,267 +0,0 @@
-/**
- * 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

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