@ucptools/validator 1.0.0

package/src/validator/structural-validator.ts

@@ -0,0 +1,476 @@
+/**
+ * Structural Validator
+ * Validates UCP Profile JSON structure (no network calls)
+ */
+
+import type { UcpProfile, UcpService, UcpCapability } from '../types/ucp-profile.js';
+import type { ValidationIssue } from '../types/validation.js';
+import { ValidationErrorCodes } from '../types/validation.js';
+
+/**
+ * Version format regex (YYYY-MM-DD)
+ */
+const VERSION_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Validate the structural integrity of a UCP profile
+ * Returns an array of validation issues
+ */
+export function validateStructure(profile: unknown): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Check if it's an object
+  if (!profile || typeof profile !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.MISSING_UCP_OBJECT,
+      path: '$',
+      message: 'Profile must be a JSON object',
+      hint: 'Ensure your profile is valid JSON and contains a root object',
+    });
+    return issues;
+  }
+
+  const profileObj = profile as Record<string, unknown>;
+
+  // Check for ucp root object
+  if (!profileObj.ucp || typeof profileObj.ucp !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.MISSING_UCP_OBJECT,
+      path: '$.ucp',
+      message: 'Missing required "ucp" object at root level',
+      hint: 'Add a "ucp" object containing version, services, and capabilities',
+    });
+    return issues;
+  }
+
+  const ucp = profileObj.ucp as Record<string, unknown>;
+
+  // Validate version
+  issues.push(...validateVersion(ucp));
+
+  // Validate services
+  issues.push(...validateServices(ucp));
+
+  // Validate capabilities
+  issues.push(...validateCapabilities(ucp));
+
+  // Validate signing_keys if present
+  if (profileObj.signing_keys !== undefined) {
+    issues.push(...validateSigningKeys(profileObj.signing_keys));
+  }
+
+  return issues;
+}
+
+/**
+ * Validate UCP version field
+ */
+function validateVersion(ucp: Record<string, unknown>): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!ucp.version) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.MISSING_VERSION,
+      path: '$.ucp.version',
+      message: 'Missing required "version" field in ucp object',
+      hint: 'Add version field with format "YYYY-MM-DD" (e.g., "2026-01-11")',
+    });
+  } else if (typeof ucp.version !== 'string') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_VERSION_FORMAT,
+      path: '$.ucp.version',
+      message: 'Version must be a string',
+      hint: 'Use format "YYYY-MM-DD" (e.g., "2026-01-11")',
+    });
+  } else if (!VERSION_REGEX.test(ucp.version)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_VERSION_FORMAT,
+      path: '$.ucp.version',
+      message: `Invalid version format: "${ucp.version}"`,
+      hint: 'Use format "YYYY-MM-DD" (e.g., "2026-01-11")',
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Validate services object
+ */
+function validateServices(ucp: Record<string, unknown>): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!ucp.services) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.MISSING_SERVICES,
+      path: '$.ucp.services',
+      message: 'Missing required "services" field in ucp object',
+      hint: 'Add a services object with at least one service definition',
+    });
+    return issues;
+  }
+
+  if (typeof ucp.services !== 'object' || Array.isArray(ucp.services)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: '$.ucp.services',
+      message: 'Services must be an object (not an array)',
+      hint: 'Use format: { "dev.ucp.shopping": { ... } }',
+    });
+    return issues;
+  }
+
+  const services = ucp.services as Record<string, unknown>;
+
+  // Check for at least one service
+  if (Object.keys(services).length === 0) {
+    issues.push({
+      severity: 'warn',
+      code: ValidationErrorCodes.MISSING_SERVICES,
+      path: '$.ucp.services',
+      message: 'Services object is empty',
+      hint: 'Add at least one service (e.g., "dev.ucp.shopping")',
+    });
+  }
+
+  // Validate each service
+  for (const [serviceName, service] of Object.entries(services)) {
+    issues.push(...validateService(serviceName, service));
+  }
+
+  return issues;
+}
+
+/**
+ * Validate individual service definition
+ */
+function validateService(name: string, service: unknown): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const path = `$.ucp.services["${name}"]`;
+
+  if (!service || typeof service !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path,
+      message: `Service "${name}" must be an object`,
+    });
+    return issues;
+  }
+
+  const svc = service as Record<string, unknown>;
+
+  // Check required version
+  if (!svc.version) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.version`,
+      message: `Service "${name}" missing required "version" field`,
+    });
+  } else if (typeof svc.version === 'string' && !VERSION_REGEX.test(svc.version)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_VERSION_FORMAT,
+      path: `${path}.version`,
+      message: `Invalid version format in service "${name}"`,
+      hint: 'Use format "YYYY-MM-DD"',
+    });
+  }
+
+  // Check required spec
+  if (!svc.spec) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.spec`,
+      message: `Service "${name}" missing required "spec" field`,
+    });
+  }
+
+  // Check for at least one transport
+  const hasTransport = svc.rest || svc.mcp || svc.a2a || svc.embedded;
+  if (!hasTransport) {
+    issues.push({
+      severity: 'warn',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path,
+      message: `Service "${name}" has no transport bindings`,
+      hint: 'Add at least one transport: rest, mcp, a2a, or embedded',
+    });
+  }
+
+  // Validate REST transport if present
+  if (svc.rest) {
+    issues.push(...validateRestTransport(svc.rest, `${path}.rest`));
+  }
+
+  // Validate MCP transport if present
+  if (svc.mcp) {
+    issues.push(...validateMcpTransport(svc.mcp, `${path}.mcp`));
+  }
+
+  return issues;
+}
+
+/**
+ * Validate REST transport binding
+ */
+function validateRestTransport(transport: unknown, path: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!transport || typeof transport !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path,
+      message: 'REST transport must be an object',
+    });
+    return issues;
+  }
+
+  const rest = transport as Record<string, unknown>;
+
+  if (!rest.schema) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.schema`,
+      message: 'REST transport missing required "schema" field',
+    });
+  }
+
+  if (!rest.endpoint) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.endpoint`,
+      message: 'REST transport missing required "endpoint" field',
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Validate MCP transport binding
+ */
+function validateMcpTransport(transport: unknown, path: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!transport || typeof transport !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path,
+      message: 'MCP transport must be an object',
+    });
+    return issues;
+  }
+
+  const mcp = transport as Record<string, unknown>;
+
+  if (!mcp.schema) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.schema`,
+      message: 'MCP transport missing required "schema" field',
+    });
+  }
+
+  if (!mcp.endpoint) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SERVICE_STRUCTURE,
+      path: `${path}.endpoint`,
+      message: 'MCP transport missing required "endpoint" field',
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Validate capabilities array
+ */
+function validateCapabilities(ucp: Record<string, unknown>): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!ucp.capabilities) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.MISSING_CAPABILITIES,
+      path: '$.ucp.capabilities',
+      message: 'Missing required "capabilities" field in ucp object',
+      hint: 'Add a capabilities array with at least one capability',
+    });
+    return issues;
+  }
+
+  if (!Array.isArray(ucp.capabilities)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path: '$.ucp.capabilities',
+      message: 'Capabilities must be an array',
+    });
+    return issues;
+  }
+
+  if (ucp.capabilities.length === 0) {
+    issues.push({
+      severity: 'warn',
+      code: ValidationErrorCodes.MISSING_CAPABILITIES,
+      path: '$.ucp.capabilities',
+      message: 'Capabilities array is empty',
+      hint: 'Add at least one capability (e.g., dev.ucp.shopping.checkout)',
+    });
+  }
+
+  // Validate each capability
+  for (let i = 0; i < ucp.capabilities.length; i++) {
+    issues.push(...validateCapability(ucp.capabilities[i], i));
+  }
+
+  return issues;
+}
+
+/**
+ * Validate individual capability
+ */
+function validateCapability(capability: unknown, index: number): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const path = `$.ucp.capabilities[${index}]`;
+
+  if (!capability || typeof capability !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path,
+      message: `Capability at index ${index} must be an object`,
+    });
+    return issues;
+  }
+
+  const cap = capability as Record<string, unknown>;
+
+  // Check required fields
+  if (!cap.name) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path: `${path}.name`,
+      message: 'Capability missing required "name" field',
+    });
+  }
+
+  if (!cap.version) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path: `${path}.version`,
+      message: 'Capability missing required "version" field',
+    });
+  } else if (typeof cap.version === 'string' && !VERSION_REGEX.test(cap.version)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_VERSION_FORMAT,
+      path: `${path}.version`,
+      message: `Invalid version format: "${cap.version}"`,
+      hint: 'Use format "YYYY-MM-DD"',
+    });
+  }
+
+  if (!cap.spec) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path: `${path}.spec`,
+      message: 'Capability missing required "spec" field',
+    });
+  }
+
+  if (!cap.schema) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_CAPABILITY_STRUCTURE,
+      path: `${path}.schema`,
+      message: 'Capability missing required "schema" field',
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Validate signing_keys structure
+ * Accepts signing_keys as a direct array of JWKs (official UCP format)
+ */
+function validateSigningKeys(signingKeys: unknown): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const path = '$.signing_keys';
+
+  // signing_keys should be an array of JWKs
+  if (!Array.isArray(signingKeys)) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SIGNING_KEY,
+      path,
+      message: 'signing_keys must be an array of JWK objects',
+    });
+    return issues;
+  }
+
+  for (let i = 0; i < signingKeys.length; i++) {
+    issues.push(...validateJwk(signingKeys[i], `${path}[${i}]`));
+  }
+
+  return issues;
+}
+
+/**
+ * Validate JWK structure
+ */
+function validateJwk(jwk: unknown, path: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  if (!jwk || typeof jwk !== 'object') {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SIGNING_KEY,
+      path,
+      message: 'JWK must be an object',
+    });
+    return issues;
+  }
+
+  const key = jwk as Record<string, unknown>;
+
+  if (!key.kty) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SIGNING_KEY,
+      path: `${path}.kty`,
+      message: 'JWK missing required "kty" field',
+    });
+  }
+
+  if (!key.kid) {
+    issues.push({
+      severity: 'error',
+      code: ValidationErrorCodes.INVALID_SIGNING_KEY,
+      path: `${path}.kid`,
+      message: 'JWK missing required "kid" field',
+    });
+  }
+
+  return issues;
+}

package/tests/fixtures/non-compliant-profile.json

@@ -0,0 +1,25 @@
+{
+  "ucp": {
+    "version": "1.0",
+    "services": {
+      "checkout": "/api/ucp/checkout",
+      "orders": "/api/ucp/orders",
+      "products": "/api/ucp/products"
+    },
+    "capabilities": [
+      "dev.ucp.shopping.checkout",
+      "dev.ucp.shopping.catalog",
+      "dev.ucp.shopping.fulfillment"
+    ],
+    "merchant": {
+      "name": "Test Merchant",
+      "description": "A non-compliant but working UCP profile",
+      "website": "https://example.com"
+    },
+    "sandbox": true
+  },
+  "payment": {
+    "sandbox_mode": true,
+    "accepted_tokens": ["sandbox_*", "test"]
+  }
+}

package/tests/fixtures/official-sample-profile.json

@@ -0,0 +1,75 @@
+{
+  "ucp": {
+    "version": "2026-01-11",
+    "services": {
+      "dev.ucp.shopping": {
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping",
+        "rest": {
+          "schema": "https://ucp.dev/services/shopping/openapi.json",
+          "endpoint": "https://example.com/api"
+        }
+      }
+    },
+    "capabilities": [
+      {
+        "name": "dev.ucp.shopping.checkout",
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping/checkout",
+        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
+      },
+      {
+        "name": "dev.ucp.shopping.order",
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping/order",
+        "schema": "https://ucp.dev/schemas/shopping/order.json",
+        "extends": "dev.ucp.shopping.checkout"
+      },
+      {
+        "name": "dev.ucp.shopping.fulfillment",
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping/fulfillment",
+        "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
+        "extends": "dev.ucp.shopping.order"
+      },
+      {
+        "name": "dev.ucp.shopping.discount",
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping/discount",
+        "schema": "https://ucp.dev/schemas/shopping/discount.json",
+        "extends": "dev.ucp.shopping.checkout"
+      },
+      {
+        "name": "dev.ucp.shopping.buyer_consent",
+        "version": "2026-01-11",
+        "spec": "https://ucp.dev/specs/shopping/buyer_consent",
+        "schema": "https://ucp.dev/schemas/shopping/buyer_consent.json",
+        "extends": "dev.ucp.shopping.checkout"
+      }
+    ]
+  },
+  "signing_keys": [
+    {
+      "kty": "EC",
+      "crv": "P-256",
+      "x": "test-x-coordinate",
+      "y": "test-y-coordinate",
+      "kid": "key-2026-01"
+    }
+  ],
+  "payment": {
+    "handlers": [
+      {
+        "id": "mock_payment",
+        "name": "com.example.mock_payment",
+        "version": "2026-01-11",
+        "spec": "https://example.com/payment/spec",
+        "config_schema": "https://example.com/payment/config.json",
+        "instrument_schemas": ["https://example.com/payment/instrument.json"],
+        "config": {
+          "mode": "sandbox"
+        }
+      }
+    ]
+  }
+}