@onlineapps/service-validator-core 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/service-validator-core",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Core validation logic for microservices",
   "main": "src/index.js",
   "scripts": {

package/src/index.js

@@ -5,6 +5,8 @@ const HealthValidator = require('./validators/healthValidator');
 const TokenManager = require('./security/tokenManager');
 const CertificateManager = require('./security/certificateManager');
 const ValidationProofVerifier = require('./security/ValidationProofVerifier');
+const ValidationProofCodec = require('./security/ValidationProofCodec');
+const ValidationProofSchema = require('./types/ValidationProofSchema');
 
 class ValidationCore {
   constructor(config = {}) {
@@ -209,4 +211,6 @@ class ValidationCore {
 }
 
 module.exports = ValidationCore;
-module.exports.ValidationProofVerifier = ValidationProofVerifier;
+module.exports.ValidationProofVerifier = ValidationProofVerifier;
+module.exports.ValidationProofCodec = ValidationProofCodec;
+module.exports.ValidationProofSchema = ValidationProofSchema;

package/src/security/ValidationProofCodec.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const crypto = require('crypto');
+const ValidationProofSchema = require('../types/ValidationProofSchema');
+
+/**
+ * ValidationProofCodec - Centralized encode/decode for validation proofs
+ *
+ * Single source of truth for encoding and decoding validation proofs.
+ * Both Generator and Verifier MUST use this codec to ensure consistency.
+ *
+ * Key principles:
+ * - Encoding and decoding use EXACTLY the same algorithm
+ * - Hash is SHA256 of JSON.stringify(data, sorted keys)
+ * - Data structure is validated against ValidationProofSchema
+ */
+class ValidationProofCodec {
+  /**
+   * Encode validation data into hash proof
+   *
+   * @param {Object} validationData - Validation data to encode
+   * @returns {Object} { validationProof: string, validationData: Object }
+   * @throws {Error} If validation data doesn't match schema
+   */
+  static encode(validationData) {
+    // 1. Validate data structure
+    const validation = ValidationProofSchema.validate(validationData);
+    if (!validation.valid) {
+      const errorDetails = validation.errors.map(e => `  - ${e.field}: ${e.message}`).join('\n');
+      throw new Error(`Invalid validation data structure:\n${errorDetails}`);
+    }
+
+    // 2. Generate hash
+    const hash = this._generateHash(validationData);
+
+    // 3. Return proof object
+    return {
+      validationProof: hash,
+      validationData: validationData
+    };
+  }
+
+  /**
+   * Decode and verify validation proof
+   *
+   * @param {Object} proof - Proof object { validationProof, validationData }
+   * @param {Object} options - Verification options
+   * @param {number} options.maxProofAge - Maximum proof age in milliseconds (default 7 days)
+   * @returns {Object} Verification result { valid, reason, details, data }
+   */
+  static decode(proof, options = {}) {
+    const maxProofAge = options.maxProofAge || 7 * 24 * 60 * 60 * 1000; // 7 days
+
+    // 1. Check proof structure
+    if (!proof || typeof proof !== 'object') {
+      return this._error('INVALID_STRUCTURE', 'Proof must be an object');
+    }
+
+    if (!proof.validationProof || typeof proof.validationProof !== 'string') {
+      return this._error('MISSING_HASH', 'validationProof field is required');
+    }
+
+    if (!proof.validationData || typeof proof.validationData !== 'object') {
+      return this._error('MISSING_DATA', 'validationData field is required');
+    }
+
+    // 2. Check hash format (SHA256 = 64 hex characters)
+    if (!/^[a-f0-9]{64}$/i.test(proof.validationProof)) {
+      return this._error('INVALID_HASH_FORMAT', 'Hash must be 64-character hex string (SHA256)');
+    }
+
+    // 3. Validate data structure against schema
+    const data = proof.validationData;
+    const schemaValidation = ValidationProofSchema.validate(data);
+    if (!schemaValidation.valid) {
+      const errorDetails = schemaValidation.errors.map(e => `${e.field}: ${e.message}`).join('; ');
+      return this._error('SCHEMA_VALIDATION_FAILED', errorDetails);
+    }
+
+    // 4. Verify hash integrity
+    const recomputedHash = this._generateHash(data);
+    if (recomputedHash !== proof.validationProof) {
+      return this._error('HASH_MISMATCH',
+        'Validation data does not match hash (data may have been tampered with)',
+        { expected: proof.validationProof, computed: recomputedHash }
+      );
+    }
+
+    // 5. Check proof age
+    const proofDate = new Date(data.validatedAt);
+    const now = new Date();
+    const age = now - proofDate;
+
+    if (age > maxProofAge) {
+      const maxDays = Math.floor(maxProofAge / (24 * 60 * 60 * 1000));
+      const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
+      return this._error('PROOF_EXPIRED', `Proof is ${ageDays} days old (max ${maxDays} days)`);
+    }
+
+    // 6. Check test results
+    if (data.testsRun <= 0) {
+      return this._error('NO_TESTS', 'At least one test must be run');
+    }
+
+    if (data.testsFailed > 0) {
+      return this._error('TESTS_FAILED', `${data.testsFailed} out of ${data.testsRun} tests failed`);
+    }
+
+    if (data.testsPassed !== data.testsRun) {
+      return this._error('TEST_COUNT_MISMATCH',
+        `Passed (${data.testsPassed}) + Failed (${data.testsFailed}) ≠ Total (${data.testsRun})`
+      );
+    }
+
+    // 7. All checks passed
+    return {
+      valid: true,
+      reason: 'VALID',
+      details: {
+        serviceName: data.serviceName,
+        version: data.version,
+        testsRun: data.testsRun,
+        testsPassed: data.testsPassed,
+        validator: data.validator,
+        validatedAt: data.validatedAt,
+        durationMs: data.durationMs
+      },
+      data: data
+    };
+  }
+
+  /**
+   * Generate SHA256 hash from validation data
+   *
+   * CRITICAL: This algorithm MUST be identical in encode() and decode()
+   *
+   * @private
+   * @param {Object} data - Validation data
+   * @returns {string} SHA256 hash (64 hex characters)
+   */
+  static _generateHash(data) {
+    // Stringify with SORTED keys to ensure deterministic output
+    const hashInput = JSON.stringify(data, Object.keys(data).sort());
+    return crypto.createHash('sha256').update(hashInput).digest('hex');
+  }
+
+  /**
+   * Create error result object
+   * @private
+   */
+  static _error(reason, message, details = null) {
+    return {
+      valid: false,
+      reason,
+      details: details || message
+    };
+  }
+
+  /**
+   * Verify that encode/decode are symmetric (for testing)
+   *
+   * @param {Object} validationData - Test data
+   * @returns {boolean} True if encode->decode returns valid
+   */
+  static testSymmetry(validationData) {
+    try {
+      const encoded = this.encode(validationData);
+      const decoded = this.decode(encoded);
+      return decoded.valid;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+module.exports = ValidationProofCodec;

package/src/security/ValidationProofVerifier.js

@@ -1,15 +1,10 @@
-const crypto = require('crypto');
+const ValidationProofCodec = require('./ValidationProofCodec');
 
 /**
  * ValidationProofVerifier - Verifies SHA256 validation proofs from pre-validation
  *
- * This class verifies validation proofs generated by ValidationProofGenerator
- * from the conn-e2e-testing package. It validates:
- * - Hash integrity (SHA256)
- * - Proof structure and format
- * - Test results (passed/failed counts)
- * - Proof age (max 7 days)
- * - Validator identity
+ * This is now a THIN WRAPPER around ValidationProofCodec.
+ * All decoding and verification logic is delegated to the centralized codec.
  */
 class ValidationProofVerifier {
   constructor(options = {}) {
@@ -26,143 +21,24 @@ class ValidationProofVerifier {
     console.log('[ValidationProofVerifier] Starting proof verification');
     console.log('[ValidationProofVerifier] Proof hash:', proof.validationProof?.substring(0, 16) + '...');
 
-    // 1. Check proof structure
-    if (!proof || typeof proof !== 'object') {
-      console.error('[ValidationProofVerifier] ❌ Invalid proof structure: not an object');
-      return { valid: false, reason: 'INVALID_STRUCTURE', details: 'Proof must be an object' };
-    }
-
-    if (!proof.validationProof || typeof proof.validationProof !== 'string') {
-      console.error('[ValidationProofVerifier] ❌ Missing or invalid validationProof field');
-      return { valid: false, reason: 'MISSING_HASH', details: 'validationProof field is required' };
-    }
-
-    if (!proof.validationData || typeof proof.validationData !== 'object') {
-      console.error('[ValidationProofVerifier] ❌ Missing or invalid validationData field');
-      return { valid: false, reason: 'MISSING_DATA', details: 'validationData field is required' };
-    }
-
-    // 2. Check hash format (SHA256 = 64 hex characters)
-    if (!/^[a-f0-9]{64}$/i.test(proof.validationProof)) {
-      console.error('[ValidationProofVerifier] ❌ Invalid hash format:', proof.validationProof);
-      return { valid: false, reason: 'INVALID_HASH_FORMAT', details: 'Hash must be 64-character hex string (SHA256)' };
-    }
-    console.log('[ValidationProofVerifier] ✓ Hash format valid (SHA256)');
-
-    // 3. Verify hash integrity
-    const data = proof.validationData;
-    const recomputedHash = this._generateHash(data);
-
-    if (recomputedHash !== proof.validationProof) {
-      console.error('[ValidationProofVerifier] ❌ Hash mismatch');
-      console.error('[ValidationProofVerifier]   Expected:', proof.validationProof);
-      console.error('[ValidationProofVerifier]   Computed:', recomputedHash);
-      return {
-        valid: false,
-        reason: 'HASH_MISMATCH',
-        details: 'Validation data does not match hash (data may have been tampered with)'
-      };
-    }
-    console.log('[ValidationProofVerifier] ✓ Hash integrity verified');
-
-    // 4. Check required validationData fields
-    const requiredFields = ['serviceName', 'version', 'testsRun', 'testsPassed', 'testsFailed', 'validator', 'validatedAt'];
-    for (const field of requiredFields) {
-      if (data[field] === undefined || data[field] === null) {
-        console.error(`[ValidationProofVerifier] ❌ Missing required field: ${field}`);
-        return {
-          valid: false,
-          reason: 'MISSING_FIELD',
-          details: `Required field missing: ${field}`
-        };
-      }
-    }
-    console.log('[ValidationProofVerifier] ✓ All required fields present');
-
-    // 5. Check proof age
-    const proofDate = new Date(data.validatedAt);
-    const now = new Date();
-    const age = now - proofDate;
-
-    if (isNaN(proofDate.getTime())) {
-      console.error('[ValidationProofVerifier] ❌ Invalid timestamp:', data.timestamp);
-      return { valid: false, reason: 'INVALID_TIMESTAMP', details: 'Timestamp is not a valid date' };
-    }
-
-    if (age > this.maxProofAge) {
-      const maxDays = Math.floor(this.maxProofAge / (24 * 60 * 60 * 1000));
-      const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
-      console.error(`[ValidationProofVerifier] ❌ Proof too old: ${ageDays} days (max ${maxDays} days)`);
-      return {
-        valid: false,
-        reason: 'PROOF_EXPIRED',
-        details: `Proof is ${ageDays} days old (max ${maxDays} days)`
-      };
-    }
-    console.log(`[ValidationProofVerifier] ✓ Proof age valid: ${Math.floor(age / (60 * 60 * 1000))} hours old`);
-
-    // 6. Check test results
-    if (data.testsRun <= 0) {
-      console.error('[ValidationProofVerifier] ❌ No tests were run');
-      return { valid: false, reason: 'NO_TESTS', details: 'At least one test must be run' };
-    }
-
-    if (data.testsFailed > 0) {
-      console.error(`[ValidationProofVerifier] ❌ Some tests failed: ${data.testsFailed}/${data.testsRun}`);
-      return {
-        valid: false,
-        reason: 'TESTS_FAILED',
-        details: `${data.testsFailed} out of ${data.testsRun} tests failed`
-      };
-    }
+    // Delegate verification to centralized codec
+    const result = ValidationProofCodec.decode(proof, {
+      maxProofAge: this.maxProofAge
+    });
 
-    if (data.testsPassed !== data.testsRun) {
-      console.error('[ValidationProofVerifier] ❌ Test count mismatch');
-      return {
-        valid: false,
-        reason: 'TEST_COUNT_MISMATCH',
-        details: `Passed (${data.testsPassed}) + Failed (${data.testsFailed}) ≠ Total (${data.testsRun})`
-      };
+    // Log results
+    if (result.valid) {
+      console.log('[ValidationProofVerifier] ✅ Proof verification successful');
+      console.log(`[ValidationProofVerifier]   Service: ${result.details.serviceName} v${result.details.version}`);
+      console.log(`[ValidationProofVerifier]   Tests: ${result.details.testsPassed}/${result.details.testsRun} passed`);
+      console.log(`[ValidationProofVerifier]   Validator: ${result.details.validator}`);
+      console.log(`[ValidationProofVerifier]   Timestamp: ${result.details.validatedAt}`);
+    } else {
+      console.error(`[ValidationProofVerifier] ❌ Verification failed: ${result.reason}`);
+      console.error(`[ValidationProofVerifier]   Details: ${JSON.stringify(result.details)}`);
     }
-    console.log(`[ValidationProofVerifier] ✓ All tests passed: ${data.testsPassed}/${data.testsRun}`);
 
-    // 7. Check validator identity
-    if (!data.validator || typeof data.validator !== 'string') {
-      console.error('[ValidationProofVerifier] ❌ Invalid validator identity');
-      return { valid: false, reason: 'INVALID_VALIDATOR', details: 'Validator identity is required' };
-    }
-    console.log('[ValidationProofVerifier] ✓ Validator:', data.validator);
-
-    // 8. All checks passed
-    console.log('[ValidationProofVerifier] ✅ Proof verification successful');
-    console.log(`[ValidationProofVerifier]   Service: ${data.serviceName} v${data.version}`);
-    console.log(`[ValidationProofVerifier]   Tests: ${data.testsPassed}/${data.testsRun} passed`);
-    console.log(`[ValidationProofVerifier]   Validator: ${data.validator}`);
-    console.log(`[ValidationProofVerifier]   Timestamp: ${data.timestamp}`);
-
-    return {
-      valid: true,
-      reason: 'VALID',
-      details: {
-        serviceName: data.serviceName,
-        version: data.version,
-        testsRun: data.testsRun,
-        testsPassed: data.testsPassed,
-        validator: data.validator,
-        timestamp: data.timestamp,
-        fingerprint: data.fingerprint
-      }
-    };
-  }
-
-  /**
-   * Generate SHA256 hash from validation data (must match ValidationProofGenerator)
-   * @private
-   */
-  _generateHash(data) {
-    // Match ValidationProofGenerator algorithm: stringify with sorted keys
-    const hashInput = JSON.stringify(data, Object.keys(data).sort());
-    return crypto.createHash('sha256').update(hashInput).digest('hex');
+    return result;
   }
 }
 

package/src/types/ValidationProofSchema.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * ValidationProofSchema - Single source of truth for validation proof format
+ *
+ * This schema defines the EXACT structure and requirements for validation proofs.
+ * Both Generator and Verifier MUST comply with this specification.
+ *
+ * @specification v1.0.0
+ */
+class ValidationProofSchema {
+  /**
+   * Get validation data schema definition
+   *
+   * @returns {Object} Schema definition with field specifications
+   */
+  static getSchema() {
+    return {
+      // Service identification
+      serviceName: {
+        type: 'string',
+        required: true,
+        description: 'Name of the service being validated',
+        example: 'hello-service'
+      },
+      version: {
+        type: 'string',
+        required: true,
+        description: 'Service version (semver)',
+        example: '1.0.0'
+      },
+
+      // Validator identification
+      validator: {
+        type: 'string',
+        required: true,
+        description: 'Name of the validator that generated the proof',
+        example: '@onlineapps/conn-e2e-testing'
+      },
+      validatorVersion: {
+        type: 'string',
+        required: true,
+        description: 'Validator version',
+        example: '1.0.0'
+      },
+
+      // Timestamp
+      validatedAt: {
+        type: 'string',
+        required: true,
+        format: 'ISO8601',
+        description: 'Timestamp when validation was performed',
+        example: '2025-10-02T10:30:45.123Z'
+      },
+
+      // Test results
+      testsRun: {
+        type: 'number',
+        required: true,
+        min: 0,
+        description: 'Total number of tests executed',
+        example: 42
+      },
+      testsPassed: {
+        type: 'number',
+        required: true,
+        min: 0,
+        description: 'Number of tests that passed',
+        example: 42
+      },
+      testsFailed: {
+        type: 'number',
+        required: true,
+        min: 0,
+        description: 'Number of tests that failed',
+        example: 0
+      },
+
+      // Performance
+      durationMs: {
+        type: 'number',
+        required: true,
+        min: 0,
+        description: 'Test execution duration in milliseconds',
+        example: 1234
+      },
+
+      // Dependencies (optional)
+      dependencies: {
+        type: 'object',
+        required: false,
+        description: 'Service dependencies with versions',
+        example: { 'express': '^4.18.2' }
+      }
+    };
+  }
+
+  /**
+   * Get list of required fields
+   *
+   * @returns {Array<string>} Array of required field names
+   */
+  static getRequiredFields() {
+    const schema = this.getSchema();
+    return Object.entries(schema)
+      .filter(([_, spec]) => spec.required)
+      .map(([field, _]) => field);
+  }
+
+  /**
+   * Get list of all fields in canonical order (for hash generation)
+   *
+   * @returns {Array<string>} Array of field names in alphabetical order
+   */
+  static getFieldsInOrder() {
+    return Object.keys(this.getSchema()).sort();
+  }
+
+  /**
+   * Validate data structure against schema
+   *
+   * @param {Object} data - Data to validate
+   * @returns {Object} Validation result { valid: boolean, errors: Array }
+   */
+  static validate(data) {
+    const errors = [];
+    const schema = this.getSchema();
+
+    // Check all fields
+    for (const [fieldName, fieldSpec] of Object.entries(schema)) {
+      const value = data[fieldName];
+
+      // Required check
+      if (fieldSpec.required && (value === undefined || value === null)) {
+        errors.push({
+          field: fieldName,
+          error: 'MISSING_REQUIRED_FIELD',
+          message: `Required field '${fieldName}' is missing`
+        });
+        continue;
+      }
+
+      // Skip type checking if field is optional and not present
+      if (!fieldSpec.required && (value === undefined || value === null)) {
+        continue;
+      }
+
+      // Type check
+      const actualType = typeof value;
+      if (actualType !== fieldSpec.type) {
+        errors.push({
+          field: fieldName,
+          error: 'INVALID_TYPE',
+          message: `Field '${fieldName}' must be ${fieldSpec.type}, got ${actualType}`
+        });
+        continue;
+      }
+
+      // Number min check
+      if (fieldSpec.type === 'number' && fieldSpec.min !== undefined && value < fieldSpec.min) {
+        errors.push({
+          field: fieldName,
+          error: 'VALUE_TOO_SMALL',
+          message: `Field '${fieldName}' must be >= ${fieldSpec.min}, got ${value}`
+        });
+      }
+
+      // ISO8601 format check
+      if (fieldSpec.format === 'ISO8601') {
+        const date = new Date(value);
+        if (isNaN(date.getTime())) {
+          errors.push({
+            field: fieldName,
+            error: 'INVALID_FORMAT',
+            message: `Field '${fieldName}' must be valid ISO8601 timestamp`
+          });
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Get human-readable schema documentation
+   *
+   * @returns {string} Formatted schema documentation
+   */
+  static getDocumentation() {
+    const schema = this.getSchema();
+    let doc = 'Validation Proof Data Format Specification v1.0.0\n';
+    doc += '='.repeat(60) + '\n\n';
+
+    for (const [field, spec] of Object.entries(schema)) {
+      doc += `${field}:\n`;
+      doc += `  Type:        ${spec.type}\n`;
+      doc += `  Required:    ${spec.required ? 'YES' : 'NO'}\n`;
+      if (spec.format) doc += `  Format:      ${spec.format}\n`;
+      if (spec.min !== undefined) doc += `  Min value:   ${spec.min}\n`;
+      doc += `  Description: ${spec.description}\n`;
+      doc += `  Example:     ${JSON.stringify(spec.example)}\n`;
+      doc += '\n';
+    }
+
+    return doc;
+  }
+}
+
+module.exports = ValidationProofSchema;