npm package: @onlineapps/service-validator-core
Description: Core validation logic for microservices
Author: OnlineApps
Latest version: 1.0.12

# @onlineapps/service-validator-core

Core validation logic for microservices with two-stage validation support.

## Installation

```bash
npm install @onlineapps/service-validator-core
```

## Usage

```javascript
const ValidationCore = require('@onlineapps/service-validator-core');

const validator = new ValidationCore({
  strictMode: true,
  requiredConnectors: [
    'connector-logger',
    'connector-storage',
    'connector-registry-client',
    'connector-mq-client',
    'connector-cookbook'
  ]
});

// Validate service data
const results = await validator.validate({
  openApiSpec: { /* OpenAPI 3.0 spec */ },
  endpoints: [ /* endpoint definitions */ ],
  metadata: { /* service metadata */ },
  health: '/health'
});

// Generate pre-validation token
if (results.success) {
  const token = await validator.generatePreValidationToken(results, 'my-service');
}

// Generate certificate (system validator only)
if (results.success) {
  const certificate = await validator.generateCertificate(
    results,
    'my-service',
    '1.0.0'
  );
}
```

## Features

### Validators

#### OpenApiValidator
Validates OpenAPI 3.0 and Swagger 2.0 specifications:
- Valid OpenAPI/Swagger format
- All paths documented
- Response schemas defined
- Required fields present

#### EndpointValidator
Validates endpoint definitions:
- Endpoints match OpenAPI spec
- Handler functions exist
- Proper HTTP methods used
- Path parameters defined

#### ConnectorValidator
Checks required connectors:
- Required connectors present in package.json
- Correct versions installed
- Proper initialization in code

#### HealthValidator
Validates health check configuration:
- `/health` endpoint exists
- Returns proper status format
- Accessible without authentication

### Security
- **TokenManager** - Generates and verifies pre-validation tokens
- **CertificateManager** - Issues and verifies cryptographic certificates

### Validation Proof Structure

**Official format** (returned by `ValidationProofCodec.encode()`):
```json
{
  "validationProof": "<SHA256-hash-64-chars>",
  "validationData": {
    "serviceName": "hello-service",
    "version": "1.0.0",
    "validator": "@onlineapps/conn-orch-validator",
    "validatorVersion": "2.0.6",
    "validatedAt": "2025-10-23T06:53:12.996Z",
    "testsRun": 3,
    "testsPassed": 3,
    "testsFailed": 0,
    "durationMs": 151
  }
}
```

**IMPORTANT:** Always use `validationProof` and `validationData` keys (NOT `hash`/`data`).

See [ValidationProofCodec.js](src/security/ValidationProofCodec.js) and [ValidationProofSchema.js](src/types/ValidationProofSchema.js) for complete specification.

## API

### ValidationCore(config)

Creates a new validation instance.

**Options:**
- `strictMode` (boolean) - Strict validation mode
- `requiredConnectors` (array) - List of required connector names
- `issuer` (string) - Certificate issuer name

### validate(serviceData)

Validates service configuration.

**Returns:** Validation results object with `success`, `errors`, `warnings`, and `checks`.

### generatePreValidationToken(results, serviceName)

Generates a pre-validation token for successful validation.

**Returns:** Object with `{token, secret, tokenId}` (configurable expiry via TOKEN_EXPIRY env var, single-use).

### generateCertificate(results, serviceName, version)

Generates a validation certificate.

**Returns:** Certificate object with cryptographic signature.

### verifyCertificate(certificate)

Verifies a validation certificate.

**Returns:** Boolean indicating certificate validity.

## Related Documentation

- **[⭐ Complete Two-Tier Validation System](/docs/modules/validator.md)** - Full architecture and flow
- [validator-client](/shared/validator/validator-client/README.md) - Local pre-validation client
- [api_services_validator](/api/api_services_validator/README.md) - System validator service

## License

MIT