@ucptools/validator 1.0.0 → 1.0.1

package/src/types/validation.ts

@@ -1,89 +0,0 @@
-/**
- * Validation Types for UCP Profile Validator
- */
-
-// Validation severity levels
-export type ValidationSeverity = 'error' | 'warn' | 'info';
-
-// Validation error codes
-export const ValidationErrorCodes = {
-  // Structural errors
-  MISSING_UCP_OBJECT: 'UCP_MISSING_ROOT',
-  MISSING_VERSION: 'UCP_MISSING_VERSION',
-  INVALID_VERSION_FORMAT: 'UCP_INVALID_VERSION_FORMAT',
-  MISSING_SERVICES: 'UCP_MISSING_SERVICES',
-  MISSING_CAPABILITIES: 'UCP_MISSING_CAPABILITIES',
-  INVALID_SERVICE_STRUCTURE: 'UCP_INVALID_SERVICE',
-  INVALID_CAPABILITY_STRUCTURE: 'UCP_INVALID_CAPABILITY',
-
-  // UCP rules errors
-  NS_ORIGIN_MISMATCH: 'UCP_NS_ORIGIN_MISMATCH',
-  ORPHANED_EXTENSION: 'UCP_ORPHANED_EXTENSION',
-  ENDPOINT_NOT_HTTPS: 'UCP_ENDPOINT_NOT_HTTPS',
-  ENDPOINT_TRAILING_SLASH: 'UCP_ENDPOINT_TRAILING_SLASH',
-  MISSING_SIGNING_KEYS: 'UCP_MISSING_SIGNING_KEYS',
-  INVALID_SIGNING_KEY: 'UCP_INVALID_SIGNING_KEY',
-
-  // Network validation errors
-  PROFILE_FETCH_FAILED: 'UCP_PROFILE_FETCH_FAILED',
-  SCHEMA_FETCH_FAILED: 'UCP_SCHEMA_FETCH_FAILED',
-  SCHEMA_NOT_SELF_DESCRIBING: 'UCP_SCHEMA_NOT_SELF_DESCRIBING',
-  SCHEMA_NAME_MISMATCH: 'UCP_SCHEMA_NAME_MISMATCH',
-  SCHEMA_VERSION_MISMATCH: 'UCP_SCHEMA_VERSION_MISMATCH',
-  PRIVATE_IP_ENDPOINT: 'UCP_PRIVATE_IP_ENDPOINT',
-} as const;
-
-export type ValidationErrorCode = typeof ValidationErrorCodes[keyof typeof ValidationErrorCodes];
-
-// Single validation issue
-export interface ValidationIssue {
-  severity: ValidationSeverity;
-  code: ValidationErrorCode;
-  path: string;          // JSON path (e.g., "$.ucp.capabilities[0].schema")
-  message: string;       // Human-readable message
-  hint?: string;         // Suggestion for fixing
-}
-
-// Validation report
-export interface ValidationReport {
-  ok: boolean;
-  profile_url?: string;   // For remote validation
-  ucp_version?: string;
-  issues: ValidationIssue[];
-  validated_at: string;   // ISO timestamp
-  validation_mode: ValidationMode;
-  sdk_validation?: {       // Official SDK validation info
-    validated: boolean;    // Whether SDK validation passed
-    sdk_version: string;   // @ucp-js/sdk version used
-    compliant: boolean;    // Whether profile is SDK-compliant
-  };
-}
-
-// Validation modes
-export type ValidationMode = 'structural' | 'rules' | 'network' | 'full';
-
-// Validation options
-export interface ValidationOptions {
-  mode?: ValidationMode;
-  skipNetworkChecks?: boolean;
-  timeoutMs?: number;
-  cacheTtlMs?: number;
-}
-
-// Schema cache entry
-export interface SchemaCacheEntry {
-  url: string;
-  etag?: string;
-  fetchedAt: string;
-  body: Record<string, unknown>;
-  expiresAt: string;
-}
-
-// Remote fetch result
-export interface FetchResult<T> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  statusCode?: number;
-  etag?: string;
-}

package/src/validator/index.ts

@@ -1,194 +0,0 @@
-/**
- * UCP Profile Validator
- * Main entry point combining structural, rules, and network validation
- */
-
-import type { UcpProfile } from '../types/ucp-profile.js';
-import type {
-  ValidationReport,
-  ValidationIssue,
-  ValidationMode,
-  ValidationOptions,
-} from '../types/validation.js';
-import { validateStructure } from './structural-validator.js';
-import { validateRules } from './rules-validator.js';
-import { validateNetwork, validateRemoteProfile, clearSchemaCache } from './network-validator.js';
-import { safeValidateWithSdk, getSdkVersion, isSdkCompliant } from './sdk-validator.js';
-import type { NetworkValidationOptions } from './network-validator.js';
-
-export { validateStructure } from './structural-validator.js';
-export { validateRules } from './rules-validator.js';
-export { validateNetwork, validateRemoteProfile, clearSchemaCache } from './network-validator.js';
-export {
-  safeValidateWithSdk,
-  validateWithSdk,
-  getSdkVersion,
-  isSdkCompliant,
-  validateServiceWithSdk,
-  validateCapabilityWithSdk,
-  validateSigningKeysWithSdk,
-} from './sdk-validator.js';
-
-/**
- * Validate a UCP profile (local JSON)
- */
-export async function validateProfile(
-  profile: unknown,
-  options: ValidationOptions = {}
-): Promise<ValidationReport> {
-  const mode = options.mode || 'full';
-  const issues: ValidationIssue[] = [];
-
-  // Phase 1: Structural validation (always run)
-  if (mode === 'structural' || mode === 'rules' || mode === 'full') {
-    const structuralIssues = validateStructure(profile);
-    issues.push(...structuralIssues);
-
-    // If structural validation has errors, don't proceed with rules/network
-    const hasStructuralErrors = structuralIssues.some(i => i.severity === 'error');
-    if (hasStructuralErrors && mode !== 'structural') {
-      return buildReport(issues, mode, undefined, profile);
-    }
-  }
-
-  // At this point, profile structure is valid
-  const ucpProfile = profile as UcpProfile;
-
-  // Phase 2: UCP rules validation
-  if (mode === 'rules' || mode === 'full') {
-    const rulesIssues = validateRules(ucpProfile);
-    issues.push(...rulesIssues);
-  }
-
-  // Phase 3: Network validation (optional)
-  if (mode === 'network' || mode === 'full') {
-    if (!options.skipNetworkChecks) {
-      const networkOptions: NetworkValidationOptions = {
-        timeoutMs: options.timeoutMs,
-        cacheTtlMs: options.cacheTtlMs,
-      };
-      const networkIssues = await validateNetwork(ucpProfile, networkOptions);
-      issues.push(...networkIssues);
-    }
-  }
-
-  return buildReport(issues, mode, undefined, ucpProfile);
-}
-
-/**
- * Validate a remote UCP profile (fetches from domain)
- */
-export async function validateRemote(
-  domain: string,
-  options: ValidationOptions = {}
-): Promise<ValidationReport> {
-  const issues: ValidationIssue[] = [];
-
-  // Fetch remote profile
-  const { profile, profileUrl: foundProfileUrl, issues: fetchIssues } = await validateRemoteProfile(domain, {
-    timeoutMs: options.timeoutMs,
-    cacheTtlMs: options.cacheTtlMs,
-  });
-  issues.push(...fetchIssues);
-
-  const profileUrl = foundProfileUrl || `https://${domain}/.well-known/ucp`;
-
-  if (!profile) {
-    return buildReport(issues, 'network', profileUrl, undefined);
-  }
-
-  // Run full validation on fetched profile
-  const validationResult = await validateProfile(profile, options);
-  issues.push(...validationResult.issues);
-
-  return buildReport(issues, options.mode || 'full', profileUrl, profile);
-}
-
-/**
- * Build validation report
- */
-function buildReport(
-  issues: ValidationIssue[],
-  mode: ValidationMode,
-  profileUrl?: string,
-  profile?: unknown
-): ValidationReport {
-  // Determine if validation passed (no errors)
-  const hasErrors = issues.some(i => i.severity === 'error');
-
-  // Extract UCP version if available
-  let ucpVersion: string | undefined;
-  if (profile && typeof profile === 'object') {
-    const p = profile as Record<string, unknown>;
-    if (p.ucp && typeof p.ucp === 'object') {
-      const ucp = p.ucp as Record<string, unknown>;
-      if (typeof ucp.version === 'string') {
-        ucpVersion = ucp.version;
-      }
-    }
-  }
-
-  // Run SDK validation for compliance check
-  const sdkCompliant = profile ? isSdkCompliant(profile) : false;
-
-  return {
-    ok: !hasErrors,
-    profile_url: profileUrl,
-    ucp_version: ucpVersion,
-    issues,
-    validated_at: new Date().toISOString(),
-    validation_mode: mode,
-    sdk_validation: {
-      validated: true,
-      sdk_version: getSdkVersion(),
-      compliant: sdkCompliant,
-    },
-  };
-}
-
-/**
- * Quick validation (structural + rules only, no network)
- */
-export function validateQuick(profile: unknown): ValidationReport {
-  const issues: ValidationIssue[] = [];
-
-  // Structural validation
-  const structuralIssues = validateStructure(profile);
-  issues.push(...structuralIssues);
-
-  // If structural is OK, run rules validation
-  const hasStructuralErrors = structuralIssues.some(i => i.severity === 'error');
-  if (!hasStructuralErrors) {
-    const rulesIssues = validateRules(profile as UcpProfile);
-    issues.push(...rulesIssues);
-  }
-
-  return buildReport(issues, 'rules', undefined, profile);
-}
-
-/**
- * Parse and validate JSON string
- */
-export async function validateJsonString(
-  json: string,
-  options: ValidationOptions = {}
-): Promise<ValidationReport> {
-  try {
-    const profile = JSON.parse(json);
-    return validateProfile(profile, options);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : 'Invalid JSON';
-    return {
-      ok: false,
-      issues: [{
-        severity: 'error',
-        code: 'UCP_MISSING_ROOT' as const,
-        path: '$',
-        message: `Failed to parse JSON: ${message}`,
-        hint: 'Ensure the input is valid JSON',
-      }],
-      validated_at: new Date().toISOString(),
-      validation_mode: options.mode || 'full',
-    };
-  }
-}

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();
-}