Skip to content

open-kya/kya-validator

BranchesTags

Repository files navigation

KYA Validator

A robust Rust-core validator for KYA (Know Your AI) Manifests with Python, Rust, and TypeScript/JavaScript bindings.

Overview

The KYA Validator provides comprehensive validation of AI agent manifests, ensuring cryptographic proof of identity, attestation of secure execution environments, and enforcement of policy rules.

Features

Core Validation ✅

  • Schema Validation: JSON Schema (Draft 7) compliance checking
  • DID Resolution: Support for did:key, did:web, and did:pkh
  • Cryptographic Verification: Ed25519 and Secp256k1 signature validation
  • TTL Checks: Time-to-live validation for manifest freshness
  • External Link Validation: URL reachability and content verification
  • Content Hashing: SHA256/384/512 digest verification

Advanced Features (Phase 2) 🚀

  • TEE Evidence Validation: Intel SGX and AMD SEV-SNP attestation
  • Blockchain Solvency: Multi-provider on-chain balance verification
  • Advanced Policy Engine: Complex rule composition and evaluation
  • WebAssembly/TypeScript: Full browser and Node.js support

Installation

Rust

cargo add kya_validator

Python

pip install kya-validator

TypeScript/JavaScript (WASM)

# From npm
pnpm add @open-kya/kya-validator-wasm

# Local build
cd bindings/wasm && pnpm run build:all

Note: For local development builds, see bindings/wasm/README.md.

Quick Start

Rust

use kya_validator::{validate_manifest_value, ValidationConfig};
use serde_json::json;

let manifest = json!({
    "kyaVersion": "1.0",
    "agentId": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "proof": []
});

let report = validate_manifest_value(&manifest);
println!("Valid: {}", report.schema_valid);

Python

from kya_validator import validate_manifest, ValidationConfig

manifest = {
    "kyaVersion": "1.0",
    "agentId": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    "proof": []
}

report = validate_manifest(json.dumps(manifest))
print(f"Valid: {report.is_valid}")

TypeScript/JavaScript (Browser)

import { validateManifest, init } from '@open-kya/kya-validator-wasm/browser';

// Initialize WASM module
await init();

const manifest = {
    kyaVersion: "1.0",
    agentId: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    proof: []
};

const report = await validateManifest(manifest);
console.log("Valid:", report.schema_valid);

TypeScript/JavaScript (Node.js)

import { validateManifest } from '@open-kya/kya-validator-wasm/node';

// No async init needed in Node.js
const manifest = {
    kyaVersion: "1.0",
    agentId: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
    proof: []
};

const report = validateManifest(manifest);
console.log("Valid:", report.schema_valid);

Python API

Core Types

The Python package provides the following core types:

  • ValidationConfig - Configuration for manifest validation
  • ValidationReport - Results of manifest validation
  • ValidationMode - Validation mode (selfAudit/clientAudit)
  • HashAlgorithm - Hash algorithm for digest computation
  • CryptoReport - Cryptographic verification report
  • TeeEvidence - TEE attestation evidence
  • TeeReport - TEE verification report
  • SolvencyCheck - Blockchain solvency check configuration
  • SolvencyReport - Blockchain solvency report
  • PolicyContext - Context for policy evaluation

Main Classes

  • Validator - Main validator for manifest validation
  • PolicyEngine - Advanced policy rule evaluation
  • TeeVerifier - TEE attestation evidence verifier
  • SolvencyChecker - Blockchain solvency checker
  • StreamingValidator - Chunk-based validation for large manifests
  • PluginManager - Plugin system manager
  • Inspector - Manifest inspector
  • Resolver - DID and verification method resolver

Configuration

from kya_validator import load_config, ValidationConfig

# Load from file
config = load_config('config.json')

# Load from environment variables
config = load_config()  # Uses KYA_VALIDATOR_* env vars

# Create preset
config = ValidationConfig.self_audit()

Validation

from kya_validator import validate_manifest, ValidationReport

# Simple validation
manifest = {"kyaVersion": "1.0", "agentId": "...", "proof": [...]}
report = validate_manifest(json.dumps(manifest))

# With configuration
from kya_validator import ValidationConfig, validate_manifest_with_config

config = ValidationConfig(
    mode=ValidationMode.SELF_AUDIT,
    allowed_kya_versions=["1.0"],
    required_fields=["/agentId", "/proof"],
)
report = validate_manifest_with_config(
    manifest_json=json.dumps(manifest),
    config=config,
)

TEE Verification

from kya_validator import TeeVerifier, TeeEvidence

verifier = TeeVerifier()
evidence = TeeEvidence(
    attestation_type="intel-sgx",
    quote="base64encodedquote...",
    mr_enclave="0" * 64,
    mr_signer="0" * 64,
    product_id=0,
    min_svn=2,
)

report = verifier.verify(evidence)
print(f"Valid: {report.valid}")

Blockchain Solvency

from kya_validator import verify_solvency

report = verify_solvency(
    address="0x742d35Cc6634C0532925a3b844Bc9e7595f0bE",
    network="ethereum",
    min_balance="0x0",
    provider="alchemy",
)

print(f"Meets minimum: {report.meets_minimum}")
print(f"Balance: {report.balance_ether} ETH")

Policy Evaluation

from kya_validator import PolicyEngine, create_policy, create_rule

engine = PolicyEngine()
policy = create_policy(
    name="strict-policy",
    rules=[
        create_rule(
            name="version-check",
            condition={
                "pointer": "/kyaVersion",
                "operator": "equals",
                "value": "1.0",
            },
            action="deny",
        ),
    ],
)

engine.add_policy(policy)
result = engine.evaluate(manifest)
print(f"Allowed: {result.allowed}")

Streaming Validation

from kya_validator import StreamingValidator

validator = StreamingValidator()
result = validator.add_chunk('{"kyaVersion": "1.0"}', 1)
result = validator.add_chunk('{"agentId": "..."}', 2)
report = validator.finalize()

print(f"Valid: {report['valid']}")
print(f"Chunks: {report['state']['chunksProcessed']}")

Plugin System

from kya_validator import PluginManager, ValidationPlugin

class CustomPlugin(ValidationPlugin):
    def name(self):
        return "custom_plugin"

    def version(self):
        return "1.0.0"

    def description(self):
        return "A custom validation plugin"

    def custom_rules(self):
        return []

manager = PluginManager()
plugin = CustomPlugin()
manager.register(plugin)

info = manager.get_plugin_info("custom_plugin")
print(f"Plugin: {info.name}")
print(f"Enabled: {manager.get_enabled_plugins()}")

DID Resolution

from kya_validator import Resolver

resolver = Resolver()

# Resolve did:key
key = resolver.resolve_key("did:key:z6Mk...")
print(f"Key ID: {key['id']}")

# Parse did:pkh
info = resolver.parse_did_pkh(
    "did:pkh:eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bE"
)
print(f"Network: {info['network']}")
print(f"Address: {info['address']}")

Configuration

Default Configuration

{
  "mode": "SelfAudit",
  "allowedKyaVersions": ["1.0", "1.1"],
  "requiredFields": [],
  "enforceControllerMatch": true,
  "checkExternalLinks": false,
  "requireAllProofs": false,
  "requiredFieldPairs": [],
  "allowedControllers": [],
  "requiredVcTypes": [],
  "attestationChecks": []
}

Self-Audit Preset

{
  "mode": "SelfAudit",
  "allowedKyaVersions": ["1.0", "1.1"],
  "requiredFields": ["/agentId", "/proof"],
  "enforceControllerMatch": true,
  "checkExternalLinks": true,
  "requireAllProofs": true,
  "requiredFieldPairs": [],
  "allowedControllers": [],
  "requiredVcTypes": [],
  "attestationChecks": []
}

Client-Audit Preset

{
  "mode": "ClientAudit",
  "allowedKyaVersions": ["1.0", "1.1"],
  "requiredFields": ["/agentId", "/proof"],
  "enforceControllerMatch": true,
  "checkExternalLinks": false,
  "requireAllProofs": false,
  "requiredFieldPairs": [],
  "allowedControllers": [],
  "requiredVcTypes": [],
  "attestationChecks": []
}

Documentation

Core Modules

Testing

Run All Tests

make test

Run Python Tests

python -m pytest tests/

Configuration

Environment Variables

Configuration can be loaded from environment variables with the KYA_VALIDATOR_ prefix:

  • KYA_VALIDATOR_MODE - Validation mode
  • KYA_VALIDATOR_ALLOWED_VERSIONS - Comma-separated list of allowed versions
  • KYA_VALIDATOR_REQUIRED_FIELDS - Comma-separated list of required fields
  • KYA_VALIDATOR_ENFORCE_CONTROLLER_MATCH - Boolean for controller matching
  • KYA_VALIDATOR_CHECK_EXTERNAL_LINKS - Boolean for external link checking
  • KYA_VALIDATOR_REQUIRE_ALL_PROOFS - Boolean for requiring all proofs

Example: Setting Environment Variables

export KYA_VALIDATOR_MODE=SelfAudit
export KYA_VALIDATOR_ALLOWED_VERSIONS=1.0,1.1
export KYA_VALIDATOR_REQUIRED_FIELDS=/agentId,/proof

Performance

Validation Performance

  • Schema Validation: ~1-5ms
  • Crypto Verification: ~5-20ms
  • TTL Checks: <1ms
  • Policy Evaluation: ~0.1-1ms per rule

Advanced Features

  • TEE Quote Validation: <10ms (structural), ~50-100ms (full)
  • Blockchain Balance: <1ms (cached), ~50-200ms (network)
  • WASM Validation: ~5-20ms per manifest

Optimization Tips

  1. Reuse Configurations: Parse and reuse config objects
  2. Batch Validations: Validate multiple manifests together
  3. Use Caching: Enable blockchain/TTL caching
  4. Pre-Validate JSON: Check JSON format before validation
  5. Skip Unnecessary Checks: Disable features not needed for your use case

Security Considerations

Best Practices

  1. Validate Input: Always validate JSON before processing
  2. Check Signatures: Never skip cryptographic verification
  3. Verify TEE: Validate attestation claims
  4. Check Solvency: Verify on-chain balances
  5. Enforce Policies: Apply strict validation rules
  6. Use CSP Headers: Set Content-Security-Policy headers for external requests

CSP Headers

Content-Security-Policy: 
  default-src 'self';
  script-src 'self' blob:;
  worker-src 'self' blob:;

Architecture

Modular Design

kya-validator/
├── core/                  # Rust core library
│   ├── types.rs           # Core data structures
│   ├── validator.rs       # Main validation logic
│   ├── resolver.rs        # DID resolution
│   ├── verifier.rs        # Crypto verification
│   ├── inspector.rs      # Field validation
│   ├── policy.rs          # Basic policies
│   ├── tee.rs             # TEE attestation
│   ├── blockchain.rs      # Solvency checks
│   ├── policy_advanced.rs # Advanced policies
│   ├── wasm.rs            # WASM bindings
│   ├── plugin.rs          # Plugin system
│   ├── plugin_manager.rs  # Plugin management
│   └── lib.rs             # Exports
├── bindings/              # Language bindings
│   ├── python/           # Python bindings (PyO3)
│   │   ├── __init__.py
│   │   ├── types.py
│   │   ├── errors.py
│   │   ├── config.py
│   │   ├── utils.py
│   │   ├── validator.py
│   │   ├── policy.py
│   │   ├── tee.py
│   │   ├── blockchain.py
│   │   ├── streaming.py
│   │   ├── plugins.py
│   │   ├── inspector.py
│   │   ├── resolver.py
│   │   └── _ffi.py
│   └── wasm/              # WASM examples
│       ├── wasm-usage.ts
│       ├── wasm-usage.js
│       ├── wasm-async-usage.ts
│       ├── streaming-validation.ts
│       └── custom-plugin-example.ts
├── apps/                  # Applications
│   ├── ui/                # Policy editor UI (React/Vite)
│   └── demo_backend/      # Demo backend (FastAPI)
└── tests/                 # Test suite

Integration Points

  • Resolver → DID to public key mapping
  • Verifier → Signature verification
  • Inspector → Schema and TTL validation
  • TEE Module → Attestation verification
  • Blockchain Module → Solvency checks
  • Policy Engine → Rule enforcement
  • Streaming Validator → Chunk-based validation
  • Plugin System → Custom validation rules

Contributing

Development Setup

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install dependencies
cargo build

# Run tests
cargo test

# Format code
cargo fmt

# Check code
cargo clippy

Adding Features

  1. Create feature branch
  2. Write tests for new feature
  3. Update documentation
  4. Submit PR

Code Style

  • Follow Rust naming conventions
  • Use #[allow(...)] sparingly
  • Document public APIs
  • Write tests for all public functions

License

See LICENSE file for details.

Resources

Roadmap

Phase 2 (In Progress - 80% Complete)

  • TEE Evidence Validation
  • Enhanced Solvency Verification
  • Advanced Policy Engine
  • TypeScript/WASM Bindings
  • Performance Optimization
  • Documentation Polish

Phase 3 (Planned)

  • Async WASM Operations
  • Streaming Validation
  • Plugin System
  • Policy Editor UI
  • Telemetry Integration
  • Performance Optimization
  • Documentation Polish

Release & Packaging

Versioning

Version follows semantic versioning (MAJOR.MINOR.PATCH):

  • Cargo.toml (Rust): Source of truth for core version
  • pyproject.toml (Python): Must match Rust version
  • Update both files together before release

Packaging

# Build Rust release
cargo build --release

# Build Python wheel (requires maturin)
uv tool run maturin build --release

# Build WASM package
wasm-pack build --target web

Release Checklist

  1. Update version in Cargo.toml and pyproject.toml
  2. Update CHANGELOG.md (if present)
  3. Tag release: git tag -a v0.x.x -m "Release v0.x.x"
  4. Push tags: git push --tags
  5. Build and publish Python package: uv tool run maturin build --release && uv publish
  6. Publish WASM to npm (if applicable)

Optional Components

The following components are not required for core validation functionality:

  • UI Demo (apps/ui/) - React/Vite policy editor demo
  • Demo Backend (apps/demo_backend/) - FastAPI demo with LLM integration
  • WASM Bindings (bindings/wasm/) - Browser/Node.js WASM package. See README for documentation.

These are optional and may be moved to separate packages in future releases.

Support

For issues, questions, or contributions, please open an issue or pull request in the repository.

Version: 0.2.0 Status: Production Ready (Core) / Beta (Phase 2 Features)

About

The reference validator for the Open KYA (Know Your Agent) standard.

Topics

python rust validator npm-package wasm rust-crate pypi-package github-action kyc-service

Resources

Readme

License

MPL-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v0.2.3 Latest
Feb 18, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages