@kya-os/contracts 1.3.5 → 1.5.1

package/dist/config/delegation.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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' | 'kta' | 'memory' | 'cloudflare-kv' | 'redis' | 'dynamodb' | 'custom';
+/**
+ * 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/dist/config/delegation.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Delegation Configuration Types
+ *
+ * Configuration for delegation verification, authorization flows,
+ * and consent management in MCP-I.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/config/identity.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Identity Configuration Types
+ *
+ * Configuration for MCP-I identity management including DID generation,
+ * key management, and environment-specific settings.
+ *
+ * @module @kya-os/contracts/config
+ */
+/**
+ * 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';
+}
+/**
+ * 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;
+    };
+}
+//# sourceMappingURL=identity.d.ts.map

package/dist/config/identity.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Identity Configuration Types
+ *
+ * Configuration for MCP-I identity management including DID generation,
+ * key management, and environment-specific settings.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=identity.js.map

package/dist/config/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 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';
+export { MCPIBaseConfig } from './base.js';
+export { RuntimeIdentityConfig, AgentIdentity } from './identity.js';
+/**
+ * @deprecated Use RuntimeIdentityConfig instead
+ * This export is maintained for backward compatibility
+ */
+export type IdentityConfig = RuntimeIdentityConfig;
+export { ProofingConfig, ProofBatchQueueConfig, ProofDestination, ProofDestinationType } from './proofing.js';
+export { DelegationConfig, DelegationVerifierConfig, DelegationVerifierType, AuthorizationConfig, DelegationRecord } from './delegation.js';
+export { ToolProtection, ToolProtectionMap, ToolProtectionSourceConfig, ToolProtectionSourceType, ToolProtectionServiceConfig, DelegationRequiredErrorData, ToolProtectionResponse } 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;
+}

package/dist/config/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/config/proofing.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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/dist/config/proofing.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Proofing Configuration Types
+ *
+ * Configuration for proof generation and submission including batch
+ * processing, destinations, and retry logic.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/config/tool-protection.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Tool Protection Configuration Types
+ *
+ * Configuration for tool protection including delegation requirements,
+ * scopes, and multi-source resolution strategies.
+ *
+ * @module @kya-os/contracts/config
+ */
+import type { ToolProtection as BaseToolProtection, ToolProtectionMap as BaseToolProtectionMap, DelegationRequiredErrorData as BaseDelegationRequiredErrorData, ToolProtectionResponse as BaseToolProtectionResponse } from '../tool-protection/index.js';
+export type ToolProtection = BaseToolProtection;
+export type ToolProtectionMap = BaseToolProtectionMap;
+export type DelegationRequiredErrorData = BaseDelegationRequiredErrorData;
+export type ToolProtectionResponse = BaseToolProtectionResponse;
+/**
+ * Tool protection source types
+ */
+export type ToolProtectionSourceType = 'inline' | 'local' | 'agentshield' | 'kta' | 'multi';
+/**
+ * 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/dist/config/tool-protection.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Tool Protection Configuration Types
+ *
+ * Configuration for tool protection including delegation requirements,
+ * scopes, and multi-source resolution strategies.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });