@onlineapps/conn-orch-validator 2.0.27 → 2.0.29

package/README.md

@@ -88,20 +88,52 @@ services/my-service/
 ```
 
 **Proof Lifecycle:**
-- **Valid for:** 30 days OR until service fingerprint changes
+- **Valid for:** 7 days OR until service fingerprint changes
 - **Fingerprint:** SHA256 hash of (version + operations + dependencies + config)
 - **Revalidation:** Automatic if proof missing/invalid/expired
 - **Registry:** Accepts service with valid proof (skips Tier 2 validation)
 
 ---
 
+## Implementation Standard Levels
+
+The validator evaluates each service against cumulative implementation standards. Levels are ordered — each requires all previous to pass:
+
+| Level | Name | Checks | Since |
+|-------|------|--------|-------|
+| **v1.0** | Base Service Standard | `conn-config/`, `src/app.js`, `index.js`, valid `config.json` + `operations.json`, `@onlineapps/service-wrapper` dep | 2025-06 |
+| **v1.1** | Multitenancy Standard | `wrapper.tenantContext` configured in `config.json` | 2026-03 |
+| **v1.2** | Business Error Handling | `@onlineapps/service-common` dep + `businessErrorHandler` in `src/app.js` | 2026-03 |
+
+**Key properties:**
+- **Cumulative** — v1.2 requires v1.0 + v1.1 to also pass
+- **Baked into validator** — older validator versions naturally know fewer levels (backward compatible)
+- **Warnings** — next unsatisfied level generates `STANDARD_LEVEL_GAP` warnings with specific missing checks
+- **Exposed in `/info`** — ServiceWrapper's `GET /info` endpoint returns the highest satisfied level
+- **In validation results** — `validate()` returns `standardLevel` and `standardDetails`
+
+```javascript
+// Programmatic access
+const { ServiceStructureValidator } = require('@onlineapps/conn-orch-validator/src/validators/ServiceStructureValidator');
+const validator = new ServiceStructureValidator('/path/to/service');
+const { level, details } = validator.determineStandardLevel();
+// level = 'v1.2', details = [{ level: 'v1.0', passed: true, checks: [...] }, ...]
+
+// List all known levels
+ServiceStructureValidator.getStandardLevels();
+// [{ level: 'v1.0', name: 'Base Service Standard', since: '2025-06-01' }, ...]
+```
+
+**Related:** [Service Endpoints — Standard Levels](/docs/standards/SERVICE_ENDPOINTS.md#implementation-standard-levels), [Error Handling Standard](/docs/standards/ERROR_HANDLING.md#business-service-error-standard)
+
 ## Related Documentation
 
 - [SERVICE_REGISTRATION_FLOW.md](/services/hello-service/docs/SERVICE_REGISTRATION_FLOW.md)
 - [/docs/architecture/validator.md](/docs/architecture/validator.md)
 - [/docs/standards/OPERATIONS.md](/docs/standards/OPERATIONS.md)
+- [/docs/standards/ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md)
 - [@onlineapps/service-validator-core](/shared/service-validator-core/README.md)
 
 ---
 
-*Last updated: 2025-10-22*
+*Last updated: 2026-03-24*

package/jest.config.js

@@ -1,5 +1,8 @@
 'use strict';
 
+process.env.OA_VALIDATION_TENANT_ID = process.env.OA_VALIDATION_TENANT_ID || '99';
+process.env.OA_VALIDATION_WORKSPACE_ID = process.env.OA_VALIDATION_WORKSPACE_ID || '200';
+
 module.exports = {
   testEnvironment: 'node',
   coverageDirectory: 'coverage',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "2.0.27",
+  "version": "2.0.29",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "scripts": {

package/src/CookbookTestRunner.js

@@ -157,11 +157,11 @@ class CookbookTestRunner {
       // Resolve operation endpoint from operations.json
       const endpoint = await this.resolveOperation(step.service, step.operation);
 
-      // Build request
-      // Validation context headers:
-      // 1. x-validation-request: signals this is a validation probe (deterministic responses)
-      // 2. account-id: required by multitenancy middleware for /api/** endpoints
-      const validationAccountId = process.env.OA_VALIDATION_ACCOUNT_ID || '99999';
+      const validationTenantId = process.env.OA_VALIDATION_TENANT_ID;
+      const validationWorkspaceId = process.env.OA_VALIDATION_WORKSPACE_ID;
+      if (!validationTenantId || !validationWorkspaceId) {
+        throw new Error('[CookbookTestRunner] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
+      }
       const request = {
         method: endpoint.method,
         url: `${this.serviceUrl}${endpoint.path}`,
@@ -169,7 +169,8 @@ class CookbookTestRunner {
         timeout: testConfig.timeout || this.timeout,
         headers: {
           'x-validation-request': 'true',
-          'account-id': validationAccountId,
+          'x-tenant-id': validationTenantId,
+          'x-workspace-id': validationWorkspaceId,
           ...resolveHeaders(endpoint.headers),
           ...resolveHeaders(step.headers)
         }

package/src/ServiceReadinessValidator.js

@@ -215,13 +215,15 @@ class ServiceReadinessValidator {
         // Generate test input based on schema
         const testInput = this.generateTestInput(operation.input);
         
-        // Validation context headers:
-        // 1. x-validation-request: signals this is a validation probe
-        // 2. account-id: required by multitenancy middleware for /api/** endpoints
-        const validationAccountId = process.env.OA_VALIDATION_ACCOUNT_ID || '99999';
+        const validationTenantId = process.env.OA_VALIDATION_TENANT_ID;
+        const validationWorkspaceId = process.env.OA_VALIDATION_WORKSPACE_ID;
+        if (!validationTenantId || !validationWorkspaceId) {
+          throw new Error('[ServiceReadinessValidator] Missing required environment variables OA_VALIDATION_TENANT_ID and/or OA_VALIDATION_WORKSPACE_ID');
+        }
         const headers = {
           'x-validation-request': 'true',
-          'account-id': validationAccountId,
+          'x-tenant-id': validationTenantId,
+          'x-workspace-id': validationWorkspaceId,
           ...resolveHeaders(operation.headers)
         };
 

package/src/ValidationOrchestrator.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
+const { ValidationProofCodec, ValidationProofVerifier } = require('@onlineapps/service-validator-core');
 const FingerprintUtils = require('@onlineapps/service-validator-core').FingerprintUtils;
 const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
 const ServiceReadinessValidator = require('./ServiceReadinessValidator');
@@ -97,10 +97,10 @@ class ValidationOrchestrator {
         return false;
       }
 
-      // Decode and verify proof using ValidationProofCodec
-      const verificationResult = ValidationProofCodec.decode(proof, {
-        maxProofAge: 30 * 24 * 60 * 60 * 1000 // 30 days
-      });
+      // Verify proof integrity + age using the shared core verifier defaults.
+      // This MUST match what Tier-2 validator enforces to avoid PROOF_EXPIRED drift.
+      const verifier = new ValidationProofVerifier();
+      const verificationResult = verifier.verifyProof(proof);
 
       if (!verificationResult.valid) {
         console.log(`[ValidationOrchestrator] Proof validation failed: ${verificationResult.reason}`);

package/src/validators/ServiceStructureValidator.js

@@ -4,7 +4,8 @@
  * Validates that a business service has correct directory structure,
  * configuration files, and follows OA Drive standards.
  *
- * Used by test helpers to provide clear error messages when something is wrong.
+ * Each standard level is cumulative — v1.2 requires all checks from v1.0 + v1.1 + v1.2.
+ * Older validator versions naturally support fewer levels (they don't know about newer ones).
  *
  * @module validators/ServiceStructureValidator
  */
@@ -14,6 +15,102 @@
 const fs = require('fs');
 const path = require('path');
 
+const STANDARD_LEVELS = [
+  {
+    level: 'v1.0',
+    name: 'Base Service Standard',
+    since: '2025-06-01',
+    checks: (root) => {
+      const results = [];
+      const has = (p) => fs.existsSync(path.join(root, p));
+      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
+
+      results.push({ passed: has('conn-config'), id: 'dir_conn_config', message: 'conn-config/ directory' });
+      results.push({ passed: has('src'), id: 'dir_src', message: 'src/ directory' });
+      results.push({ passed: has('tests'), id: 'dir_tests', message: 'tests/ directory' });
+      results.push({ passed: has('src/app.js'), id: 'file_app', message: 'src/app.js' });
+      results.push({ passed: has('index.js'), id: 'file_index', message: 'index.js entry point' });
+
+      const configRaw = read('conn-config/config.json');
+      let configValid = false;
+      if (configRaw) {
+        try {
+          const cfg = JSON.parse(configRaw);
+          configValid = !!(cfg.service?.name && cfg.service?.port);
+        } catch { /* invalid JSON */ }
+      }
+      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name + service.port' });
+
+      const opsRaw = read('conn-config/operations.json');
+      let opsValid = false;
+      if (opsRaw) {
+        try {
+          const ops = JSON.parse(opsRaw);
+          opsValid = !!(ops.operations && typeof ops.operations === 'object');
+        } catch { /* invalid JSON */ }
+      }
+      results.push({ passed: opsValid, id: 'operations_valid', message: 'Valid operations.json' });
+
+      const pkgRaw = read('package.json');
+      let hasWrapper = false;
+      if (pkgRaw) {
+        try {
+          const pkg = JSON.parse(pkgRaw);
+          hasWrapper = !!pkg.dependencies?.['@onlineapps/service-wrapper'];
+        } catch { /* invalid JSON */ }
+      }
+      results.push({ passed: hasWrapper, id: 'dep_service_wrapper', message: '@onlineapps/service-wrapper dependency' });
+
+      return results;
+    }
+  },
+  {
+    level: 'v1.1',
+    name: 'Multitenancy Standard',
+    since: '2026-03-01',
+    checks: (root) => {
+      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
+
+      const configRaw = read('conn-config/config.json');
+      let hasTenantContext = false;
+      if (configRaw) {
+        try {
+          const cfg = JSON.parse(configRaw);
+          hasTenantContext = cfg.wrapper?.tenantContext !== undefined;
+        } catch { /* invalid JSON */ }
+      }
+      return [
+        { passed: hasTenantContext, id: 'tenant_context', message: 'wrapper.tenantContext configured in config.json' }
+      ];
+    }
+  },
+  {
+    level: 'v1.2',
+    name: 'Business Error Handling Standard',
+    since: '2026-03-24',
+    checks: (root) => {
+      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
+
+      const pkgRaw = read('package.json');
+      let hasServiceCommon = false;
+      if (pkgRaw) {
+        try {
+          const pkg = JSON.parse(pkgRaw);
+          hasServiceCommon = !!pkg.dependencies?.['@onlineapps/service-common'];
+        } catch { /* invalid JSON */ }
+      }
+
+      const appContent = read('src/app.js') || '';
+      const hasErrorMiddleware = appContent.includes('businessErrorHandler');
+
+      return [
+        { passed: hasServiceCommon, id: 'dep_service_common', message: '@onlineapps/service-common dependency' },
+        { passed: hasErrorMiddleware, id: 'error_middleware', message: 'businessErrorHandler middleware in src/app.js' }
+      ];
+    }
+  }
+];
+
 class ServiceStructureValidator {
   constructor(serviceRoot) {
     this.serviceRoot = serviceRoot;
@@ -49,16 +146,79 @@ class ServiceStructureValidator {
     // 5. Validate test structure
     this.validateTestStructure();
 
+    // 6. Determine standard level
+    const standardResult = this.determineStandardLevel();
+
     const valid = this.errors.length === 0;
 
     return {
       valid,
       errors: this.errors,
       warnings: this.warnings,
-      info: this.info
+      info: this.info,
+      standardLevel: standardResult.level,
+      standardDetails: standardResult.details
     };
   }
 
+  /**
+   * Determine the highest satisfied implementation standard level.
+   * Levels are cumulative — each requires all previous levels to pass.
+   *
+   * @returns {{ level: string|null, details: Array<{ level: string, name: string, passed: boolean, checks: Array }> }}
+   */
+  determineStandardLevel() {
+    const details = [];
+    let highestPassed = null;
+
+    for (const standard of STANDARD_LEVELS) {
+      const checkResults = standard.checks(this.serviceRoot);
+      const allPassed = checkResults.every(c => c.passed);
+
+      details.push({
+        level: standard.level,
+        name: standard.name,
+        since: standard.since,
+        passed: allPassed,
+        checks: checkResults
+      });
+
+      if (allPassed) {
+        highestPassed = standard.level;
+      } else {
+        break;
+      }
+    }
+
+    if (highestPassed) {
+      this.info.push(`✓ Implementation standard level: ${highestPassed}`);
+    }
+
+    const nextLevel = details.find(d => !d.passed);
+    if (nextLevel) {
+      const failing = nextLevel.checks.filter(c => !c.passed);
+      for (const check of failing) {
+        this.warnings.push({
+          type: 'STANDARD_LEVEL_GAP',
+          level: nextLevel.level,
+          check: check.id,
+          message: `Standard ${nextLevel.level} (${nextLevel.name}): missing ${check.message}`,
+          fix: `Implement ${check.message} to reach standard ${nextLevel.level}. See docs/standards/SERVICE_TEMPLATE.md`
+        });
+      }
+    }
+
+    return { level: highestPassed, details };
+  }
+
+  /**
+   * Get all known standard levels (for /info endpoint and external tools).
+   * @returns {Array<{ level: string, name: string, since: string }>}
+   */
+  static getStandardLevels() {
+    return STANDARD_LEVELS.map(s => ({ level: s.level, name: s.name, since: s.since }));
+  }
+
   /**
    * Validate directory structure exists
    */
@@ -350,7 +510,8 @@ class ServiceStructureValidator {
       // Check for @onlineapps dependencies
       const requiredDeps = [
         '@onlineapps/service-wrapper',
-        '@onlineapps/conn-orch-validator'
+        '@onlineapps/conn-orch-validator',
+        '@onlineapps/service-common'
       ];
 
       for (const dep of requiredDeps) {
@@ -391,6 +552,26 @@ class ServiceStructureValidator {
       });
     } else {
       this.info.push('✓ Found src/app.js');
+
+      try {
+        const appContent = fs.readFileSync(appPath, 'utf-8');
+        if (appContent.includes('businessErrorHandler')) {
+          this.info.push('✓ businessErrorHandler middleware registered');
+        } else {
+          this.warnings.push({
+            type: 'MISSING_ERROR_MIDDLEWARE',
+            path: 'src/app.js',
+            message: 'businessErrorHandler middleware not found in src/app.js',
+            fix: 'Register businessErrorHandler from @onlineapps/service-common as Express error middleware. See: /docs/standards/ERROR_HANDLING.md'
+          });
+        }
+      } catch (readError) {
+        this.warnings.push({
+          type: 'UNREADABLE_APP',
+          path: 'src/app.js',
+          message: `Could not read src/app.js: ${readError.message}`
+        });
+      }
     }
 
     const indexPath = path.join(this.serviceRoot, 'index.js');