@ucptools/validator 1.0.0 → 1.1.0

package/src/validator/network-validator.ts

@@ -1,417 +0,0 @@
-/**
- * Network Validator
- * Validates UCP profile with network checks (fetches remote schemas)
- */
-
-import type { UcpProfile } from '../types/ucp-profile.js';
-import type { ValidationIssue, FetchResult, SchemaCacheEntry } from '../types/validation.js';
-import { ValidationErrorCodes } from '../types/validation.js';
-
-// Simple in-memory cache for schema fetches
-const schemaCache = new Map<string, SchemaCacheEntry>();
-const DEFAULT_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
-const DEFAULT_TIMEOUT_MS = 10000; // 10 seconds
-
-export interface NetworkValidationOptions {
-  timeoutMs?: number;
-  cacheTtlMs?: number;
-  skipSchemaFetch?: boolean;
-}
-
-/**
- * Validate UCP profile with network checks
- */
-export async function validateNetwork(
-  profile: UcpProfile,
-  options: NetworkValidationOptions = {}
-): Promise<ValidationIssue[]> {
-  const issues: ValidationIssue[] = [];
-  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
-  const cacheTtlMs = options.cacheTtlMs || DEFAULT_CACHE_TTL_MS;
-
-  if (options.skipSchemaFetch) {
-    return issues;
-  }
-
-  const capabilities = profile.ucp.capabilities || [];
-
-  // Validate each capability's schema
-  for (let i = 0; i < capabilities.length; i++) {
-    const cap = capabilities[i];
-    const path = `$.ucp.capabilities[${i}]`;
-
-    if (cap.schema) {
-      const schemaIssues = await validateCapabilitySchema(
-        cap.schema,
-        cap.name,
-        cap.version,
-        path,
-        timeoutMs,
-        cacheTtlMs
-      );
-      issues.push(...schemaIssues);
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Validate remote profile fetch
- */
-export async function validateRemoteProfile(
-  domain: string,
-  options: NetworkValidationOptions = {}
-): Promise<{ profile: UcpProfile | null; profileUrl?: string; issues: ValidationIssue[] }> {
-  const issues: ValidationIssue[] = [];
-  const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
-
-  // Try both /.well-known/ucp and /.well-known/ucp.json
-  const urls = [
-    `https://${domain}/.well-known/ucp`,
-    `https://${domain}/.well-known/ucp.json`,
-  ];
-
-  for (const profileUrl of urls) {
-    const result = await fetchProfileWithTimeout(profileUrl, timeoutMs);
-
-    if (!result.success) {
-      // Try next URL
-      continue;
-    }
-
-    // Verify it's an object with ucp field
-    if (!result.data || typeof result.data !== 'object') {
-      continue;
-    }
-
-    const profileData = result.data as Record<string, unknown>;
-    if (!profileData.ucp) {
-      continue;
-    }
-
-    return { profile: result.data as UcpProfile, profileUrl, issues };
-  }
-
-  // All URLs failed
-  issues.push({
-    severity: 'error',
-    code: ValidationErrorCodes.PROFILE_FETCH_FAILED,
-    path: '$.well-known/ucp',
-    message: 'No UCP profile found at /.well-known/ucp or /.well-known/ucp.json',
-    hint: 'Check that the profile is accessible and returns valid JSON',
-  });
-  return { profile: null, issues };
-}
-
-/**
- * Validate a capability's schema (fetch and check self-describing)
- */
-async function validateCapabilitySchema(
-  schemaUrl: string,
-  expectedName: string,
-  expectedVersion: string,
-  basePath: string,
-  timeoutMs: number,
-  cacheTtlMs: number
-): Promise<ValidationIssue[]> {
-  const issues: ValidationIssue[] = [];
-
-  // Check cache first
-  const cached = getCachedSchema(schemaUrl, cacheTtlMs);
-  let schemaData: Record<string, unknown>;
-
-  if (cached) {
-    schemaData = cached;
-  } else {
-    // Fetch schema
-    const result = await fetchWithTimeout<Record<string, unknown>>(schemaUrl, timeoutMs);
-
-    if (!result.success) {
-      issues.push({
-        severity: 'warn',
-        code: ValidationErrorCodes.SCHEMA_FETCH_FAILED,
-        path: `${basePath}.schema`,
-        message: `Failed to fetch schema from ${schemaUrl}`,
-        hint: result.error || 'Schema URL may be incorrect or temporarily unavailable',
-      });
-      return issues;
-    }
-
-    if (!result.data) {
-      issues.push({
-        severity: 'warn',
-        code: ValidationErrorCodes.SCHEMA_FETCH_FAILED,
-        path: `${basePath}.schema`,
-        message: `Schema response is empty`,
-      });
-      return issues;
-    }
-
-    schemaData = result.data;
-
-    // Cache the schema
-    cacheSchema(schemaUrl, schemaData, result.etag, cacheTtlMs);
-  }
-
-  // Check if schema is self-describing
-  const selfDescribingIssues = validateSelfDescribingSchema(
-    schemaData,
-    expectedName,
-    expectedVersion,
-    basePath
-  );
-  issues.push(...selfDescribingIssues);
-
-  return issues;
-}
-
-/**
- * Validate schema is self-describing (contains name and version matching capability)
- */
-function validateSelfDescribingSchema(
-  schema: Record<string, unknown>,
-  expectedName: string,
-  expectedVersion: string,
-  basePath: string
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  // Check for $id or name field
-  const schemaName = (schema.$id as string) || (schema.name as string);
-  const schemaVersion = schema.version as string;
-
-  if (!schemaName && !schema.$id) {
-    issues.push({
-      severity: 'info',
-      code: ValidationErrorCodes.SCHEMA_NOT_SELF_DESCRIBING,
-      path: `${basePath}.schema`,
-      message: 'Schema does not contain self-describing $id or name field',
-      hint: 'Consider adding $id field to schema for better discoverability',
-    });
-  }
-
-  // If schema has a name, check it contains the capability name
-  if (schemaName) {
-    // Extract capability name from schema $id if it's a URL
-    const nameFromId = extractNameFromSchemaId(schemaName);
-    if (nameFromId && !expectedName.includes(nameFromId) && !nameFromId.includes(expectedName.split('.').pop() || '')) {
-      issues.push({
-        severity: 'warn',
-        code: ValidationErrorCodes.SCHEMA_NAME_MISMATCH,
-        path: `${basePath}.schema`,
-        message: `Schema name "${nameFromId}" may not match capability "${expectedName}"`,
-      });
-    }
-  }
-
-  // Check version if present
-  if (schemaVersion && schemaVersion !== expectedVersion) {
-    issues.push({
-      severity: 'info',
-      code: ValidationErrorCodes.SCHEMA_VERSION_MISMATCH,
-      path: `${basePath}.schema`,
-      message: `Schema version "${schemaVersion}" differs from capability version "${expectedVersion}"`,
-      hint: 'Ensure schema and capability versions are aligned',
-    });
-  }
-
-  return issues;
-}
-
-/**
- * Extract capability name from schema $id URL
- */
-function extractNameFromSchemaId(schemaId: string): string | null {
-  try {
-    const url = new URL(schemaId);
-    // Extract last path segment without .json extension
-    const pathParts = url.pathname.split('/').filter(Boolean);
-    const lastPart = pathParts[pathParts.length - 1] || '';
-    return lastPart.replace('.json', '');
-  } catch {
-    // Not a URL, return as-is
-    return schemaId;
-  }
-}
-
-/**
- * Fetch profile URL with timeout, checking for HTML responses
- */
-async function fetchProfileWithTimeout(
-  url: string,
-  timeoutMs: number
-): Promise<FetchResult<unknown>> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        'Accept': 'application/json',
-        'User-Agent': 'UCP-Profile-Validator/1.0',
-      },
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      return {
-        success: false,
-        error: `HTTP ${response.status}: ${response.statusText}`,
-        statusCode: response.status,
-      };
-    }
-
-    const text = await response.text();
-
-    // Check if response looks like JSON (not HTML)
-    if (text.trim().startsWith('<')) {
-      return {
-        success: false,
-        error: 'Response is HTML, not JSON',
-      };
-    }
-
-    const data = JSON.parse(text);
-    const etag = response.headers.get('etag') || undefined;
-
-    return {
-      success: true,
-      data,
-      statusCode: response.status,
-      etag,
-    };
-  } catch (error) {
-    clearTimeout(timeoutId);
-
-    if (error instanceof Error) {
-      if (error.name === 'AbortError') {
-        return {
-          success: false,
-          error: `Request timed out after ${timeoutMs}ms`,
-        };
-      }
-      return {
-        success: false,
-        error: error.message,
-      };
-    }
-
-    return {
-      success: false,
-      error: 'Unknown error occurred',
-    };
-  }
-}
-
-/**
- * Fetch URL with timeout
- */
-async function fetchWithTimeout<T>(
-  url: string,
-  timeoutMs: number
-): Promise<FetchResult<T>> {
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        'Accept': 'application/json',
-        'User-Agent': 'UCP-Profile-Validator/1.0',
-      },
-    });
-
-    clearTimeout(timeoutId);
-
-    if (!response.ok) {
-      return {
-        success: false,
-        error: `HTTP ${response.status}: ${response.statusText}`,
-        statusCode: response.status,
-      };
-    }
-
-    const data = await response.json() as T;
-    const etag = response.headers.get('etag') || undefined;
-
-    return {
-      success: true,
-      data,
-      statusCode: response.status,
-      etag,
-    };
-  } catch (error) {
-    clearTimeout(timeoutId);
-
-    if (error instanceof Error) {
-      if (error.name === 'AbortError') {
-        return {
-          success: false,
-          error: `Request timed out after ${timeoutMs}ms`,
-        };
-      }
-      return {
-        success: false,
-        error: error.message,
-      };
-    }
-
-    return {
-      success: false,
-      error: 'Unknown error occurred',
-    };
-  }
-}
-
-/**
- * Get cached schema if valid
- */
-function getCachedSchema(
-  url: string,
-  cacheTtlMs: number
-): Record<string, unknown> | null {
-  const cached = schemaCache.get(url);
-  if (!cached) {
-    return null;
-  }
-
-  const now = new Date().toISOString();
-  if (cached.expiresAt < now) {
-    schemaCache.delete(url);
-    return null;
-  }
-
-  return cached.body;
-}
-
-/**
- * Cache a schema
- */
-function cacheSchema(
-  url: string,
-  body: Record<string, unknown>,
-  etag: string | undefined,
-  cacheTtlMs: number
-): void {
-  const now = new Date();
-  const expiresAt = new Date(now.getTime() + cacheTtlMs);
-
-  schemaCache.set(url, {
-    url,
-    etag,
-    fetchedAt: now.toISOString(),
-    body,
-    expiresAt: expiresAt.toISOString(),
-  });
-}
-
-/**
- * Clear the schema cache
- */
-export function clearSchemaCache(): void {
-  schemaCache.clear();
-}

package/src/validator/rules-validator.ts

@@ -1,297 +0,0 @@
-/**
- * UCP Rules Validator
- * Validates UCP-specific business rules (no network calls)
- */
-
-import type { UcpProfile, UcpCapability } from '../types/ucp-profile.js';
-import type { ValidationIssue } from '../types/validation.js';
-import { ValidationErrorCodes } from '../types/validation.js';
-import { CAPABILITY_NAMESPACES, KNOWN_CAPABILITIES } from '../types/ucp-profile.js';
-
-/**
- * Validate UCP business rules
- */
-export function validateRules(profile: UcpProfile): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  // Validate namespace/origin binding for capabilities
-  issues.push(...validateNamespaceOrigins(profile));
-
-  // Validate extension chains (no orphaned extends)
-  issues.push(...validateExtensions(profile));
-
-  // Validate endpoint rules
-  issues.push(...validateEndpoints(profile));
-
-  // Validate signing keys if Order capability is present
-  issues.push(...validateSigningKeysRequirement(profile));
-
-  return issues;
-}
-
-/**
- * Validate namespace and URL origin binding
- * - dev.ucp.* capabilities must have spec/schema from ucp.dev
- * - com.vendor.* capabilities must have spec/schema from vendor's domain
- */
-function validateNamespaceOrigins(profile: UcpProfile): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const capabilities = profile.ucp.capabilities || [];
-
-  for (let i = 0; i < capabilities.length; i++) {
-    const cap = capabilities[i];
-    const path = `$.ucp.capabilities[${i}]`;
-
-    // Check dev.ucp.* namespace
-    if (cap.name.startsWith(CAPABILITY_NAMESPACES.UCP_OFFICIAL)) {
-      // Spec must be from ucp.dev
-      if (cap.spec && !isUcpDevOrigin(cap.spec)) {
-        issues.push({
-          severity: 'error',
-          code: ValidationErrorCodes.NS_ORIGIN_MISMATCH,
-          path: `${path}.spec`,
-          message: `dev.ucp.* capability spec must be hosted on ucp.dev`,
-          hint: `Use https://ucp.dev/specification/... instead of "${cap.spec}"`,
-        });
-      }
-
-      // Schema must be from ucp.dev
-      if (cap.schema && !isUcpDevOrigin(cap.schema)) {
-        issues.push({
-          severity: 'error',
-          code: ValidationErrorCodes.NS_ORIGIN_MISMATCH,
-          path: `${path}.schema`,
-          message: `dev.ucp.* capability schema must be hosted on ucp.dev`,
-          hint: `Use https://ucp.dev/schemas/... instead of "${cap.schema}"`,
-        });
-      }
-    }
-
-    // Check vendor namespace (com.vendor.*)
-    if (cap.name.startsWith(CAPABILITY_NAMESPACES.VENDOR_PREFIX)) {
-      const vendorDomain = extractVendorDomain(cap.name);
-      if (vendorDomain) {
-        // Spec origin should match vendor domain
-        if (cap.spec && !isOriginFromDomain(cap.spec, vendorDomain)) {
-          issues.push({
-            severity: 'warn',
-            code: ValidationErrorCodes.NS_ORIGIN_MISMATCH,
-            path: `${path}.spec`,
-            message: `Vendor capability spec should be hosted on vendor's domain (${vendorDomain})`,
-            hint: `Consider hosting spec at https://${vendorDomain}/...`,
-          });
-        }
-
-        // Schema origin should match vendor domain
-        if (cap.schema && !isOriginFromDomain(cap.schema, vendorDomain)) {
-          issues.push({
-            severity: 'warn',
-            code: ValidationErrorCodes.NS_ORIGIN_MISMATCH,
-            path: `${path}.schema`,
-            message: `Vendor capability schema should be hosted on vendor's domain (${vendorDomain})`,
-            hint: `Consider hosting schema at https://${vendorDomain}/...`,
-          });
-        }
-      }
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Validate extension chains - ensure parent capabilities exist
- */
-function validateExtensions(profile: UcpProfile): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const capabilities = profile.ucp.capabilities || [];
-
-  // Build set of capability names
-  const capabilityNames = new Set(capabilities.map(c => c.name));
-
-  for (let i = 0; i < capabilities.length; i++) {
-    const cap = capabilities[i];
-
-    if (cap.extends) {
-      // Check if parent capability exists in this profile
-      if (!capabilityNames.has(cap.extends)) {
-        issues.push({
-          severity: 'error',
-          code: ValidationErrorCodes.ORPHANED_EXTENSION,
-          path: `$.ucp.capabilities[${i}].extends`,
-          message: `Extension "${cap.name}" references non-existent parent capability "${cap.extends}"`,
-          hint: `Add "${cap.extends}" to capabilities or remove the extends field`,
-        });
-      }
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Validate endpoint rules (https, no trailing slash)
- */
-function validateEndpoints(profile: UcpProfile): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const services = profile.ucp.services || {};
-
-  for (const [serviceName, service] of Object.entries(services)) {
-    const basePath = `$.ucp.services["${serviceName}"]`;
-
-    // Validate REST endpoint
-    if (service.rest?.endpoint) {
-      issues.push(...validateEndpoint(service.rest.endpoint, `${basePath}.rest.endpoint`));
-    }
-
-    // Validate MCP endpoint
-    if (service.mcp?.endpoint) {
-      issues.push(...validateEndpoint(service.mcp.endpoint, `${basePath}.mcp.endpoint`));
-    }
-
-    // Validate A2A agent card URL
-    if (service.a2a?.agentCard) {
-      issues.push(...validateEndpoint(service.a2a.agentCard, `${basePath}.a2a.agentCard`));
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Validate a single endpoint URL
- */
-function validateEndpoint(endpoint: string, path: string): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  // Must be HTTPS
-  if (!endpoint.startsWith('https://')) {
-    issues.push({
-      severity: 'error',
-      code: ValidationErrorCodes.ENDPOINT_NOT_HTTPS,
-      path,
-      message: `Endpoint must use HTTPS`,
-      hint: `Change "${endpoint}" to use https://`,
-    });
-  }
-
-  // Should not have trailing slash
-  if (endpoint.endsWith('/')) {
-    issues.push({
-      severity: 'warn',
-      code: ValidationErrorCodes.ENDPOINT_TRAILING_SLASH,
-      path,
-      message: `Endpoint should not have a trailing slash`,
-      hint: `Remove trailing slash from "${endpoint}"`,
-    });
-  }
-
-  // Check for private IP ranges (basic check)
-  if (isPrivateIpEndpoint(endpoint)) {
-    issues.push({
-      severity: 'warn',
-      code: ValidationErrorCodes.PRIVATE_IP_ENDPOINT,
-      path,
-      message: `Endpoint appears to use a private IP address`,
-      hint: `Use a public domain name for production profiles`,
-    });
-  }
-
-  return issues;
-}
-
-/**
- * Validate signing keys requirement for Order capability
- */
-function validateSigningKeysRequirement(profile: UcpProfile): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  const capabilities = profile.ucp.capabilities || [];
-
-  // Check if Order capability is present
-  const hasOrderCapability = capabilities.some(
-    c => c.name === KNOWN_CAPABILITIES.ORDER
-  );
-
-  if (hasOrderCapability) {
-    // Signing keys should be present for webhook signing
-    if (!profile.signing_keys || profile.signing_keys.length === 0) {
-      issues.push({
-        severity: 'error',
-        code: ValidationErrorCodes.MISSING_SIGNING_KEYS,
-        path: '$.signing_keys',
-        message: `Order capability requires signing_keys for webhook verification`,
-        hint: `Add signing_keys array with at least one JWK public key`,
-      });
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Check if URL is from ucp.dev origin
- */
-function isUcpDevOrigin(url: string): boolean {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname === 'ucp.dev' || parsed.hostname.endsWith('.ucp.dev');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Extract vendor domain from capability name
- * e.g., "com.example.feature" -> "example.com"
- */
-function extractVendorDomain(name: string): string | null {
-  if (!name.startsWith('com.')) {
-    return null;
-  }
-
-  const parts = name.split('.');
-  if (parts.length < 3) {
-    return null;
-  }
-
-  // "com.example.feature" -> "example.com"
-  return `${parts[1]}.com`;
-}
-
-/**
- * Check if URL origin matches expected domain
- */
-function isOriginFromDomain(url: string, domain: string): boolean {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if endpoint uses private IP address
- */
-function isPrivateIpEndpoint(endpoint: string): boolean {
-  try {
-    const parsed = new URL(endpoint);
-    const hostname = parsed.hostname;
-
-    // Check for localhost
-    if (hostname === 'localhost' || hostname === '127.0.0.1') {
-      return true;
-    }
-
-    // Check for private IP ranges (simplified)
-    if (hostname.startsWith('10.') ||
-        hostname.startsWith('192.168.') ||
-        hostname.match(/^172\.(1[6-9]|2[0-9]|3[0-1])\./)) {
-      return true;
-    }
-
-    return false;
-  } catch {
-    return false;
-  }
-}