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

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

package/src/config/proofing.ts

@@ -0,0 +1,138 @@
+/**
+ * Proofing Configuration Types
+ *
+ * Configuration for proof generation and submission including batch
+ * processing, destinations, and retry logic.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+/**
+ * Proof destination types
+ */
+export type ProofDestinationType = 'agentshield' | 'kta' | 'custom';
+
+/**
+ * Proof destination configuration
+ * Defines where proofs should be submitted
+ */
+export interface ProofDestination {
+  /**
+   * Type of destination
+   */
+  type: ProofDestinationType;
+
+  /**
+   * API base URL for the destination
+   * Required for 'agentshield' and 'kta' types
+   * @example 'https://kya.vouched.id'
+   */
+  apiUrl?: string;
+
+  /**
+   * API key for authentication
+   * Required for most destinations
+   */
+  apiKey?: string;
+
+  /**
+   * Custom submission function
+   * Required for 'custom' type destinations
+   */
+  submit?: (proofs: any[]) => Promise<void>;
+
+  /**
+   * Additional destination-specific configuration
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Proof batch queue configuration
+ * Controls how proofs are batched and submitted
+ */
+export interface ProofBatchQueueConfig {
+  /**
+   * Destinations where proofs should be sent
+   * Multiple destinations are processed in parallel
+   */
+  destinations: ProofDestination[];
+
+  /**
+   * Maximum number of proofs to batch before auto-submission
+   * @default 10
+   */
+  maxBatchSize?: number;
+
+  /**
+   * Time interval (ms) between automatic flush attempts
+   * @default 5000
+   */
+  flushIntervalMs?: number;
+
+  /**
+   * Maximum number of retry attempts for failed submissions
+   * @default 3
+   */
+  maxRetries?: number;
+
+  /**
+   * Backoff multiplier for retry delays
+   * @default 2
+   */
+  retryBackoff?: number;
+
+  /**
+   * Enable debug logging for proof submission
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Proofing configuration (platform-agnostic)
+ *
+ * Controls proof generation, batching, and submission to external services
+ * like AgentShield or Know That AI (KTA).
+ */
+export interface ProofingConfig {
+  /**
+   * Enable proof generation and submission
+   * @default true
+   */
+  enabled: boolean;
+
+  /**
+   * Proof batch queue configuration
+   * Controls batching and submission behavior
+   */
+  batchQueue?: ProofBatchQueueConfig;
+
+  /**
+   * Include additional metadata in proofs
+   * @default true
+   */
+  includeMetadata?: boolean;
+
+  /**
+   * Custom proof generation options
+   */
+  options?: {
+    /**
+     * Include timestamp in all proofs
+     * @default true
+     */
+    includeTimestamp?: boolean;
+
+    /**
+     * Include session context in proofs
+     * @default true
+     */
+    includeSession?: boolean;
+
+    /**
+     * Custom fields to include in every proof
+     */
+    customFields?: Record<string, unknown>;
+  };
+}

package/src/config/tool-context.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool Execution Context
+ *
+ * Execution context passed to tool handlers, enabling tools to access
+ * IDP tokens for external API calls (GitHub, Google, etc.).
+ *
+ * All fields are optional for backward compatibility - tools that don't
+ * require OAuth will receive undefined context.
+ *
+ * @package @kya-os/contracts
+ */
+
+/**
+ * Execution context passed to tool handlers
+ *
+ * Enables tools to access IDP tokens for external API calls.
+ * Context is only provided when:
+ * - Tool requires OAuth (has requiredScopes)
+ * - User DID is available
+ * - IDP token is successfully resolved
+ */
+export interface ToolExecutionContext {
+  /** IDP access token for external API calls (e.g., GitHub, Google) */
+  idpToken?: string;
+
+  /** OAuth provider name (e.g., "github", "google") */
+  provider?: string;
+
+  /** Scopes granted for this token */
+  scopes?: string[];
+
+  /** User DID associated with this token */
+  userDid?: string;
+
+  /** Session ID */
+  sessionId?: string;
+
+  /** Delegation token (MCP-I internal authorization) */
+  delegationToken?: string;
+}
+

package/src/config/tool-protection.ts

@@ -0,0 +1,174 @@
+/**
+ * Tool Protection Configuration Types
+ *
+ * Configuration for tool protection including delegation requirements,
+ * scopes, and multi-source resolution strategies.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+// Import core tool protection types from the spec
+import type {
+  ToolProtection as BaseToolProtection,
+  ToolProtectionMap as BaseToolProtectionMap,
+  DelegationRequiredErrorData as BaseDelegationRequiredErrorData,
+  ToolProtectionResponse as BaseToolProtectionResponse
+} from '../tool-protection/index.js';
+
+// Re-export for convenience
+export type ToolProtection = BaseToolProtection;
+export type ToolProtectionMap = BaseToolProtectionMap;
+export type DelegationRequiredErrorData = BaseDelegationRequiredErrorData;
+export type ToolProtectionResponse = BaseToolProtectionResponse;
+
+/**
+ * Tool protection source types
+ */
+export type ToolProtectionSourceType =
+  | 'inline'       // Inline configuration in code
+  | 'local'        // Local file (tool-protections.json)
+  | 'agentshield'  // AgentShield API
+  | 'kta'          // Know That AI
+  | 'multi';       // Multiple sources with priority resolution
+
+/**
+ * Tool protection source configuration
+ * Defines where tool protection settings come from
+ */
+export interface ToolProtectionSourceConfig {
+  /**
+   * Type of source to use
+   */
+  source: ToolProtectionSourceType;
+
+  /**
+   * Inline tool protection map
+   * Used when source is 'inline'
+   */
+  inline?: BaseToolProtectionMap;
+
+  /**
+   * Path to local tool protections file
+   * Used when source is 'local'
+   * @example './tool-protections.json'
+   */
+  localFile?: string;
+
+  /**
+   * AgentShield configuration
+   * Used when source is 'agentshield'
+   */
+  agentShield?: {
+    /**
+     * AgentShield API base URL
+     * @example 'https://kya.vouched.id'
+     */
+    apiUrl: string;
+
+    /**
+     * API key for authentication
+     */
+    apiKey?: string;
+
+    /**
+     * Project ID (optional, for backward compatibility)
+     * Modern approach uses agent DID
+     */
+    projectId?: string;
+
+    /**
+     * Cache TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    cacheTtl?: number;
+  };
+
+  /**
+   * KTA configuration
+   * Used when source is 'kta'
+   */
+  kta?: {
+    /**
+     * KTA API base URL
+     */
+    apiUrl: string;
+
+    /**
+     * API key for authentication
+     */
+    apiKey?: string;
+  };
+
+  /**
+   * Multi-source configuration
+   * Used when source is 'multi'
+   * Sources are checked in priority order
+   */
+  sources?: Array<{
+    /**
+     * Source configuration
+     */
+    config: Omit<ToolProtectionSourceConfig, 'source' | 'sources'>;
+
+    /**
+     * Priority (higher number = higher priority)
+     * @default 0
+     */
+    priority?: number;
+
+    /**
+     * Whether to stop after this source if found
+     * @default false
+     */
+    exclusive?: boolean;
+  }>;
+
+  /**
+   * Fallback configuration if all sources fail
+   */
+  fallback?: BaseToolProtectionMap;
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Tool protection service configuration
+ * Used by provider-based implementations
+ */
+export interface ToolProtectionServiceConfig {
+  /**
+   * API base URL for fetching tool protections
+   */
+  apiUrl: string;
+
+  /**
+   * API key for authentication
+   */
+  apiKey: string;
+
+  /**
+   * Project ID (optional)
+   */
+  projectId?: string;
+
+  /**
+   * Cache TTL in milliseconds
+   * @default 300000 (5 minutes)
+   */
+  cacheTtl?: number;
+
+  /**
+   * Fallback configuration if API is unavailable
+   */
+  fallbackConfig?: BaseToolProtectionMap;
+
+  /**
+   * Enable debug logging
+   * @default false
+   */
+  debug?: boolean;
+}

package/src/consent/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Consent Module Exports
+ *
+ * Types and schemas for consent page configuration and approval handling
+ */
+
+// Export schemas and inferred types (types are derived from schemas)
+export {
+  consentBrandingSchema,
+  consentTermsSchema,
+  consentCustomFieldSchema,
+  consentCustomFieldOptionSchema,
+  consentPageConfigSchema,
+  consentApprovalRequestSchema,
+  consentApprovalResponseSchema,
+  consentConfigSchema,
+  oauthIdentitySchema,
+  validateConsentPageConfig,
+  validateConsentApprovalRequest,
+  validateConsentApprovalResponse,
+  validateConsentConfig,
+  type ConsentBranding,
+  type ConsentTerms,
+  type ConsentCustomField,
+  type ConsentPageConfig,
+  type ConsentApprovalRequest,
+  type ConsentApprovalResponse,
+  type ConsentConfig,
+  type OAuthIdentity,
+} from './schemas.js';
+
+