@kya-os/contracts 1.5.2-canary.4 → 1.5.2-canary.6

package/dist/consent/schemas.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Consent Schemas
+ *
+ * Zod schemas for runtime validation of consent-related data structures.
+ * All types are derived from these schemas using z.infer.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consentConfigSchema = exports.consentApprovalResponseSchema = exports.consentApprovalRequestSchema = exports.consentPageConfigSchema = exports.oauthIdentitySchema = exports.consentCustomFieldSchema = exports.consentCustomFieldOptionSchema = exports.consentTermsSchema = exports.consentBrandingSchema = void 0;
+exports.validateConsentPageConfig = validateConsentPageConfig;
+exports.validateConsentApprovalRequest = validateConsentApprovalRequest;
+exports.validateConsentApprovalResponse = validateConsentApprovalResponse;
+exports.validateConsentConfig = validateConsentConfig;
+const zod_1 = require("zod");
+/**
+ * Consent Branding Schema
+ */
+exports.consentBrandingSchema = zod_1.z.object({
+    primaryColor: zod_1.z
+        .string()
+        .regex(/^#[0-9A-Fa-f]{6}$/, 'Must be a valid hex color (e.g., #0066CC)')
+        .optional(),
+    logoUrl: zod_1.z.string().url('Must be a valid URL').optional(),
+    companyName: zod_1.z.string().max(100, 'Company name must be 100 characters or less').optional(),
+    theme: zod_1.z.enum(['light', 'dark', 'auto']).optional(),
+});
+/**
+ * Consent Terms Schema
+ */
+exports.consentTermsSchema = zod_1.z.object({
+    text: zod_1.z.string().max(10000, 'Terms text must be 10000 characters or less').optional(),
+    url: zod_1.z.string().url('Must be a valid URL').optional(),
+    version: zod_1.z.string().max(50, 'Version must be 50 characters or less').optional(),
+    required: zod_1.z.boolean().default(true),
+});
+/**
+ * Consent Custom Field Option Schema
+ */
+exports.consentCustomFieldOptionSchema = zod_1.z.object({
+    value: zod_1.z.string().max(100, 'Option value must be 100 characters or less'),
+    label: zod_1.z.string().max(100, 'Option label must be 100 characters or less'),
+});
+/**
+ * Consent Custom Field Schema
+ */
+exports.consentCustomFieldSchema = zod_1.z.object({
+    name: zod_1.z
+        .string()
+        .min(1, 'Field name is required')
+        .max(50, 'Field name must be 50 characters or less')
+        .regex(/^[a-zA-Z0-9_]+$/, 'Field name must contain only letters, numbers, and underscores'),
+    label: zod_1.z.string().min(1, 'Field label is required').max(100, 'Field label must be 100 characters or less'),
+    type: zod_1.z.enum(['text', 'textarea', 'checkbox', 'select']),
+    required: zod_1.z.boolean(),
+    placeholder: zod_1.z.string().max(200, 'Placeholder must be 200 characters or less').optional(),
+    options: zod_1.z
+        .array(exports.consentCustomFieldOptionSchema)
+        .min(1, 'Select fields must have at least one option')
+        .optional(),
+    pattern: zod_1.z.string().max(500, 'Pattern must be 500 characters or less').optional(),
+}).refine((data) => {
+    // Select fields must have options
+    if (data.type === 'select' && (!data.options || data.options.length === 0)) {
+        return false;
+    }
+    // Non-select fields should not have options
+    if (data.type !== 'select' && data.options) {
+        return false;
+    }
+    return true;
+}, {
+    message: 'Select fields must have options, and non-select fields must not have options',
+});
+/**
+ * OAuth Identity Schema
+ *
+ * Represents a user's OAuth provider account information.
+ * Used in Phase 4 to link OAuth accounts to persistent User DIDs.
+ */
+exports.oauthIdentitySchema = zod_1.z.object({
+    /**
+     * OAuth provider name (e.g., "google", "github", "microsoft")
+     */
+    provider: zod_1.z.string()
+        .min(1, 'Provider is required')
+        .max(50, 'Provider name must be 50 characters or less'),
+    /**
+     * OAuth subject identifier (unique user ID from provider)
+     * @example "123456789" (Google), "github-user-id" (GitHub)
+     */
+    subject: zod_1.z.string()
+        .min(1, 'Subject is required')
+        .max(255, 'Subject must be 255 characters or less'),
+    /**
+     * User's email address from OAuth provider (optional)
+     */
+    email: zod_1.z.string()
+        .email('Must be a valid email address')
+        .max(255, 'Email must be 255 characters or less')
+        .optional(),
+    /**
+     * User's display name from OAuth provider (optional)
+     */
+    name: zod_1.z.string()
+        .max(255, 'Name must be 255 characters or less')
+        .optional(),
+});
+/**
+ * Consent Page Config Schema
+ */
+exports.consentPageConfigSchema = zod_1.z.object({
+    tool: zod_1.z.string().min(1, 'Tool name is required'),
+    toolDescription: zod_1.z.string().max(500, 'Tool description must be 500 characters or less'),
+    scopes: zod_1.z.array(zod_1.z.string()).min(0, 'Scopes array cannot be negative'),
+    agentDid: zod_1.z.string().min(1, 'Agent DID is required'),
+    sessionId: zod_1.z.string().min(1, 'Session ID is required'),
+    projectId: zod_1.z.string().min(1, 'Project ID is required'),
+    branding: exports.consentBrandingSchema.optional(),
+    terms: exports.consentTermsSchema.optional(),
+    customFields: zod_1.z
+        .array(exports.consentCustomFieldSchema)
+        .max(10, 'Maximum 10 custom fields allowed')
+        .optional(),
+    serverUrl: zod_1.z.string().url('Server URL must be a valid URL'),
+    autoClose: zod_1.z.boolean().optional(),
+});
+/**
+ * Consent Approval Request Schema
+ *
+ * Note: Uses snake_case for API compatibility (agent_did, session_id, project_id)
+ *
+ * Phase 4 additions:
+ * - oauth_identity: Optional OAuth provider information for identity linking
+ * - user_did: Optional User DID for persistent identity (if already known)
+ */
+exports.consentApprovalRequestSchema = zod_1.z.object({
+    tool: zod_1.z.string().min(1, 'Tool name is required'),
+    scopes: zod_1.z.array(zod_1.z.string()).min(0, 'Scopes array cannot be negative'),
+    agent_did: zod_1.z.string().min(1, 'Agent DID is required'),
+    session_id: zod_1.z.string().min(1, 'Session ID is required'),
+    project_id: zod_1.z.string().min(1, 'Project ID is required'),
+    termsAccepted: zod_1.z.boolean(),
+    termsVersion: zod_1.z.string()
+        .max(50, 'Terms version must be 50 characters or less')
+        .optional(),
+    customFields: zod_1.z
+        .record(zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()]))
+        .optional(),
+    // Phase 4: OAuth identity linking
+    /**
+     * OAuth provider identity information (optional)
+     * Used to link OAuth accounts to persistent User DIDs
+     */
+    oauth_identity: exports.oauthIdentitySchema.optional(),
+    /**
+     * User DID (optional)
+     * If provided, represents the persistent User DID for this user
+     * Format: did:key:... or did:web:...
+     */
+    user_did: zod_1.z.string()
+        .regex(/^did:/, 'Must be a valid DID format (starting with did:)')
+        .max(500, 'DID must be 500 characters or less')
+        .optional(),
+});
+/**
+ * Consent Approval Response Schema
+ */
+exports.consentApprovalResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    delegation_id: zod_1.z.string().min(1).optional(),
+    delegation_token: zod_1.z.string().min(1).optional(),
+    error: zod_1.z.string().optional(),
+    error_code: zod_1.z.string().optional(),
+}).refine((data) => {
+    // If success is true, must have delegation_id and delegation_token
+    if (data.success) {
+        return !!data.delegation_id && !!data.delegation_token;
+    }
+    // If success is false, must have error or error_code
+    return !!data.error || !!data.error_code;
+}, {
+    message: 'Successful responses must include delegation_id and delegation_token. Failed responses must include error or error_code',
+});
+/**
+ * Consent Config Schema
+ */
+exports.consentConfigSchema = zod_1.z.object({
+    branding: exports.consentBrandingSchema.optional(),
+    terms: exports.consentTermsSchema.optional(),
+    customFields: zod_1.z
+        .array(exports.consentCustomFieldSchema)
+        .max(10, 'Maximum 10 custom fields allowed')
+        .optional(),
+    ui: zod_1.z.object({
+        theme: zod_1.z.enum(['light', 'dark', 'auto']).optional(),
+        popupEnabled: zod_1.z.boolean().optional(),
+        autoClose: zod_1.z.boolean().optional(),
+        autoCloseDelay: zod_1.z.number().int().positive().max(60000, 'Auto-close delay must be 60000ms or less').optional(),
+    }).optional(),
+});
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a consent page config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+function validateConsentPageConfig(config) {
+    return exports.consentPageConfigSchema.safeParse(config);
+}
+/**
+ * Validate a consent approval request
+ *
+ * @param request - The request to validate
+ * @returns Validation result
+ */
+function validateConsentApprovalRequest(request) {
+    return exports.consentApprovalRequestSchema.safeParse(request);
+}
+/**
+ * Validate a consent approval response
+ *
+ * @param response - The response to validate
+ * @returns Validation result
+ */
+function validateConsentApprovalResponse(response) {
+    return exports.consentApprovalResponseSchema.safeParse(response);
+}
+/**
+ * Validate a consent config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+function validateConsentConfig(config) {
+    return exports.consentConfigSchema.safeParse(config);
+}

package/dist/consent/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Consent Types
+ *
+ * TypeScript type definitions for consent page configuration and approval handling.
+ * These types are used for server-hosted consent pages in HTTP/SSE transports.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+/**
+ * Consent Branding Configuration
+ *
+ * Customization options for consent page appearance
+ */
+export interface ConsentBranding {
+    /** Primary brand color (hex format, e.g., '#0066CC') */
+    primaryColor?: string;
+    /** Logo URL for display on consent page */
+    logoUrl?: string;
+    /** Company/application name */
+    companyName?: string;
+    /** Theme preference ('light', 'dark', or 'auto' for system preference) */
+    theme?: 'light' | 'dark' | 'auto';
+}
+/**
+ * Consent Terms Configuration
+ *
+ * Terms of service or privacy policy information
+ */
+export interface ConsentTerms {
+    /** Full terms text (displayed on page) */
+    text?: string;
+    /** URL to terms document */
+    url?: string;
+    /** Version identifier for terms */
+    version?: string;
+    /** Whether terms acceptance is required */
+    required?: boolean;
+}
+/**
+ * Consent Custom Field
+ *
+ * Additional fields to collect during consent (e.g., email, preferences)
+ */
+export interface ConsentCustomField {
+    /** Field name (used as form field name, must be valid identifier) */
+    name: string;
+    /** Display label for the field */
+    label: string;
+    /** Field type */
+    type: 'text' | 'textarea' | 'checkbox' | 'select';
+    /** Whether field is required */
+    required: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Options for select fields */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Validation pattern (regex) */
+    pattern?: string;
+}
+/**
+ * Consent Page Configuration
+ *
+ * Complete configuration for rendering a consent page
+ */
+export interface ConsentPageConfig {
+    /** Tool name requiring authorization */
+    tool: string;
+    /** Description of what the tool does */
+    toolDescription: string;
+    /** Scopes being requested */
+    scopes: string[];
+    /** Agent DID requesting authorization */
+    agentDid: string;
+    /** Session ID for tracking */
+    sessionId: string;
+    /** Project ID from AgentShield */
+    projectId: string;
+    /** Branding configuration */
+    branding?: ConsentBranding;
+    /** Terms configuration */
+    terms?: ConsentTerms;
+    /** Custom fields to collect */
+    customFields?: ConsentCustomField[];
+    /** Server URL for form submission */
+    serverUrl: string;
+    /** Whether to auto-close window after success */
+    autoClose?: boolean;
+}
+/**
+ * Consent Approval Request
+ *
+ * Request payload when user approves consent
+ */
+export interface ConsentApprovalRequest {
+    /** Tool name */
+    tool: string;
+    /** Approved scopes */
+    scopes: string[];
+    /** Agent DID (snake_case for API compatibility) */
+    agent_did: string;
+    /** Session ID (snake_case for API compatibility) */
+    session_id: string;
+    /** Project ID (snake_case for API compatibility) */
+    project_id: string;
+    /** Whether terms were accepted */
+    termsAccepted: boolean;
+    /** Terms version (if applicable) */
+    termsVersion?: string;
+    /** Custom field values */
+    customFields?: Record<string, string | boolean>;
+}
+/**
+ * Consent Approval Response
+ *
+ * Response after processing consent approval
+ */
+export interface ConsentApprovalResponse {
+    /** Whether approval was successful */
+    success: boolean;
+    /** Delegation ID (if successful) */
+    delegation_id?: string;
+    /** Delegation token (if successful) */
+    delegation_token?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** Error code (if failed) */
+    error_code?: string;
+}
+/**
+ * Consent Configuration
+ *
+ * Complete consent configuration fetched from AgentShield or defaults
+ */
+export interface ConsentConfig {
+    /** Branding configuration */
+    branding?: ConsentBranding;
+    /** Terms configuration */
+    terms?: ConsentTerms;
+    /** Custom fields configuration */
+    customFields?: ConsentCustomField[];
+    /** UI preferences */
+    ui?: {
+        /** Theme preference */
+        theme?: 'light' | 'dark' | 'auto';
+        /** Whether popup mode is enabled */
+        popupEnabled?: boolean;
+        /** Whether to auto-close after success */
+        autoClose?: boolean;
+        /** Delay before auto-close (milliseconds) */
+        autoCloseDelay?: number;
+    };
+}

package/dist/consent/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Consent Types
+ *
+ * TypeScript type definitions for consent page configuration and approval handling.
+ * These types are used for server-hosted consent pages in HTTP/SSE transports.
+ *
+ * Related Spec: MCP-I Phase 0 Implementation Plan
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dashboard-config/default-config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Default Configuration for MCP-I Servers
+ *
+ * Provides safe, production-ready defaults for new user configurations.
+ * Used by AgentShield Dashboard, Scaffolder, and Runtime fallbacks.
+ *
+ * @package @kya-os/contracts/dashboard-config
+ */
+import type { MCPIServerConfig } from "./types.js";
+/**
+ * Default configuration object
+ *
+ * This is the base default configuration used when creating new user configs.
+ * Platform-specific defaults are available via getDefaultConfigForPlatform().
+ */
+export declare const defaultConfig: MCPIServerConfig;
+/**
+ * Get default configuration for a specific platform
+ *
+ * Returns the base default config merged with platform-specific defaults.
+ *
+ * @param platform - Platform type ('node', 'cloudflare', or 'vercel')
+ * @returns Platform-specific default configuration
+ *
+ * @example
+ * ```typescript
+ * const nodeConfig = getDefaultConfigForPlatform('node');
+ * const cloudflareConfig = getDefaultConfigForPlatform('cloudflare');
+ * ```
+ */
+export declare function getDefaultConfigForPlatform(platform: "node" | "cloudflare" | "vercel"): MCPIServerConfig;
+/**
+ * Merge partial configuration with defaults
+ *
+ * Deep merges a partial configuration object with the base defaults,
+ * ensuring all required fields are present.
+ *
+ * @param partial - Partial configuration to merge with defaults
+ * @returns Complete configuration with defaults applied
+ *
+ * @example
+ * ```typescript
+ * const config = mergeWithDefaults({
+ *   proofing: { enabled: false },
+ *   identity: { environment: 'production' }
+ * });
+ * ```
+ */
+export declare function mergeWithDefaults(partial: Partial<MCPIServerConfig>): MCPIServerConfig;

package/dist/dashboard-config/default-config.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Default Configuration for MCP-I Servers
+ *
+ * Provides safe, production-ready defaults for new user configurations.
+ * Used by AgentShield Dashboard, Scaffolder, and Runtime fallbacks.
+ *
+ * @package @kya-os/contracts/dashboard-config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+exports.getDefaultConfigForPlatform = getDefaultConfigForPlatform;
+exports.mergeWithDefaults = mergeWithDefaults;
+const schemas_js_1 = require("./schemas.js");
+const zod_1 = require("zod");
+/**
+ * Default configuration JSON content
+ * Embedded here to avoid TypeScript JSON import issues in build
+ */
+const defaultConfigJson = {
+    identity: {
+        // agentDid removed - deprecated, use serverDid instead
+        serverDid: "", // New field - will be populated when identity is generated
+        environment: "development",
+        storageLocation: "env-vars",
+    },
+    proofing: {
+        enabled: true,
+        destinations: [
+            {
+                type: "agentshield",
+                apiUrl: "https://kya.vouched.id",
+            },
+        ],
+        batchQueue: {
+            maxBatchSize: 10,
+            flushIntervalMs: 5000,
+            maxRetries: 3,
+        },
+    },
+    delegation: {
+        enabled: true,
+        enforceStrictly: false,
+        verifier: {
+            type: "agentshield",
+            apiUrl: "https://kya.vouched.id/api/v1/bouncer/delegations/verify",
+            cacheTtl: 300000,
+        },
+        authorization: {
+            authorizationUrl: "https://kya.vouched.id/api/v1/bouncer/delegations/authorize",
+            minReputationScore: 80,
+            resumeTokenTtl: 3600000,
+            requireAuthForUnknown: false,
+        },
+    },
+    toolProtection: {
+        source: "agentshield",
+        agentShield: {
+            apiUrl: "https://kya.vouched.id",
+            cacheTtl: 300000,
+        },
+        fallback: {},
+    },
+    audit: {
+        enabled: true,
+        includeProofHashes: false,
+        includePayloads: false,
+    },
+    session: {
+        timestampSkewSeconds: 120,
+        ttlMinutes: 30,
+    },
+    platform: {
+        type: "node",
+        node: {
+            server: {
+                port: 3000,
+                host: "0.0.0.0",
+                cors: true,
+                timeout: 30000,
+            },
+            storage: {
+                type: "memory",
+            },
+        },
+        cloudflare: {
+            workers: {
+                cpuMs: 50,
+                memoryMb: 128,
+            },
+            kvNamespaces: [],
+            environmentVariables: [],
+        },
+        vercel: {
+            environmentVariables: [],
+            edgeRuntime: {},
+        },
+    },
+    metadata: {
+        version: "1.0.0",
+        lastUpdated: "",
+        source: "dashboard",
+        deploymentStatus: "inactive",
+    },
+};
+/**
+ * Relaxed schema for default config validation
+ * Allows empty strings for fields that will be populated later
+ *
+ * Note: Empty `agentDid` is valid for new/incomplete configurations.
+ * This allows users to create configs before registering their agent DID.
+ * The base schema (mcpIServerConfigSchema) requires non-empty agentDid for
+ * complete configurations, but defaults allow empty to support progressive
+ * configuration.
+ */
+const defaultConfigSchema = schemas_js_1.mcpIServerConfigSchema.extend({
+    identity: schemas_js_1.mcpIServerConfigSchema.shape.identity.extend({
+        agentDid: zod_1.z.string().optional(), // Allow empty string or undefined for defaults (deprecated)
+        serverDid: zod_1.z.string(), // Allow empty string for defaults (will be populated later)
+    }),
+    metadata: schemas_js_1.mcpIServerConfigSchema.shape.metadata.extend({
+        lastUpdated: zod_1.z.string(), // Allow empty string (will be set dynamically)
+    }),
+});
+/**
+ * Default configuration object
+ *
+ * This is the base default configuration used when creating new user configs.
+ * Platform-specific defaults are available via getDefaultConfigForPlatform().
+ */
+exports.defaultConfig = defaultConfigSchema.parse(defaultConfigJson);
+/**
+ * Platform-specific default configurations
+ */
+const platformDefaults = {
+    node: {
+        platform: {
+            type: "node",
+            node: {
+                server: {
+                    port: 3000,
+                    host: "0.0.0.0",
+                    cors: true,
+                    timeout: 30000,
+                },
+                storage: {
+                    type: "memory",
+                },
+            },
+        },
+    },
+    cloudflare: {
+        platform: {
+            type: "cloudflare",
+            cloudflare: {
+                workers: {
+                    cpuMs: 50,
+                    memoryMb: 128,
+                },
+                kvNamespaces: [],
+                environmentVariables: [],
+            },
+        },
+    },
+    vercel: {
+        platform: {
+            type: "vercel",
+            vercel: {
+                environmentVariables: [],
+                edgeRuntime: {},
+            },
+        },
+    },
+};
+/**
+ * Get default configuration for a specific platform
+ *
+ * Returns the base default config merged with platform-specific defaults.
+ *
+ * @param platform - Platform type ('node', 'cloudflare', or 'vercel')
+ * @returns Platform-specific default configuration
+ *
+ * @example
+ * ```typescript
+ * const nodeConfig = getDefaultConfigForPlatform('node');
+ * const cloudflareConfig = getDefaultConfigForPlatform('cloudflare');
+ * ```
+ */
+function getDefaultConfigForPlatform(platform) {
+    const platformDefault = platformDefaults[platform];
+    return {
+        ...exports.defaultConfig,
+        platform: platformDefault.platform,
+    };
+}
+/**
+ * Deep merge utility for objects
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        const sourceValue = source[key];
+        if (sourceValue &&
+            typeof sourceValue === "object" &&
+            !Array.isArray(sourceValue) &&
+            sourceValue !== null) {
+            const targetValue = target[key];
+            if (targetValue &&
+                typeof targetValue === "object" &&
+                !Array.isArray(targetValue) &&
+                targetValue !== null) {
+                result[key] = deepMerge(targetValue, sourceValue);
+            }
+        }
+        else if (sourceValue !== undefined) {
+            result[key] = sourceValue;
+        }
+    }
+    return result;
+}
+/**
+ * Merge partial configuration with defaults
+ *
+ * Deep merges a partial configuration object with the base defaults,
+ * ensuring all required fields are present.
+ *
+ * @param partial - Partial configuration to merge with defaults
+ * @returns Complete configuration with defaults applied
+ *
+ * @example
+ * ```typescript
+ * const config = mergeWithDefaults({
+ *   proofing: { enabled: false },
+ *   identity: { environment: 'production' }
+ * });
+ * ```
+ */
+function mergeWithDefaults(partial) {
+    return deepMerge(exports.defaultConfig, partial);
+}