beltic-kya

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beltic KYA Ecosystem

Beltic KYA 生态系统

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

KYA（Know Your Agent）是一个开发中的、面向AI Agent的基于凭证的信任框架，它通过加密可验证的凭证来建立信任关系。

Trust Chain

信任链

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

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

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

状态：这是一个测试/开发阶段的产品，API和Schema可能会发生变更。

Critical Rules

核心规则

Package Names

包名规范

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

TypeScript：
```
@belticlabs/kya
```
（禁止使用
```
kya
```
或
```
beltic
```
）
Python：
```
beltic-sdk
```
（禁止使用
```
beltic
```
或
```
kya
```
）

CLI Flags

CLI 参数规范

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

使用
```
--alg
```
（禁止使用
```
--algorithm
```
）
使用
```
--out
```
（禁止使用
```
--output
```
）
```
--key
```
、
```
--payload
```
、
```
--pub
```
为正确写法

Platform Directory

平台目录

DO NOT EDIT anything in

platform/

directory. Read-only reference only.

禁止编辑

platform/

目录下的任何内容，仅可作为只读参考。

Git Commits

Git 提交规范

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

提交者名称使用：
```
pranav-beltic
```
使用约定式提交格式：
```
feat:
```
、
```
fix:
```
、
```
docs:
```
、
```
refactor:
```
所有面向用户的变更必须更新CHANGELOG.md

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

代码仓库	用途	开发语言
beltic-spec	JSON Schema与规范定义	JSON Schema
beltic-cli	用于签名/验证的CLI工具	Rust
beltic-sdk	TypeScript SDK	TypeScript
fact-python	Python SDK	Python
kya-platform	验证平台与API	TS/Next.js/Hono
wizard	基于Claude的凭证引导工具	TypeScript
nasa	文档站点	MDX/Next.js
homebrew-tap	Homebrew 公式	Ruby
platform	企业风险平台	禁止编辑

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)

当变更涉及多个仓库时，请遵循以下顺序：

首先更新beltic-spec（Schema变更）
然后更新beltic-sdk和fact-python（SDK更新）
接着更新beltic-cli（CLI变更）
再更新kya-platform（平台变更）
最后更新nasa（文档更新）

Key Files

关键文件

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

```
context.md
```
- 完整的生态系统上下文说明
```
{repo}/CLAUDE.md
```
- 各仓库专属的使用指南
```
beltic-spec/schemas/
```
- JSON Schema定义文件

CLI Quick Reference

CLI 快速参考

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

命令	描述
`beltic init`	交互式创建Agent清单
`beltic dev-init`	创建自签名开发者凭证
`beltic fingerprint`	生成SHA256代码指纹
`beltic keygen --alg EdDSA`	生成Ed25519密钥对
`beltic sign --key KEY --payload FILE`	将凭证签名为JWS格式
`beltic verify --key KEY --token FILE`	验证JWS令牌
`beltic http-sign`	对HTTP请求进行签名（遵循RFC 9421）
`beltic sandbox`	运行合规性测试
`beltic auth login`	登录KYA平台进行身份验证

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

bash

beltic init                              # 创建.beltic.yaml文件
beltic fingerprint                       # 生成代码指纹
beltic keygen --alg EdDSA               # 生成密钥对
beltic sign --key .beltic/eddsa-*-private.pem --payload agent-manifest.json
beltic verify --key .beltic/eddsa-*-public.pem --token credential.jwt

SDK Patterns

SDK 使用模式

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,
  },
});

typescript

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

// 信任链验证
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,
)

python

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

// 信任链验证
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,
        ),
    ),
)

Trust chain verification

安全相关概念

—

四项鲁棒性指标（评分范围0-100）

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, ), ), )

---

指标	描述
`harmfulContentRefusalScore`	拒绝有害内容请求的能力
`promptInjectionRobustnessScore`	抵御提示注入攻击的能力
`toolAbuseRobustnessScore`	防止工具滥用的能力
`piiLeakageRobustnessScore`	防止PII（个人可识别信息）泄露的能力

计算方式：评分 = (1 - 攻击成功率) × 100

Safety Concepts

KYB 等级

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

等级	名称	验证级别
`tier_0`	未验证	仅自声明
`tier_1`	基础级	邮箱/域名验证
`tier_2`	标准级	身份证件验证
`tier_3`	增强级	背景调查
`tier_4`	最高级	适用于受监管行业

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

self_attested：开发者自行声明，未经过验证
beltic_verified：由Beltic通过评估进行验证
third_party_verified：由独立审计机构进行验证

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:

生成新的密钥对（
```
beltic keygen
```
）
签署凭证（
```
beltic sign
```
）
删除或轮换密钥
修改
```
.beltic/
```
目录下的内容

Key Operations

代码修改操作

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

修改加密相关代码（签名、验证逻辑）
修改
```
beltic-spec/schemas/
```
下的Schema定义
修改SDK中的验证逻辑
修改信任链验证逻辑

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

对
```
kya-platform/
```
下的API路由进行任何修改
数据库Schema变更（Drizzle迁移）
身份认证/授权逻辑变更
Webhook处理器修改

Platform Changes

当Agent无法继续操作时

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

如果某操作需要：

访问Agent无法获取的私钥
Agent无法完成的平台身份认证
手动验证步骤（KYB、安全评估）
基于安全决策的人工判断

请明确告知用户：

我无法执行[操作]，原因是[具体原因]。
如需继续，您需要执行[具体必要操作]。

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].

私钥（文件名包含"private"的.pem文件）
API密钥、机密信息、令牌
包含凭证的.env文件
```
credentials.json
```
文件

Security Rules

禁止记录的内容

Never Commit

—

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

私钥内容
API密钥或令牌
包含敏感数据的凭证负载
用户的PII信息

Never Log

必须执行的验证

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

读写文件前验证文件路径
解析前验证JSON/YAML格式
签署前验证凭证Schema
信任凭证前验证签名

Always Validate

安全默认配置

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

始终拒绝
```
none
```
算法
新密钥使用Ed25519（EdDSA）算法
私钥文件权限设置为0600
生产环境端点必须使用HTTPS

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

算法：ES256（P-256）、EdDSA（Ed25519）
格式：符合W3C VC规范的JWS/JWT格式
DID：did:web、did:key、did:ion
吊销机制：W3C Status List 2021
HTTP签名：遵循RFC 9421

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

如需详细信息，请查看：

仓库详情 - 各仓库的模式与指南
凭证Schema - Schema字段规范
API端点 - KYA平台API参考
错误码 - 验证与签名错误码说明

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

问题	解决方案
`SIG-003: Algorithm none not allowed`	使用 `--alg EdDSA` 或 `--alg ES256` 参数
Schema验证失败	在beltic-spec仓库中运行 `npm run validate:all` 命令
密钥未找到	检查 `.beltic/` 目录下的PEM文件
HTTP签名失败	验证密钥目录URL是否可访问
信任链验证失败	检查开发者凭证是否有效且未被吊销

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

这是一个开发中的产品，请注意：

不同版本间API可能会发生变更
Schema更新可能需要重新签署凭证
持续新增功能
可能存在文档缺失

当对实现细节不确定时：

查看
```
context.md
```
获取完整上下文
阅读对应仓库的
```
CLAUDE.md
```
文件
参考现有代码模式
向用户寻求澄清

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

—