Beltic KYA Ecosystem

KYA (Know Your Agent) is an in-development credential-based trust framework for AI agents. It establishes trust through cryptographically verifiable credentials.

Trust Chain

Developer (KYB Verified) --> Issues --> Agent Credential --> Verified by --> Merchant/Platform

Status: This is a testing/development product. APIs and schemas may change.

Critical Rules

Package Names

• TypeScript: @belticlabs/kya (NOT kya or beltic)
• Python: beltic-sdk (NOT beltic or kya)

CLI Flags

• --alg (NOT --algorithm)
• --out (NOT --output)
• --key, --payload, --pub (correct)

Platform Directory

DO NOT EDIT anything in platform/ directory. Read-only reference only.

Git Commits

• Commit as: pranav-beltic
• Use conventional commits: feat:, fix:, docs:, refactor:
• Always update CHANGELOG.md for user-facing changes

Monorepo Navigation

Cross-Repository Change Order

When changes affect multiple repos, follow this order:

1. beltic-spec first (schema changes)
2. beltic-sdk and fact-python (SDK updates)
3. beltic-cli (CLI changes)
4. kya-platform (platform changes)
5. nasa (documentation)

Key Files

• context.md - Comprehensive ecosystem context
• {repo}/CLAUDE.md - Repository-specific guidance
• beltic-spec/schemas/ - JSON Schema definitions

CLI Quick Reference

Typical Workflow

beltic init                              # Create .beltic.yaml
beltic fingerprint                       # Generate code fingerprint
beltic keygen --alg EdDSA               # Generate keypair
beltic sign --key .beltic/eddsa-*-private.pem --payload agent-manifest.json
beltic verify --key .beltic/eddsa-*-public.pem --token credential.jwt

SDK Patterns

TypeScript (@belticlabs/kya)

import {
  validateAgentCredential,
  validateDeveloperCredential,
  signCredential,
  verifyCredential,
  verifyAgentTrustChain,
  signHttpRequest,
  generateKeyPair,
} from '@belticlabs/kya';

// Trust chain verification
const result = await verifyAgentTrustChain(agentToken, {
  keyResolver: async (header) => publicKey,
  fetchDeveloperCredential: async (id) => developerJwt,
  policy: {
    minKybTier: 'tier_1',
    minPromptInjectionScore: 80,
  },
});

Python (beltic-sdk)

from beltic import (
    validate_agent_credential,
    validate_developer_credential,
    sign_credential,
    verify_credential,
    verify_agent_trust_chain,
    sign_http_request,
)

# Trust chain verification
result = await verify_agent_trust_chain(
    agent_token,
    TrustChainOptions(
        key_resolver=resolve_key,
        fetch_developer_credential=fetch_dev_cred,
        policy=TrustPolicy(
            min_kyb_tier="tier_1",
            min_prompt_injection_score=80,
        ),
    ),
)

Safety Concepts

Four Robustness Metrics (0-100 scores)

Calculation: Score = (1 - Attack Success Rate) x 100

KYB Tiers

Assurance Levels

• self_attested: Developer claims without verification
• beltic_verified: Beltic validates through evaluation
• third_party_verified: Independent auditor verification

Sensitive Operations - PROMPT USER

ALWAYS ask user confirmation before:

Key Operations

• Generating new keypairs (beltic keygen)
• Signing credentials (beltic sign)
• Deleting or rotating keys
• Modifying .beltic/ directory contents

Code Modifications

• Changes to cryptographic code (signing, verification)
• Modifications to schema definitions in beltic-spec/schemas/
• Changes to SDK verification logic
• Modifications to trust chain validation

Platform Changes

• Any modifications to kya-platform/ API routes
• Database schema changes (Drizzle migrations)
• Authentication/authorization logic changes
• Webhook handler modifications

When Agent Cannot Proceed

If an operation requires:

• Access to private keys the agent doesn't have
• Platform authentication the agent cannot perform
• Manual verification steps (KYB, safety evaluation)
• Human judgment on security decisions

Tell the user clearly:

I cannot perform [operation] because [reason].
To proceed, you would need to [specific action required].

Security Rules

Never Commit

• Private keys (.pem files with "private" in name)
• API keys, secrets, tokens
• .env files with credentials
• credentials.json files

Never Log

• Private key contents
• API keys or tokens
• Credential payloads with sensitive data
• User PII

Always Validate

• File paths before reading/writing
• JSON/YAML before parsing
• Credential schemas before signing
• Signatures before trusting credentials

Secure Defaults

• Reject algorithm none (always)
• Use Ed25519 (EdDSA) for new keys
• Set file permissions to 0600 for private keys
• Require HTTPS for production endpoints

Cryptographic Standards

• Algorithms: ES256 (P-256), EdDSA (Ed25519)
• Format: JWS/JWT with W3C VC-compatible structure
• DIDs: did:web, did:key, did:ion
• Revocation: W3C Status List 2021
• HTTP Signatures: RFC 9421

Reference Files

For detailed information, see:

• Repository Details - Per-repo patterns and guidance
• Credential Schemas - Schema field specifications
• API Endpoints - KYA Platform API reference
• Error Codes - Validation and signature error codes

Quick Troubleshooting

Development Status

This is an in-development product. Expect:

• API changes between versions
• Schema updates requiring re-signing
• New features being added
• Documentation gaps

When unsure about implementation details:

1. Check context.md for comprehensive context
2. Read the relevant repository's CLAUDE.md
3. Look at existing code patterns
4. Ask the user for clarification