@ucptools/validator 1.0.0 → 1.1.0

package/src/types/generator.ts

@@ -1,140 +0,0 @@
-/**
- * Generator Types for UCP Profile Generator
- */
-
-import type { Environment, ProfileStatus } from './ucp-profile.js';
-
-// Merchant information
-export interface MerchantInfo {
-  merchantId: string;
-  primaryDomain: string;
-  displayName?: string;
-  environment?: Environment;
-}
-
-// Transport configuration inputs
-export interface TransportConfig {
-  rest?: {
-    endpoint: string;
-    schemaUrl?: string;  // Override default
-  };
-  mcp?: {
-    endpoint: string;
-    schemaUrl?: string;
-  };
-  a2a?: {
-    agentCardUrl: string;
-  };
-  embedded?: {
-    schemaUrl: string;
-  };
-}
-
-// Capability selection (based on official UCP spec)
-export interface CapabilitySelection {
-  checkout: boolean;      // Default: true
-  order: boolean;         // Requires signing keys
-  fulfillment: boolean;   // Extension of order
-  discount: boolean;      // Extension
-  payment?: boolean;      // Payment capability
-  buyerConsent?: boolean; // Buyer consent capability
-  customCapabilities?: CustomCapability[];
-}
-
-// Custom/vendor capability
-export interface CustomCapability {
-  namespace: string;      // e.g., "com.myvendor"
-  name: string;           // e.g., "custom-feature"
-  version: string;
-  specUrl: string;
-  schemaUrl: string;
-  extendsCapability?: string;
-}
-
-// Security configuration
-export interface SecurityConfig {
-  generateSigningKeys: boolean;
-  signingKeyAlgorithm?: 'ES256' | 'RS256';
-  uploadedPublicKey?: string;  // PEM or JWK format
-}
-
-// Complete generator input
-export interface GeneratorInput {
-  merchant: MerchantInfo;
-  transport: TransportConfig;
-  capabilities: CapabilitySelection;
-  security?: SecurityConfig;
-  ucpVersion?: string;    // Override default version
-}
-
-// Generator output artifacts
-export interface GeneratorOutput {
-  profile: object;                    // The UCP profile JSON
-  profileJson: string;                // Formatted JSON string
-  installInstructions: string;        // Markdown instructions
-  validationReport?: object;          // Initial validation
-  signingKeyPair?: {                  // If keys were generated
-    publicKey: object;                // JWK public key
-    privateKey: string;               // PEM private key (for merchant to store securely)
-  };
-}
-
-// Hosting mode options
-export type HostingMode = 'static' | 'edge-worker' | 'reverse-proxy';
-
-// Hosting target platforms
-export type HostingPlatform =
-  | 'nginx'
-  | 'apache'
-  | 'vercel'
-  | 'netlify'
-  | 'cloudflare-worker'
-  | 'cloudflare-pages'
-  | 's3-cloudfront'
-  | 'generic';
-
-// Hosting configuration
-export interface HostingConfig {
-  mode: HostingMode;
-  platform?: HostingPlatform;
-  merchantId: string;
-  merchantDomain: string;
-  hostedProfileUrl?: string;  // For edge/proxy modes
-}
-
-// Install artifact
-export interface InstallArtifact {
-  filename: string;
-  content: string;
-  contentType: 'json' | 'javascript' | 'nginx' | 'apache' | 'markdown';
-  description: string;
-}
-
-// Database models (for API service)
-export interface MerchantRecord {
-  id: string;
-  primaryDomain: string;
-  displayName?: string;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-export interface ProfileRecord {
-  id: string;
-  merchantId: string;
-  versionTag: string;
-  ucpVersion: string;
-  jsonBody: object;
-  status: ProfileStatus;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-export interface ValidationRunRecord {
-  id: string;
-  profileId: string;
-  mode: 'draft' | 'remote';
-  result: object;
-  ok: boolean;
-  createdAt: Date;
-}

package/src/types/ucp-profile.ts

@@ -1,140 +0,0 @@
-/**
- * UCP (Universal Commerce Protocol) Profile Types
- * Based on https://ucp.dev/specification/overview/
- */
-
-// Current UCP version
-export const CURRENT_UCP_VERSION = '2026-01-11';
-
-// Transport binding types
-export interface RestTransport {
-  schema: string;  // OpenAPI schema URL
-  endpoint: string; // REST API endpoint (https, no trailing slash)
-}
-
-export interface McpTransport {
-  schema: string;  // MCP schema URL
-  endpoint: string; // MCP endpoint URL
-}
-
-export interface A2aTransport {
-  agentCard: string; // A2A agent card URL
-}
-
-export interface EmbeddedTransport {
-  schema: string;  // Embedded schema URL
-}
-
-// Service definition with transport bindings
-export interface UcpService {
-  version: string;
-  spec: string;
-  rest?: RestTransport;
-  mcp?: McpTransport;
-  a2a?: A2aTransport;
-  embedded?: EmbeddedTransport;
-}
-
-// Capability definition
-export interface UcpCapability {
-  name: string;        // e.g., "dev.ucp.shopping.checkout"
-  version: string;     // e.g., "2026-01-11"
-  spec: string;        // Specification URL
-  schema: string;      // JSON Schema URL
-  extends?: string;    // Parent capability for extensions
-  config?: Record<string, unknown>; // Capability-specific settings
-}
-
-// JWK (JSON Web Key) for signing
-export interface JwkKey {
-  kty: string;         // Key type (e.g., "EC", "RSA")
-  kid: string;         // Key ID
-  use?: string;        // Key use (e.g., "sig")
-  alg?: string;        // Algorithm (e.g., "ES256")
-  crv?: string;        // Curve (for EC keys)
-  x?: string;          // X coordinate (for EC keys)
-  y?: string;          // Y coordinate (for EC keys)
-  n?: string;          // Modulus (for RSA keys)
-  e?: string;          // Exponent (for RSA keys)
-}
-
-// Signing keys - array of JWK public keys at root level
-export type SigningKeys = JwkKey[];
-
-// Payment handler definition
-export interface PaymentHandler {
-  id: string;           // Handler identifier
-  name: string;         // Display name
-  version: string;      // Handler version (YYYY-MM-DD)
-  spec: string;         // Handler specification URL
-  config_schema?: string;        // Configuration schema URL
-  instrument_schemas?: string[]; // Payment instrument schemas
-  config?: Record<string, unknown>; // Handler-specific config
-}
-
-// Payment configuration
-export interface PaymentConfig {
-  handlers: PaymentHandler[];
-}
-
-// Main UCP object within profile
-export interface UcpObject {
-  version: string;
-  services: Record<string, UcpService>;
-  capabilities: UcpCapability[];
-}
-
-// Complete UCP Business Profile (/.well-known/ucp)
-export interface UcpProfile {
-  ucp: UcpObject;
-  payment?: PaymentConfig;       // Payment handlers configuration
-  signing_keys?: SigningKeys;    // JWK public keys for webhook verification
-  // Additional vendor extensions can be added as siblings
-  [key: string]: unknown;
-}
-
-// Known capability namespaces
-export const CAPABILITY_NAMESPACES = {
-  UCP_OFFICIAL: 'dev.ucp.',
-  VENDOR_PREFIX: 'com.',
-} as const;
-
-// Known UCP capabilities (from official spec)
-export const KNOWN_CAPABILITIES = {
-  CHECKOUT: 'dev.ucp.shopping.checkout',
-  ORDER: 'dev.ucp.shopping.order',
-  PAYMENT: 'dev.ucp.shopping.payment',
-  PAYMENT_DATA: 'dev.ucp.shopping.payment_data',
-  FULFILLMENT: 'dev.ucp.shopping.fulfillment',
-  DISCOUNT: 'dev.ucp.shopping.discount',
-  BUYER_CONSENT: 'dev.ucp.shopping.buyer_consent',
-} as const;
-
-// Known UCP services
-export const KNOWN_SERVICES = {
-  SHOPPING: 'dev.ucp.shopping',
-} as const;
-
-// Default URLs for UCP official resources
-export const UCP_DEFAULTS = {
-  SPEC_BASE: 'https://ucp.dev/specification/',
-  SCHEMA_BASE: 'https://ucp.dev/schemas/',
-  SERVICE_SCHEMA_BASE: 'https://ucp.dev/services/',
-
-  // Default schema URLs
-  SHOPPING_REST_SCHEMA: 'https://ucp.dev/services/shopping/rest.openapi.json',
-  CHECKOUT_SPEC: 'https://ucp.dev/specification/checkout/',
-  CHECKOUT_SCHEMA: 'https://ucp.dev/schemas/shopping/checkout.json',
-  ORDER_SPEC: 'https://ucp.dev/specification/order/',
-  ORDER_SCHEMA: 'https://ucp.dev/schemas/shopping/order.json',
-  FULFILLMENT_SPEC: 'https://ucp.dev/specification/fulfillment/',
-  FULFILLMENT_SCHEMA: 'https://ucp.dev/schemas/shopping/fulfillment.json',
-  DISCOUNT_SPEC: 'https://ucp.dev/specification/discount/',
-  DISCOUNT_SCHEMA: 'https://ucp.dev/schemas/shopping/discount.json',
-} as const;
-
-// Environment types
-export type Environment = 'production' | 'staging' | 'development';
-
-// Profile status
-export type ProfileStatus = 'draft' | 'published';

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',
-    };
-  }
-}