@onlineapps/conn-orch-validator 2.0.28 → 2.0.30

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.28",
+  "version": "2.0.30",
   "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,13 +157,10 @@ 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;
-      if (!validationAccountId) {
-        throw new Error('[CookbookTestRunner] Missing required environment variable OA_VALIDATION_ACCOUNT_ID');
+      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,
@@ -172,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,16 +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;
-        if (!validationAccountId) {
-          throw new Error('[ServiceReadinessValidator] Missing required environment variable OA_VALIDATION_ACCOUNT_ID');
+        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}`);
@@ -136,7 +136,7 @@ class ValidationOrchestrator {
       const packageFile = path.join(this.serviceRoot, 'package.json');
       const dockerFile = path.join(this.serviceRoot, 'Dockerfile');
       const dockerComposeFile = path.join(this.serviceRoot, 'docker-compose.yml');
-      const envExampleFile = path.join(this.serviceRoot, '.env.example');
+      const envTemplateFile = path.join(this.serviceRoot, '..', '..', 'config', 'env-templates', `${path.basename(this.serviceRoot)}.env`);
 
       if (!fs.existsSync(configFile)) {
         throw new Error('config.json not found');
@@ -154,8 +154,8 @@ class ValidationOrchestrator {
       if (fs.existsSync(dockerComposeFile)) {
         infra.dockerCompose = fs.readFileSync(dockerComposeFile, 'utf8');
       }
-      if (fs.existsSync(envExampleFile)) {
-        infra.envExample = fs.readFileSync(envExampleFile, 'utf8');
+      if (fs.existsSync(envTemplateFile)) {
+        infra.envTemplate = fs.readFileSync(envTemplateFile, 'utf8');
       }
 
       // Extract @onlineapps/* dependencies

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,122 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Try reading from new path first (config/service/), fall back to legacy (conn-config/).
+ * @param {string} root - Service root
+ * @param {string} filename - e.g. 'config.json'
+ * @returns {string|null} File contents or null
+ */
+function readConfigFile(root, filename) {
+  const candidates = [
+    path.join(root, 'config', 'service', filename),
+    path.join(root, 'conn-config', filename)
+  ];
+  for (const p of candidates) {
+    try { return fs.readFileSync(p, 'utf-8'); } catch { /* try next */ }
+  }
+  return null;
+}
+
+function hasConfigDir(root) {
+  return fs.existsSync(path.join(root, 'config', 'service')) ||
+         fs.existsSync(path.join(root, 'conn-config'));
+}
+
+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: hasConfigDir(root), id: 'dir_conn_config', message: 'config/service/ or 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 = readConfigFile(root, '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 = readConfigFile(root, '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 configRaw = readConfigFile(root, '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,26 +166,100 @@ 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
    */
   validateDirectoryStructure() {
     const requiredDirs = [
-      { path: 'conn-config', description: 'Configuration directory' },
       { path: 'src', description: 'Source code directory' },
       { path: 'tests', description: 'Tests directory' }
     ];
 
+    if (!hasConfigDir(this.serviceRoot)) {
+      this.errors.push({
+        type: 'MISSING_DIRECTORY',
+        path: 'config/service/ (or conn-config/)',
+        message: 'Required directory missing: config/service/ (or legacy conn-config/)',
+        description: 'Configuration directory',
+        fix: 'Create directory: mkdir -p config/service'
+      });
+    } else {
+      this.info.push('✓ Found Configuration directory');
+    }
+
     const recommendedDirs = [
       { path: 'tests/unit', description: 'Unit tests' },
       { path: 'tests/integration', description: 'Integration tests' },
@@ -108,48 +299,46 @@ class ServiceStructureValidator {
    * Validate configuration files
    */
   validateConfigurationFiles() {
-    // 1. Validate conn-config/config.json
-    const configPath = path.join(this.serviceRoot, 'conn-config/config.json');
-    if (!fs.existsSync(configPath)) {
+    const configRaw = readConfigFile(this.serviceRoot, 'config.json');
+    if (!configRaw) {
       this.errors.push({
         type: 'MISSING_CONFIG',
-        path: 'conn-config/config.json',
-        message: 'Service configuration missing: conn-config/config.json',
+        path: 'config/service/config.json (or conn-config/config.json)',
+        message: 'Service configuration missing: config/service/config.json (or conn-config/config.json)',
         fix: 'Create config.json with service metadata. See: /docs/standards/SERVICE_TEMPLATE.md'
       });
     } else {
       try {
-        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const config = JSON.parse(configRaw);
         this.validateConfigStructure(config);
         this.info.push('✓ Found valid config.json');
       } catch (error) {
         this.errors.push({
           type: 'INVALID_CONFIG',
-          path: 'conn-config/config.json',
+          path: 'config.json',
           message: `Invalid JSON in config.json: ${error.message}`,
           fix: 'Fix JSON syntax errors in config.json'
         });
       }
     }
 
-    // 2. Validate conn-config/operations.json
-    const operationsPath = path.join(this.serviceRoot, 'conn-config/operations.json');
-    if (!fs.existsSync(operationsPath)) {
+    const opsRaw = readConfigFile(this.serviceRoot, 'operations.json');
+    if (!opsRaw) {
       this.errors.push({
         type: 'MISSING_OPERATIONS',
-        path: 'conn-config/operations.json',
-        message: 'Operations specification missing: conn-config/operations.json',
+        path: 'config/service/operations.json (or conn-config/operations.json)',
+        message: 'Operations specification missing: config/service/operations.json (or conn-config/operations.json)',
         fix: 'Create operations.json. See: /docs/standards/OPERATIONS.md'
       });
     } else {
       try {
-        const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
+        const operations = JSON.parse(opsRaw);
         this.validateOperationsStructure(operations);
         this.info.push('✓ Found valid operations.json');
       } catch (error) {
         this.errors.push({
           type: 'INVALID_OPERATIONS',
-          path: 'conn-config/operations.json',
+          path: 'operations.json',
           message: `Invalid JSON in operations.json: ${error.message}`,
           fix: 'Fix JSON syntax errors in operations.json'
         });
@@ -178,7 +367,7 @@ class ServiceStructureValidator {
       if (!value) {
         this.errors.push({
           type: 'MISSING_CONFIG_FIELD',
-          path: 'conn-config/config.json',
+          path: 'config/service/config.json',
           field: field,
           message: `Required field missing in config.json: ${field}`,
           fix: `Add "${field}" to config.json`
@@ -191,7 +380,7 @@ class ServiceStructureValidator {
       if (!/^[a-z][a-z0-9-]*$/.test(config.service.name)) {
         this.warnings.push({
           type: 'INVALID_SERVICE_NAME',
-          path: 'conn-config/config.json',
+          path: 'config/service/config.json',
           field: 'service.name',
           value: config.service.name,
           message: `Service name should be lowercase kebab-case: ${config.service.name}`,
@@ -227,7 +416,7 @@ class ServiceStructureValidator {
     if (!operations.operations) {
       this.errors.push({
         type: 'INVALID_OPERATIONS_STRUCTURE',
-        path: 'conn-config/operations.json',
+        path: 'config/service/operations.json',
         message: 'operations.json must have "operations" key',
         fix: 'Wrap operations in {"operations": {...}}. See: /docs/standards/OPERATIONS.md'
       });
@@ -238,7 +427,7 @@ class ServiceStructureValidator {
     if (typeof ops !== 'object' || Array.isArray(ops)) {
       this.errors.push({
         type: 'INVALID_OPERATIONS_TYPE',
-        path: 'conn-config/operations.json',
+        path: 'config/service/operations.json',
         message: 'operations must be an object',
         fix: 'operations should be key-value pairs: {"operation-name": {...}}'
       });
@@ -248,7 +437,7 @@ class ServiceStructureValidator {
     if (Object.keys(ops).length === 0) {
       this.warnings.push({
         type: 'NO_OPERATIONS',
-        path: 'conn-config/operations.json',
+        path: 'config/service/operations.json',
         message: 'No operations defined',
         fix: 'Add at least one operation to operations.json'
       });
@@ -271,7 +460,7 @@ class ServiceStructureValidator {
       if (!spec[field]) {
         this.errors.push({
           type: 'MISSING_OPERATION_FIELD',
-          path: 'conn-config/operations.json',
+          path: 'config/service/operations.json',
           operation: name,
           field: field,
           message: `Operation "${name}" missing required field: ${field}`,
@@ -284,7 +473,7 @@ class ServiceStructureValidator {
     if (spec.endpoint && !spec.endpoint.startsWith('/')) {
       this.errors.push({
         type: 'INVALID_ENDPOINT',
-        path: 'conn-config/operations.json',
+        path: 'config/service/operations.json',
         operation: name,
         field: 'endpoint',
         value: spec.endpoint,
@@ -298,7 +487,7 @@ class ServiceStructureValidator {
     if (spec.method && !validMethods.includes(spec.method)) {
       this.errors.push({
         type: 'INVALID_HTTP_METHOD',
-        path: 'conn-config/operations.json',
+        path: 'config/service/operations.json',
         operation: name,
         field: 'method',
         value: spec.method,
@@ -350,7 +539,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 +581,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');