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

package/src/config/builder.ts

@@ -0,0 +1,97 @@
+/**
+ * Configuration Builder Utilities
+ *
+ * Shared utilities for building MCP-I configuration objects with sensible defaults.
+ * These functions are platform-agnostic and can be used by any adapter/platform.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+import type { MCPIBaseConfig } from './base.js';
+import type { RuntimeIdentityConfig } from './identity.js';
+import type { ProofingConfig } from './proofing.js';
+import type { DelegationConfig, DelegationVerifierConfig, AuthorizationConfig } from './delegation.js';
+import type { ToolProtectionSourceConfig } from './tool-protection.js';
+
+/**
+ * Complete runtime configuration type
+ * This can be extended by platform-specific configs
+ */
+export interface MCPIConfig extends MCPIBaseConfig {
+  identity?: RuntimeIdentityConfig;
+  proofing?: ProofingConfig;
+  delegation?: DelegationConfig;
+  toolProtection?: ToolProtectionSourceConfig;
+}
+
+/**
+ * Build base MCPIConfig that works across all platforms
+ *
+ * Creates a platform-agnostic configuration object with sensible defaults
+ * for identity, proofing, delegation, audit, and session management.
+ *
+ * @param env - Environment variables object (works with process.env or Cloudflare env)
+ * @returns Complete MCPIConfig object
+ */
+export function buildBaseConfig(env: Record<string, any>): MCPIConfig {
+  const environment = (env.MCPI_ENV || env.ENVIRONMENT || 'development') as 'development' | 'production';
+  const isDevelopment = environment === 'development';
+
+  const baseConfig: MCPIConfig = {
+    environment,
+
+    identity: {
+      enabled: true,
+      environment,
+      devIdentityPath: '.mcpi/identity.json'
+    } as RuntimeIdentityConfig,
+
+    proofing: {
+      enabled: true,
+      batchQueue: {
+        destinations: [
+          {
+            type: 'agentshield' as const,
+            apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+            apiKey: env.AGENTSHIELD_API_KEY
+          }
+        ],
+        maxBatchSize: 10,
+        flushIntervalMs: 5000,
+        maxRetries: 3,
+        debug: isDevelopment
+      }
+    } as ProofingConfig,
+
+    delegation: {
+      enabled: true,
+      enforceDelegations: true,
+      verifier: {
+        type: 'agentshield' as const,
+        apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+        apiKey: env.AGENTSHIELD_API_KEY || '',
+        cacheTtl: 60000, // 1 minute cache
+        debug: isDevelopment
+      } as DelegationVerifierConfig,
+      authorization: {
+        authorizationUrl: env.AUTHORIZATION_URL || `${env.AGENTSHIELD_API_URL || 'https://kya.vouched.id'}/authorize`,
+        resumeTokenTtl: 600000, // 10 minutes
+        minReputationScore: 76
+      } as AuthorizationConfig
+    } as DelegationConfig,
+
+    audit: {
+      enabled: true,
+      includeProofHashes: false,
+      includePayloads: false
+    },
+
+    session: {
+      timestampSkewSeconds: 120,
+      ttlMinutes: 30
+    }
+  };
+
+  return baseConfig;
+}
+

package/src/config/delegation.ts

@@ -0,0 +1,232 @@
+/**
+ * Delegation Configuration Types
+ *
+ * Configuration for delegation verification, authorization flows,
+ * and consent management in MCP-I.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+/**
+ * Delegation verifier types
+ */
+export type DelegationVerifierType =
+  | 'agentshield'    // AgentShield API
+  | 'kta'            // Know That AI
+  | 'memory'         // In-memory (development)
+  | 'cloudflare-kv'  // Cloudflare KV storage
+  | 'redis'          // Redis cache
+  | 'dynamodb'       // AWS DynamoDB
+  | 'custom';        // Custom implementation
+
+/**
+ * Delegation verifier configuration
+ * Controls how delegations are verified and cached
+ */
+export interface DelegationVerifierConfig {
+  /**
+   * Type of verifier to use
+   */
+  type: DelegationVerifierType;
+
+  /**
+   * API URL for remote verifiers (agentshield, kta)
+   * @example 'https://kya.vouched.id'
+   */
+  apiUrl?: string;
+
+  /**
+   * API key for authentication with remote verifiers
+   */
+  apiKey?: string;
+
+  /**
+   * Cache time-to-live in milliseconds
+   * How long to cache delegation verification results
+   * @default 300000 (5 minutes)
+   */
+  cacheTtl?: number;
+
+  /**
+   * Custom verifier implementation
+   * Required when type is 'custom'
+   */
+  customVerifier?: {
+    verify: (agentDid: string, scopes: string[]) => Promise<boolean>;
+    invalidate?: (agentDid: string) => Promise<void>;
+  };
+
+  /**
+   * Additional verifier-specific options
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Authorization configuration
+ * Controls consent flows and authorization requirements
+ */
+export interface AuthorizationConfig {
+  /**
+   * Base URL for authorization/consent flow
+   * Users are redirected here when delegation is required
+   * @example 'https://kya.vouched.id/bouncer/consent'
+   */
+  authorizationUrl?: string;
+
+  /**
+   * KTA (Know That AI) configuration for reputation checks
+   */
+  kta?: {
+    /**
+     * KTA API base URL
+     */
+    apiUrl: string;
+
+    /**
+     * API key for KTA
+     */
+    apiKey?: string;
+  };
+
+  /**
+   * Minimum reputation score to bypass authorization
+   * Agents with reputation above this threshold don't need explicit consent
+   * Range: 0-100
+   * @default 80
+   */
+  minReputationScore?: number;
+
+  /**
+   * Resume token TTL in milliseconds
+   * How long a resume token remains valid
+   * @default 3600000 (1 hour)
+   */
+  resumeTokenTtl?: number;
+
+  /**
+   * Require authorization for unknown agents
+   * If false, unknown agents are allowed by default
+   * @default true
+   */
+  requireAuthForUnknown?: boolean;
+
+  /**
+   * Custom authorization URL builder
+   * Allows customization of consent URL generation
+   */
+  buildAuthUrl?: (toolName: string, scopes: string[], context: any) => string;
+}
+
+/**
+ * Delegation configuration (platform-agnostic)
+ *
+ * Controls delegation verification, authorization flows, and
+ * tool protection enforcement.
+ */
+export interface DelegationConfig {
+  /**
+   * Enable delegation features
+   * When false, all tools are accessible without delegation
+   * @default false (for backward compatibility)
+   */
+  enabled: boolean;
+
+  /**
+   * Enforce delegation requirements strictly
+   * When true, tools requiring delegation will fail without valid delegation
+   * When false, logs warnings but allows execution
+   * @default true in production, false in development
+   */
+  enforceDelegations?: boolean;
+
+  /**
+   * Delegation verifier configuration
+   * Controls how delegations are verified
+   */
+  verifier: DelegationVerifierConfig;
+
+  /**
+   * Authorization configuration
+   * Controls consent flows and reputation checks
+   */
+  authorization?: AuthorizationConfig;
+
+  /**
+   * Enable debug logging for delegation operations
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Delegation record structure
+ * Represents a delegation from a user to an agent
+ */
+export interface DelegationRecord {
+  /**
+   * Unique identifier for this delegation
+   */
+  id: string;
+
+  /**
+   * User who granted the delegation
+   */
+  userId: string;
+
+  /**
+   * Agent DID receiving the delegation
+   */
+  agentDid: string;
+
+  /**
+   * Scopes granted in this delegation
+   * @example ['files:read', 'files:write']
+   */
+  scopes: string[];
+
+  /**
+   * ISO 8601 timestamp when delegation was created
+   */
+  createdAt: string;
+
+  /**
+   * ISO 8601 timestamp when delegation expires
+   */
+  expiresAt?: string;
+
+  /**
+   * Whether this delegation has been revoked
+   */
+  revoked?: boolean;
+
+  /**
+   * Additional constraints on the delegation
+   */
+  constraints?: {
+    /**
+     * IP addresses allowed to use this delegation
+     */
+    allowedIps?: string[];
+
+    /**
+     * Origins allowed to use this delegation
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * Maximum number of uses
+     */
+    maxUses?: number;
+
+    /**
+     * Current number of uses
+     */
+    currentUses?: number;
+
+    /**
+     * Additional custom constraints
+     */
+    [key: string]: unknown;
+  };
+}

package/src/config/identity.ts

@@ -0,0 +1,252 @@
+/**
+ * Identity Configuration Types
+ *
+ * Configuration for MCP-I identity management including DID generation,
+ * key management, and environment-specific settings.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+import { z } from "zod";
+
+/**
+ * Runtime Identity Configuration
+ *
+ * Configuration for MCP-I identity management at runtime.
+ * Used in application configs (mcpi-runtime-config.ts)
+ *
+ * Controls how agent identity is managed, including key generation,
+ * storage, and DID creation.
+ */
+export interface RuntimeIdentityConfig {
+  /**
+   * Enable identity features
+   * When false, the agent operates anonymously without DID/keys
+   */
+  enabled: boolean;
+
+  /**
+   * Runtime environment for identity
+   * Determines where keys come from and how they're managed
+   */
+  environment: "development" | "production";
+
+  /**
+   * Production identity configuration
+   * Used when environment is 'production'
+   */
+  production?: {
+    /**
+     * Environment variable name containing the private key
+     * @example 'MCPI_PRIVATE_KEY'
+     */
+    privateKeyEnv?: string;
+
+    /**
+     * Environment variable name containing the public key
+     * @example 'MCPI_PUBLIC_KEY'
+     */
+    publicKeyEnv?: string;
+
+    /**
+     * Environment variable name containing the DID
+     * @example 'MCPI_AGENT_DID'
+     */
+    didEnv?: string;
+  };
+
+  /**
+   * Privacy mode - minimizes identity disclosure
+   * When true, identity is only revealed when absolutely necessary
+   * @default false
+   */
+  privacyMode?: boolean;
+
+  /**
+   * Enable debug logging for identity operations
+   * WARNING: May log sensitive information
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Enable automatic user DID generation on chat join
+   * When true, generates ephemeral did:key DIDs for users when they join a session
+   * @default false
+   */
+  generateUserDids?: boolean;
+
+  /**
+   * User DID storage strategy
+   * - 'ephemeral': User DIDs are not persisted (default, did:key)
+   * - 'persistent': User DIDs are persisted in storage (requires did:web setup)
+   * @default 'ephemeral'
+   */
+  userDidStorage?: "ephemeral" | "persistent";
+}
+
+/**
+ * OAuth Provider Configuration
+ *
+ * Configuration for a single OAuth provider (GitHub, Google, etc.)
+ */
+export interface OAuthProvider {
+  /** OAuth client ID (public, safe to expose) */
+  clientId: string;
+
+  /** OAuth client secret (NOT returned in API response for security) */
+  clientSecret?: string | null;
+
+  /** OAuth authorization URL */
+  authorizationUrl: string;
+
+  /** OAuth token exchange URL */
+  tokenUrl: string;
+
+  /** OAuth user info endpoint URL */
+  userInfoUrl?: string;
+
+  /** Whether provider supports PKCE (Proof Key for Code Exchange) */
+  supportsPKCE: boolean;
+
+  /** Whether provider requires client secret (false for PKCE-only providers) */
+  requiresClientSecret: boolean;
+
+  /** Available scopes for this provider */
+  scopes?: string[];
+
+  /** Default scopes to request */
+  defaultScopes?: string[];
+
+  /** Whether provider uses proxy mode (via AgentShield) */
+  proxyMode?: boolean;
+
+  // Phase 3: Custom IDP Support
+  /** Custom OAuth parameters to include in authorization URL (e.g., audience, acr_values) */
+  customParams?: Record<string, string>;
+
+  /** Token endpoint authentication method */
+  tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic";
+
+  /** OAuth response type (default: "code") */
+  responseType?: string;
+
+  /** OAuth grant type (default: "authorization_code") */
+  grantType?: string;
+}
+
+/**
+ * OAuth Configuration
+ *
+ * Configuration for OAuth providers fetched from AgentShield API.
+ * Contains all available providers for a project.
+ *
+ * Note: API does NOT return a defaultProvider field (Phase 1 architecture).
+ * Phase 1 uses configured provider as temporary fallback.
+ * Phase 2+ requires tools to explicitly specify oauthProvider.
+ */
+export interface OAuthConfig {
+  /** Map of provider names to provider configurations */
+  providers: Record<string, OAuthProvider>;
+}
+
+/**
+ * Zod schema for OAuthProvider validation
+ */
+export const OAuthProviderSchema = z.object({
+  clientId: z.string().min(1),
+  clientSecret: z.string().nullable().optional(),
+  authorizationUrl: z.string().url(),
+  tokenUrl: z.string().url(),
+  userInfoUrl: z.string().url().optional(),
+  supportsPKCE: z.boolean(),
+  requiresClientSecret: z.boolean(),
+  scopes: z.array(z.string()).optional(),
+  defaultScopes: z.array(z.string()).optional(),
+  proxyMode: z.boolean().optional(),
+  // Phase 3: Custom IDP Support
+  customParams: z.record(z.string()).optional(),
+  tokenEndpointAuthMethod: z.enum(["client_secret_post", "client_secret_basic"]).optional(),
+  responseType: z.string().optional().default("code"),
+  grantType: z.string().optional().default("authorization_code"),
+});
+
+/**
+ * Zod schema for OAuthConfig validation
+ */
+export const OAuthConfigSchema = z.object({
+  providers: z.record(z.string(), OAuthProviderSchema),
+});
+
+/**
+ * IDP Tokens
+ *
+ * Tokens received from OAuth provider (IDP = Identity Provider)
+ */
+export interface IdpTokens {
+  /** OAuth access token for API calls */
+  access_token: string;
+
+  /** OAuth refresh token (optional) */
+  refresh_token?: string;
+
+  /** Token expiration time in seconds */
+  expires_in?: number;
+
+  /** Token expiration timestamp (milliseconds since epoch) */
+  expires_at: number;
+
+  /** Token type (usually "Bearer") */
+  token_type: string;
+
+  /** Granted scopes */
+  scope?: string;
+}
+
+/**
+ * Agent identity representation
+ * The actual identity data structure used at runtime
+ */
+export interface AgentIdentity {
+  /**
+   * Decentralized Identifier
+   * @example 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
+   */
+  did: string;
+
+  /**
+   * Base64-encoded public key
+   */
+  publicKey: string;
+
+  /**
+   * Base64-encoded private key
+   * NOTE: Should be kept secure and never logged
+   */
+  privateKey: string;
+
+  /**
+   * ISO 8601 timestamp of when the identity was created
+   */
+  createdAt: string;
+
+  /**
+   * Optional metadata about the identity
+   */
+  metadata?: {
+    /**
+     * Human-readable name for this identity
+     */
+    name?: string;
+
+    /**
+     * Version of the identity format
+     */
+    version?: string;
+
+    /**
+     * Additional custom properties
+     */
+    [key: string]: unknown;
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,78 @@
+/**
+ * Configuration Type Exports
+ *
+ * Central export point for all configuration types in the contracts package.
+ * These types form the foundation of XMCP-I's configuration architecture.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+// Import types for the interface
+import type { MCPIBaseConfig } from "./base.js";
+import type { RuntimeIdentityConfig } from "./identity.js";
+import type { ProofingConfig } from "./proofing.js";
+import type { DelegationConfig } from "./delegation.js";
+import type { ToolProtectionSourceConfig } from "./tool-protection.js";
+
+// Base configuration
+export { MCPIBaseConfig } from "./base.js";
+
+// Identity configuration
+export {
+  RuntimeIdentityConfig,
+  AgentIdentity,
+  OAuthProvider,
+  OAuthConfig,
+  IdpTokens,
+} from "./identity.js";
+
+// Tool execution context
+export type { ToolExecutionContext } from "./tool-context.js";
+
+/**
+ * @deprecated Use RuntimeIdentityConfig instead
+ * This export is maintained for backward compatibility
+ */
+export type IdentityConfig = RuntimeIdentityConfig;
+
+// Proofing configuration
+export {
+  ProofingConfig,
+  ProofBatchQueueConfig,
+  ProofDestination,
+  ProofDestinationType,
+} from "./proofing.js";
+
+// Delegation configuration
+export {
+  DelegationConfig,
+  DelegationVerifierConfig,
+  DelegationVerifierType,
+  AuthorizationConfig,
+  DelegationRecord,
+} from "./delegation.js";
+
+// Tool protection configuration
+export {
+  ToolProtection,
+  ToolProtectionMap,
+  ToolProtectionSourceConfig,
+  ToolProtectionSourceType,
+  ToolProtectionServiceConfig,
+  DelegationRequiredErrorData,
+  ToolProtectionResponse,
+} from "./tool-protection.js";
+
+// Configuration builder utilities
+export { buildBaseConfig } from "./builder.js";
+
+/**
+ * Complete runtime configuration type
+ * This can be extended by platform-specific configs
+ */
+export interface MCPIConfig extends MCPIBaseConfig {
+  identity?: RuntimeIdentityConfig;
+  proofing?: ProofingConfig;
+  delegation?: DelegationConfig;
+  toolProtection?: ToolProtectionSourceConfig;
+}