@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0-canary.clientinfo.20251126003544

package/src/compliance/schema-verifier.ts

@@ -0,0 +1,708 @@
+/**
+ * Schema Compliance Verification Tool
+ *
+ * Supports JSON Schema draft-07 features:
+ * - $ref resolution
+ * - oneOf, anyOf, allOf
+ * - Nested required fields
+ * - Array tuple validation
+ * - Format, pattern, enum, const
+ * - Recursive object validation
+ */
+
+export interface SchemaMetadata {
+  id: string;
+  url: string;
+  version: string;
+  type: string;
+  description?: string;
+}
+
+export interface FieldComplianceResult {
+  fieldPath: string;
+  present: boolean;
+  expectedType: string;
+  actualType?: string;
+  typeMatches: boolean;
+  required: boolean;
+  status: 'pass' | 'fail' | 'warning';
+  reason?: string;
+}
+
+export interface SchemaComplianceReport {
+  schema: SchemaMetadata;
+  compliant: boolean;
+  compliancePercentage: number;
+  fields: FieldComplianceResult[];
+  issues: string[];
+  warnings: string[];
+  timestamp: number;
+}
+
+export interface FullComplianceReport {
+  totalSchemas: number;
+  compliantSchemas: number;
+  overallCompliance: number;
+  schemaReports: SchemaComplianceReport[];
+  criticalIssues: string[];
+  timestamp: number;
+}
+
+/**
+ * Schema Verifier with JSON Schema draft-07 support
+ */
+export class SchemaVerifier {
+  private schemasBaseUrl = 'https://schemas.kya-os.ai';
+  private schemaCache = new Map<string, any>();
+
+  constructor(options?: { schemasBaseUrl?: string }) {
+    if (options?.schemasBaseUrl) {
+      this.schemasBaseUrl = options.schemasBaseUrl;
+    }
+  }
+
+  /**
+   * Verify a single schema against implementation
+   */
+  async verifySchema(
+    schema: SchemaMetadata,
+    implementation: any
+  ): Promise<SchemaComplianceReport> {
+    const fields: FieldComplianceResult[] = [];
+    const issues: string[] = [];
+    const warnings: string[] = [];
+
+    // Fetch the canonical schema
+    let canonicalSchema: any;
+    try {
+      canonicalSchema = await this.fetchSchema(schema.url);
+    } catch (error) {
+      return {
+        schema,
+        compliant: false,
+        compliancePercentage: 0,
+        fields: [],
+        issues: [
+          `Failed to fetch schema: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        ],
+        warnings: [],
+        timestamp: Date.now(),
+      };
+    }
+
+    // Resolve $ref if present at root
+    const resolvedSchema = this.resolveRef(canonicalSchema, canonicalSchema);
+
+    // Validate the implementation against the schema
+    const validationResult = this.validateAgainstSchema(
+      implementation,
+      resolvedSchema,
+      canonicalSchema,
+      ''
+    );
+
+    fields.push(...validationResult.fields);
+
+    // Separate issues and warnings
+    for (const field of fields) {
+      if (field.status === 'fail') {
+        issues.push(`${field.fieldPath}: ${field.reason}`);
+      } else if (field.status === 'warning') {
+        warnings.push(`${field.fieldPath}: ${field.reason}`);
+      }
+    }
+
+    // Calculate compliance
+    const requiredFields = fields.filter((f) => f.required);
+    const passingRequiredFields = requiredFields.filter(
+      (f) => f.status === 'pass'
+    ).length;
+
+    const compliancePercentage =
+      requiredFields.length > 0
+        ? (passingRequiredFields / requiredFields.length) * 100
+        : 100; // If no required fields, 100% compliant
+
+    const compliant = issues.length === 0 && compliancePercentage >= 95;
+
+    return {
+      schema,
+      compliant,
+      compliancePercentage,
+      fields,
+      issues,
+      warnings,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Verify all schemas
+   */
+  async verifyAll(
+    schemas: SchemaMetadata[],
+    implementations: Map<string, any>
+  ): Promise<FullComplianceReport> {
+    const schemaReports: SchemaComplianceReport[] = [];
+    const criticalIssues: string[] = [];
+
+    for (const schema of schemas) {
+      const implementation = implementations.get(schema.id);
+      if (!implementation) {
+        criticalIssues.push(`No implementation found for schema: ${schema.id}`);
+        continue;
+      }
+
+      const report = await this.verifySchema(schema, implementation);
+      schemaReports.push(report);
+
+      if (!report.compliant) {
+        criticalIssues.push(`${schema.id}: ${report.issues.join(', ')}`);
+      }
+    }
+
+    const compliantSchemas = schemaReports.filter((r) => r.compliant).length;
+    const overallCompliance =
+      schemas.length > 0 ? (compliantSchemas / schemas.length) * 100 : 0;
+
+    return {
+      totalSchemas: schemas.length,
+      compliantSchemas,
+      overallCompliance,
+      schemaReports,
+      criticalIssues,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Validate implementation against schema recursively
+   */
+  private validateAgainstSchema(
+    value: any,
+    schema: any,
+    rootSchema: any,
+    path: string
+  ): { fields: FieldComplianceResult[] } {
+    const fields: FieldComplianceResult[] = [];
+
+    // Resolve $ref
+    schema = this.resolveRef(schema, rootSchema);
+
+    // Handle oneOf, anyOf, allOf
+    if (schema.oneOf || schema.anyOf || schema.allOf) {
+      return this.validateUnion(value, schema, rootSchema, path);
+    }
+
+    // Handle type: object
+    if (schema.type === 'object' && schema.properties) {
+      const required = schema.required || [];
+
+      for (const [propName, propSchema] of Object.entries<any>(
+        schema.properties
+      )) {
+        const propPath = path ? `${path}.${propName}` : propName;
+        const propValue = value?.[propName];
+        const isRequired = required.includes(propName);
+
+        const fieldResult = this.checkField(
+          propPath,
+          propValue,
+          propSchema,
+          rootSchema,
+          isRequired
+        );
+
+        fields.push(fieldResult);
+
+        // Recurse into nested objects
+        if (propValue !== undefined && propSchema.type === 'object') {
+          const nestedResult = this.validateAgainstSchema(
+            propValue,
+            propSchema,
+            rootSchema,
+            propPath
+          );
+          fields.push(...nestedResult.fields);
+        }
+      }
+    }
+
+    // Handle type: array
+    if (schema.type === 'array' && value && Array.isArray(value)) {
+      const arrayResult = this.validateArray(value, schema, rootSchema, path);
+      fields.push(...arrayResult.fields);
+    }
+
+    return { fields };
+  }
+
+  /**
+   * Validate against oneOf, anyOf, allOf
+   */
+  private validateUnion(
+    value: any,
+    schema: any,
+    rootSchema: any,
+    path: string
+  ): { fields: FieldComplianceResult[] } {
+    const fields: FieldComplianceResult[] = [];
+
+    // For anyOf/oneOf, try to find a matching schema
+    if (schema.anyOf || schema.oneOf) {
+      const options = schema.anyOf || schema.oneOf;
+      let matched = false;
+
+      for (const option of options) {
+        const resolvedOption = this.resolveRef(option, rootSchema);
+
+        // Try to validate against this option
+        try {
+          if (this.matchesSchema(value, resolvedOption, rootSchema)) {
+            // Found a match, validate with this schema
+            const result = this.validateAgainstSchema(
+              value,
+              resolvedOption,
+              rootSchema,
+              path
+            );
+            fields.push(...result.fields);
+            matched = true;
+            break;
+          }
+        } catch (e) {
+          // Doesn't match this option, try next
+          continue;
+        }
+      }
+
+      if (!matched && path) {
+        // Didn't match any option
+        fields.push({
+          fieldPath: path,
+          present: value !== undefined,
+          expectedType: 'oneOf/anyOf options',
+          actualType: typeof value,
+          typeMatches: false,
+          required: true,
+          status: 'fail',
+          reason: 'Value does not match any of the schema options',
+        });
+      }
+    }
+
+    // For allOf, validate against all schemas
+    if (schema.allOf) {
+      for (const subSchema of schema.allOf) {
+        const resolvedSubSchema = this.resolveRef(subSchema, rootSchema);
+        const result = this.validateAgainstSchema(
+          value,
+          resolvedSubSchema,
+          rootSchema,
+          path
+        );
+        fields.push(...result.fields);
+      }
+    }
+
+    return { fields };
+  }
+
+  /**
+   * Check if value matches schema (lightweight check)
+   */
+  private matchesSchema(value: any, schema: any, rootSchema: any): boolean {
+    schema = this.resolveRef(schema, rootSchema);
+
+    // Check type
+    if (schema.type) {
+      const actualType = Array.isArray(value) ? 'array' : typeof value;
+      // JSON Schema "integer" matches JavaScript "number" (if it's an integer)
+      if (schema.type === 'integer' && actualType === 'number') {
+        if (!Number.isInteger(value)) {
+          return false;
+        }
+      } else if (schema.type !== actualType) {
+        return false;
+      }
+    }
+
+    // Check const
+    if (schema.const !== undefined && value !== schema.const) {
+      return false;
+    }
+
+    // Check enum
+    if (schema.enum && !schema.enum.includes(value)) {
+      return false;
+    }
+
+    // Check pattern (for strings)
+    if (schema.pattern && typeof value === 'string') {
+      const regex = new RegExp(schema.pattern);
+      if (!regex.test(value)) {
+        return false;
+      }
+    }
+
+    // Check required properties (for objects)
+    if (schema.type === 'object' && schema.required) {
+      for (const requiredProp of schema.required) {
+        if (!(requiredProp in value)) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate array against schema
+   */
+  private validateArray(
+    value: any[],
+    schema: any,
+    rootSchema: any,
+    path: string
+  ): { fields: FieldComplianceResult[] } {
+    const fields: FieldComplianceResult[] = [];
+
+    // Check minItems
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      fields.push({
+        fieldPath: `${path}.length`,
+        present: true,
+        expectedType: `array with minItems: ${schema.minItems}`,
+        actualType: `array with length: ${value.length}`,
+        typeMatches: false,
+        required: true,
+        status: 'fail',
+        reason: `Array length ${value.length} is less than minItems ${schema.minItems}`,
+      });
+    }
+
+    // Check tuple validation (items as array)
+    if (Array.isArray(schema.items)) {
+      for (let i = 0; i < schema.items.length; i++) {
+        const itemSchema = schema.items[i];
+        const itemValue = value[i];
+        const itemPath = `${path}[${i}]`;
+
+        if (itemValue !== undefined) {
+          const resolvedItemSchema = this.resolveRef(itemSchema, rootSchema);
+          const itemResult = this.validateAgainstSchema(
+            itemValue,
+            resolvedItemSchema,
+            rootSchema,
+            itemPath
+          );
+          fields.push(...itemResult.fields);
+        }
+      }
+
+      // Check additionalItems
+      if (schema.additionalItems !== undefined && value.length > schema.items.length) {
+        for (let i = schema.items.length; i < value.length; i++) {
+          const itemValue = value[i];
+          const itemPath = `${path}[${i}]`;
+          const itemResult = this.validateAgainstSchema(
+            itemValue,
+            schema.additionalItems,
+            rootSchema,
+            itemPath
+          );
+          fields.push(...itemResult.fields);
+        }
+      }
+    } else if (schema.items) {
+      // Single schema for all items
+      for (let i = 0; i < value.length; i++) {
+        const itemValue = value[i];
+        const itemPath = `${path}[${i}]`;
+        const resolvedItemSchema = this.resolveRef(schema.items, rootSchema);
+        const itemResult = this.validateAgainstSchema(
+          itemValue,
+          resolvedItemSchema,
+          rootSchema,
+          itemPath
+        );
+        fields.push(...itemResult.fields);
+      }
+    }
+
+    // Check contains (at least one item must match)
+    if (schema.contains) {
+      const containsSchema = this.resolveRef(schema.contains, rootSchema);
+      const hasMatch = value.some((item) =>
+        this.matchesSchema(item, containsSchema, rootSchema)
+      );
+
+      if (!hasMatch) {
+        fields.push({
+          fieldPath: `${path}.contains`,
+          present: true,
+          expectedType: 'array containing matching item',
+          actualType: 'array without matching item',
+          typeMatches: false,
+          required: true,
+          status: 'fail',
+          reason: 'Array does not contain any item matching the "contains" schema',
+        });
+      }
+    }
+
+    return { fields };
+  }
+
+  /**
+   * Check a single field
+   */
+  private checkField(
+    fieldPath: string,
+    value: any,
+    schema: any,
+    rootSchema: any,
+    required: boolean
+  ): FieldComplianceResult {
+    schema = this.resolveRef(schema, rootSchema);
+
+    const present = value !== undefined;
+    const actualType = this.getActualType(value);
+
+    // Get expected type
+    let expectedType = 'unknown';
+    if (schema.type) {
+      expectedType = schema.type;
+    } else if (schema.anyOf) {
+      expectedType = 'anyOf';
+    } else if (schema.oneOf) {
+      expectedType = 'oneOf';
+    } else if (schema.allOf) {
+      expectedType = 'allOf';
+    }
+
+    // Check if required field is missing
+    if (required && !present) {
+      return {
+        fieldPath,
+        present,
+        expectedType,
+        actualType,
+        typeMatches: false,
+        required,
+        status: 'fail',
+        reason: 'Required field missing',
+      };
+    }
+
+    // Check if optional field is missing
+    if (!required && !present) {
+      return {
+        fieldPath,
+        present,
+        expectedType,
+        actualType,
+        typeMatches: true, // Optional field can be missing
+        required,
+        status: 'pass',
+      };
+    }
+
+    // Value is present, check if it matches schema
+    const typeMatches = this.matchesSchema(value, schema, rootSchema);
+
+    if (!typeMatches) {
+      return {
+        fieldPath,
+        present,
+        expectedType,
+        actualType,
+        typeMatches: false,
+        required,
+        status: 'fail',
+        reason: `Type/value mismatch`,
+      };
+    }
+
+    // All good
+    return {
+      fieldPath,
+      present,
+      expectedType,
+      actualType,
+      typeMatches: true,
+      required,
+      status: 'pass',
+    };
+  }
+
+  /**
+   * Get actual JavaScript type
+   */
+  private getActualType(value: any): string {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    if (typeof value === 'number' && Number.isInteger(value)) return 'integer';
+    return typeof value;
+  }
+
+  /**
+   * Resolve $ref reference
+   */
+  private resolveRef(schema: any, rootSchema: any): any {
+    if (!schema.$ref) {
+      return schema;
+    }
+
+    const ref = schema.$ref;
+
+    // Handle #/definitions/Foo
+    if (ref.startsWith('#/definitions/')) {
+      const defName = ref.substring('#/definitions/'.length);
+      if (rootSchema.definitions && rootSchema.definitions[defName]) {
+        return rootSchema.definitions[defName];
+      }
+    }
+
+    // Handle #/$defs/Foo (draft-07+)
+    if (ref.startsWith('#/$defs/')) {
+      const defName = ref.substring('#/$defs/'.length);
+      if (rootSchema.$defs && rootSchema.$defs[defName]) {
+        return rootSchema.$defs[defName];
+      }
+    }
+
+    // Handle # (root)
+    if (ref === '#') {
+      return rootSchema;
+    }
+
+    // If we can't resolve, return original
+    return schema;
+  }
+
+  /**
+   * Fetch a schema from URL
+   */
+  private async fetchSchema(url: string): Promise<any> {
+    // Check cache
+    if (this.schemaCache.has(url)) {
+      return this.schemaCache.get(url);
+    }
+
+    try {
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const schema = await response.json();
+      this.schemaCache.set(url, schema);
+      return schema;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to fetch schema from ${url}: ${error.message}`);
+      }
+      throw new Error(`Failed to fetch schema from ${url}: Unknown error`);
+    }
+  }
+
+  /**
+   * Generate a formatted report
+   */
+  generateReport(report: SchemaComplianceReport): string {
+    const lines: string[] = [];
+
+    lines.push(`\n${'='.repeat(80)}`);
+    lines.push(`SCHEMA COMPLIANCE REPORT: ${report.schema.id}`);
+    lines.push(`${'='.repeat(80)}\n`);
+
+    lines.push(`Schema: ${report.schema.type} v${report.schema.version}`);
+    lines.push(`URL: ${report.schema.url}`);
+    lines.push(
+      `Status: ${report.compliant ? '✅ COMPLIANT' : '❌ NON-COMPLIANT'}`
+    );
+    lines.push(`Compliance: ${report.compliancePercentage.toFixed(1)}%\n`);
+
+    if (report.issues.length > 0) {
+      lines.push(`\n🚨 ISSUES (${report.issues.length}):`);
+      report.issues.forEach((issue, i) => {
+        lines.push(`  ${i + 1}. ${issue}`);
+      });
+    }
+
+    if (report.warnings.length > 0) {
+      lines.push(`\n⚠️  WARNINGS (${report.warnings.length}):`);
+      report.warnings.forEach((warning, i) => {
+        lines.push(`  ${i + 1}. ${warning}`);
+      });
+    }
+
+    lines.push(`\n📊 FIELD DETAILS:\n`);
+    const requiredFields = report.fields.filter((f) => f.required);
+    const passing = requiredFields.filter((f) => f.status === 'pass').length;
+    const failing = requiredFields.filter((f) => f.status === 'fail').length;
+    const warnings = report.fields.filter((f) => f.status === 'warning').length;
+
+    lines.push(`  ✅ Pass: ${passing}/${requiredFields.length} required fields`);
+    lines.push(`  ❌ Fail: ${failing}/${requiredFields.length} required fields`);
+    lines.push(`  ⚠️  Warn: ${warnings} optional fields`);
+    lines.push(`  📝 Total: ${report.fields.length} fields checked\n`);
+
+    lines.push(`${'='.repeat(80)}\n`);
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate full report
+   */
+  generateFullReport(report: FullComplianceReport): string {
+    const lines: string[] = [];
+
+    lines.push(`\n${'='.repeat(80)}`);
+    lines.push(`FULL SCHEMA COMPLIANCE REPORT`);
+    lines.push(`${'='.repeat(80)}\n`);
+
+    lines.push(`Total Schemas: ${report.totalSchemas}`);
+    lines.push(`Compliant: ${report.compliantSchemas}`);
+    lines.push(
+      `Non-Compliant: ${report.totalSchemas - report.compliantSchemas}`
+    );
+    lines.push(`Overall Compliance: ${report.overallCompliance.toFixed(1)}%\n`);
+
+    if (report.criticalIssues.length > 0) {
+      lines.push(`\n🚨 CRITICAL ISSUES (${report.criticalIssues.length}):`);
+      report.criticalIssues.slice(0, 10).forEach((issue, i) => {
+        lines.push(`  ${i + 1}. ${issue}`);
+      });
+      if (report.criticalIssues.length > 10) {
+        lines.push(
+          `  ... and ${report.criticalIssues.length - 10} more issues`
+        );
+      }
+    }
+
+    lines.push(`\n📊 SCHEMA BREAKDOWN:\n`);
+    report.schemaReports.forEach((schemaReport) => {
+      const icon = schemaReport.compliant ? '✅' : '❌';
+      const percentage = schemaReport.compliancePercentage.toFixed(1);
+      lines.push(`  ${icon} ${schemaReport.schema.id}: ${percentage}%`);
+    });
+
+    lines.push(`\n${'='.repeat(80)}\n`);
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Create a schema verifier
+ */
+export function createSchemaVerifier(options?: {
+  schemasBaseUrl?: string;
+}): SchemaVerifier {
+  return new SchemaVerifier(options);
+}