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

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

package/src/consent/schemas.ts

@@ -0,0 +1,334 @@
+/**
+ * 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
+ */
+
+import { z } from "zod";
+
+/**
+ * Consent Branding Schema
+ */
+export const consentBrandingSchema = z.object({
+  primaryColor: z
+    .string()
+    .regex(/^#[0-9A-Fa-f]{6}$/, "Must be a valid hex color (e.g., #0066CC)")
+    .optional(),
+  logoUrl: z.string().url("Must be a valid URL").optional(),
+  companyName: z
+    .string()
+    .max(100, "Company name must be 100 characters or less")
+    .optional(),
+  theme: z.enum(["light", "dark", "auto"]).optional(),
+});
+
+export type ConsentBranding = z.infer<typeof consentBrandingSchema>;
+
+/**
+ * Consent Terms Schema
+ */
+export const consentTermsSchema = z.object({
+  text: z
+    .string()
+    .max(10000, "Terms text must be 10000 characters or less")
+    .optional(),
+  url: z.string().url("Must be a valid URL").optional(),
+  version: z
+    .string()
+    .max(50, "Version must be 50 characters or less")
+    .optional(),
+  required: z.boolean().default(true),
+});
+
+export type ConsentTerms = z.infer<typeof consentTermsSchema>;
+
+/**
+ * Consent Custom Field Option Schema
+ */
+export const consentCustomFieldOptionSchema = z.object({
+  value: z.string().max(100, "Option value must be 100 characters or less"),
+  label: z.string().max(100, "Option label must be 100 characters or less"),
+});
+
+/**
+ * Consent Custom Field Schema
+ */
+export const consentCustomFieldSchema = z
+  .object({
+    name: 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: z
+      .string()
+      .min(1, "Field label is required")
+      .max(100, "Field label must be 100 characters or less"),
+    type: z.enum(["text", "textarea", "checkbox", "select"]),
+    required: z.boolean(),
+    placeholder: z
+      .string()
+      .max(200, "Placeholder must be 200 characters or less")
+      .optional(),
+    options: z
+      .array(consentCustomFieldOptionSchema)
+      .min(1, "Select fields must have at least one option")
+      .optional(),
+    pattern: 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",
+    }
+  );
+
+export type ConsentCustomField = z.infer<typeof consentCustomFieldSchema>;
+
+/**
+ * OAuth Identity Schema
+ *
+ * Represents a user's OAuth provider account information.
+ * Used in Phase 4 to link OAuth accounts to persistent User DIDs.
+ */
+export const oauthIdentitySchema = z.object({
+  /**
+   * OAuth provider name (e.g., "google", "github", "microsoft")
+   */
+  provider: 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: 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: 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: z.string().max(255, "Name must be 255 characters or less").optional(),
+});
+
+export type OAuthIdentity = z.infer<typeof oauthIdentitySchema>;
+
+/**
+ * Consent Page Config Schema
+ */
+export const consentPageConfigSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  toolDescription: z
+    .string()
+    .max(500, "Tool description must be 500 characters or less"),
+  scopes: z.array(z.string()).min(0, "Scopes array cannot be negative"),
+  agentDid: z.string().min(1, "Agent DID is required"),
+  sessionId: z.string().min(1, "Session ID is required"),
+  projectId: z.string().min(1, "Project ID is required"),
+  provider: z.string().optional(), // Phase 2: OAuth provider name (e.g., "github", "google")
+  branding: consentBrandingSchema.optional(),
+  terms: consentTermsSchema.optional(),
+  customFields: z
+    .array(consentCustomFieldSchema)
+    .max(10, "Maximum 10 custom fields allowed")
+    .optional(),
+  serverUrl: z.string().url("Server URL must be a valid URL"),
+  autoClose: z.boolean().optional(),
+  /**
+   * Whether OAuth authorization is required immediately
+   * If true, the consent page will act as a landing page before redirecting
+   */
+  oauthRequired: z.boolean().optional(),
+  /**
+   * The OAuth authorization URL to redirect to
+   * Required if oauthRequired is true
+   */
+  oauthUrl: z.string().url().optional(),
+});
+
+export type ConsentPageConfig = z.infer<typeof consentPageConfigSchema>;
+
+/**
+ * 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)
+ */
+export const consentApprovalRequestSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  scopes: z.array(z.string()).min(0, "Scopes array cannot be negative"),
+  agent_did: z.string().min(1, "Agent DID is required"),
+  session_id: z.string().min(1, "Session ID is required"),
+  project_id: z.string().min(1, "Project ID is required"),
+  termsAccepted: z.boolean(),
+  termsVersion: z
+    .string()
+    .max(50, "Terms version must be 50 characters or less")
+    .optional(),
+  customFields: z.record(z.union([z.string(), z.boolean()])).optional(),
+
+  // Phase 4: OAuth identity linking
+  /**
+   * OAuth provider identity information (optional)
+   * Used to link OAuth accounts to persistent User DIDs
+   *
+   * CRITICAL: Uses .nullish() to accept null, undefined, or OAuthIdentity
+   * This matches JSON parsing behavior where missing fields become null
+   */
+  oauth_identity: oauthIdentitySchema.nullish(),
+
+  /**
+   * User DID (optional)
+   * If provided, represents the persistent User DID for this user
+   * Format: did:key:... or did:web:...
+   */
+  user_did: z
+    .string()
+    .regex(/^did:/, "Must be a valid DID format (starting with did:)")
+    .max(500, "DID must be 500 characters or less")
+    .optional(),
+});
+
+export type ConsentApprovalRequest = z.infer<
+  typeof consentApprovalRequestSchema
+>;
+
+/**
+ * Consent Approval Response Schema
+ */
+export const consentApprovalResponseSchema = z
+  .object({
+    success: z.boolean(),
+    delegation_id: z.string().min(1).optional(),
+    delegation_token: z.string().min(1).optional(),
+    error: z.string().optional(),
+    error_code: 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",
+    }
+  );
+
+export type ConsentApprovalResponse = z.infer<
+  typeof consentApprovalResponseSchema
+>;
+
+/**
+ * Consent Config Schema
+ */
+export const consentConfigSchema = z.object({
+  branding: consentBrandingSchema.optional(),
+  terms: consentTermsSchema.optional(),
+  customFields: z
+    .array(consentCustomFieldSchema)
+    .max(10, "Maximum 10 custom fields allowed")
+    .optional(),
+  ui: z
+    .object({
+      theme: z.enum(["light", "dark", "auto"]).optional(),
+      popupEnabled: z.boolean().optional(),
+      autoClose: z.boolean().optional(),
+      autoCloseDelay: z
+        .number()
+        .int()
+        .positive()
+        .max(60000, "Auto-close delay must be 60000ms or less")
+        .optional(),
+    })
+    .optional(),
+});
+
+export type ConsentConfig = z.infer<typeof consentConfigSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a consent page config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+export function validateConsentPageConfig(config: unknown) {
+  return consentPageConfigSchema.safeParse(config);
+}
+
+/**
+ * Validate a consent approval request
+ *
+ * @param request - The request to validate
+ * @returns Validation result
+ */
+export function validateConsentApprovalRequest(request: unknown) {
+  return consentApprovalRequestSchema.safeParse(request);
+}
+
+/**
+ * Validate a consent approval response
+ *
+ * @param response - The response to validate
+ * @returns Validation result
+ */
+export function validateConsentApprovalResponse(response: unknown) {
+  return consentApprovalResponseSchema.safeParse(response);
+}
+
+/**
+ * Validate a consent config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+export function validateConsentConfig(config: unknown) {
+  return consentConfigSchema.safeParse(config);
+}