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

Repository	Purpose	Language
beltic-spec	JSON schemas & specification	JSON Schema
beltic-cli	CLI for signing/verification	Rust
beltic-sdk	TypeScript SDK	TypeScript
fact-python	Python SDK	Python
kya-platform	Verification platform & API	TS/Next.js/Hono
wizard	Claude-powered credential bootstrap	TypeScript
nasa	Documentation site	MDX/Next.js
homebrew-tap	Homebrew formula	Ruby
platform	Enterprise risk platform	DO NOT EDIT

Cross-Repository Change Order

When changes affect multiple repos, follow this order:

beltic-spec first (schema changes)
beltic-sdk and fact-python (SDK updates)
beltic-cli (CLI changes)
kya-platform (platform changes)
nasa (documentation)

Key Files

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

CLI Quick Reference

Command	Description
`beltic init`	Create agent manifest interactively
`beltic dev-init`	Create self-attested developer credential
`beltic fingerprint`	Generate SHA256 code fingerprint
`beltic keygen --alg EdDSA`	Generate Ed25519 keypair
`beltic sign --key KEY --payload FILE`	Sign credential as JWS
`beltic verify --key KEY --token FILE`	Verify JWS token
`beltic http-sign`	Sign HTTP request (RFC 9421)
`beltic sandbox`	Run compliance tests
`beltic auth login`	Authenticate with KYA platform

Typical Workflow

bash

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)

typescript

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)

python

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)

Metric	Description
`harmfulContentRefusalScore`	Refusal of harmful content requests
`promptInjectionRobustnessScore`	Resistance to prompt injection attacks
`toolAbuseRobustnessScore`	Prevention of tool misuse
`piiLeakageRobustnessScore`	Protection against PII extraction

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

KYB Tiers

Tier	Name	Verification Level
`tier_0`	Unverified	Self-attested only
`tier_1`	Basic	Email/domain verified
`tier_2`	Standard	Identity documents
`tier_3`	Enhanced	Background checks
`tier_4`	Maximum	Regulated industries

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

Issue	Solution
`SIG-003: Algorithm none not allowed`	Use `--alg EdDSA` or `--alg ES256`
Schema validation fails	Run `npm run validate:all` in beltic-spec
Key not found	Check `.beltic/` directory for PEM files
HTTP signature fails	Verify key directory URL is accessible
Trust chain fails	Check developer credential is valid and not revoked

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:

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

beltic-kya

NPX Install

Tags

SKILL.md Content