为AI代理提供基于域锚的加密身份验证,采用ES256 JWT、TOFU密钥固定、撤销和委托链检查。
AgentPin Development Switch Fuility Guide.Purpose : 本指南帮助AI助手与AgentPin合作,进行域-安控加是一项面向实际任务的技能,主要用于Full Documents : 见RE.。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
目的:本指南帮助 AI 助手使用 AgentPin 实现面向领域的加密代理身份验证。
完整文档请参阅:README 文件与技术规范文档。
AgentPin 是一种面向领域的加密身份协议,专为 AI 代理设计。它使组织能够为其代理发布可验证的身份文档、签发短期有效的 JWT 凭据,并通过包含 TOFU 密钥绑定(Trust-On-First-Use)、吊销检查及委托链验证的多步协议来验证代理身份。
属于 ThirdKey 信任栈的一部分:SchemaPin(工具完整性)→ AgentPin(代理身份)→ Symbiont(运行时)
组织 验证方
──────────── ───────────────
1. 生成 ECDSA P-256 密钥对
2. 在 /.well-known/agent-identity.json 发布代理身份 3. 从 /.well-known/agent-identity.json 发现身份
4. 签发 JWT 凭据 5. 验证凭据(12 步流程)
(ES256 签名,短期有效) - JWT 解析与 ES256 签名验证
- 域绑定检查
- TOFU 密钥绑定
- 吊销检查
- 能力验证
- 委托链验证
crates/ ├── agentpin/ 核心库(无强制 HTTP 依赖) ├── agentpin-cli/ CLI 可执行程序(密钥生成、签发、验证、打包) └── agentpin-server/ Axum 服务器,用于提供 .well-known 端点
# 生成密钥
cargo run -p agentpin-cli -- keygen
--output-dir ./keys --agent-name "my-agent"
# 签发凭据(ES256 JWT,1 小时 TTL)
cargo run -p agentpin-cli -- issue
--key ./keys/my-agent.private.pem
--issuer "https://example.com"
--agent-id "my-agent"
--capabilities read,write --ttl 3600
# 离线验证
cargo run -p agentpin-cli -- verify
--credential ./credential.jwt
--discovery ./agent-identity.json
# 在线验证(自动从 .well-known 获取)
cargo run -p agentpin-cli -- verify
--credential ./credential.jwt --domain example.com
# 为离线/气隙环境创建信任包
cargo run -p agentpin-cli -- bundle
--discovery ./agent-identity.json
--revocation ./revocations.json --output ./bundle.json
use agentpin::{
crypto,
credential::CredentialBuilder,
verification::verify_credential,
pinning::KeyPinStore,
};
let (private_key, public_key) = crypto::generate_keypair()?;
let credential = CredentialBuilder::new()
.issuer("https://example.com")
.agent_id("my-agent")
.capability("read")
.capability("write")
.ttl_secs(3600)
.sign(&private_key)?;
let result = verify_credential(&credential, &discovery_doc, &pin_store)?;
npm install agentpin
import {
generateKeypair, issueCredential, verifyCredential,
KeyPinStore
} from 'agentpin';
// 生成 ECDSA P-256 密钥对
const { privateKey, publicKey } = await generateKeypair();
// 签发凭据
const credential = await issueCredential(privateKey, {
issuer: 'https://example.com',
agentId: 'my-agent',
capabilities: ['read', 'write'],
ttlSecs: 3600,
});
// 验证
const pinStore = new KeyPinStore();
const result = await verifyCredential(credential, discoveryDoc, pinStore);
pip install agentpin
from agentpin.crypto import generate_keypair
from agentpin.credential import issue_credential
from agentpin.verification import verify_credential
from agentpin.pinning import KeyPinStore
private_key, public_key = generate_keypair()
credential = issue_credential(
private_key,
issuer="https://example.com",
agent_id="my-agent",
capabilities=["read", "write"],
ttl_secs=3600,
)
pin_store = KeyPinStore()
result = verify_credential(credential, discovery_doc, pin_store)
cargo run -p agentpin-server --
--identity ./agent-identity.json
--revocation ./revocations.json
--port 3000
提供以下端点:
GET /.well-known/agent-identity.json(Cache-Control: max-age=3600)GET /.well-known/agent-identity-revocations.json(Cache-Control: max-age=300)GET /health| 模块 | 用途 |
|---|---|
crypto |
ECDSA P-256 签名/验证(不依赖外部 JWT crate) |
types |
核心数据结构(代理、凭据、能力) |
credential |
JWT 签发与解析 |
discovery |
代理身份文档的发布与解析 |
verification |
12 步凭据验证流程 |
revocation |
检查已被吊销的凭据/代理/密钥 |
pinning |
基于 JWK 指纹的 TOFU 密钥绑定 |
delegation |
委托链验证 |
mutual |
挑战-响应式双向身份认证(128 位随机数) |
jwk |
JWK 处理与指纹计算 |
resolver |
可插拔的身份发现解析器 |
| 操作 | Rust | JavaScript | Python |
|---|---|---|---|
| 生成密钥 | crypto::generate_keypair() |
generateKeypair() |
generate_keypair() |
| 签发凭据 | CredentialBuilder::new().sign() |
issueCredential() |
issue_credential() |
| 验证凭据 | verify_credential() |
verifyCredential() |
verify_credential() |
| 密钥绑定 | KeyPinStore |
KeyPinStore |
KeyPinStore |
| 信任包 | TrustBundle::from_json() |
TrustBundle.fromJson() |
TrustBundle.from_json() |
| 双向认证 | MutualAuth::challenge() |
createChallenge() |
create_challenge() |
| 特性 | 用途 |
|---|---|
fetch |
启用 reqwest 实现在线发现(HTTP) |
| (默认) | 核心库,无任何 HTTP 依赖 |
AgentPin 仅使用 ES256(ECDSA P-256),拒绝所有其他签名算法。该限制在代码中内联实现,不依赖外部 JWT crate。
凭据验证流程包括以下步骤:
首次为某域名验证凭据时,将代理的公钥(JWK 指纹)进行绑定。后续对该域名的验证若发现密钥不一致,则直接拒绝——以此检测密钥替换攻击。
代理可将其部分能力委托给子代理。委托链验证确保:
采用挑战-响应协议,配合 128 位随机数,实现代理之间的双向身份验证。
发布于 /.well-known/agent-identity.json:
{
"schema_version": "0.2",
"domain": "example.com",
"agents": [
{
"agent_id": "my-agent",
"display_name": "My Agent",
"description": "A helpful agent",
"capabilities": ["read", "write"],
"public_key_jwk": { ... },
"constraints": {
"max_ttl_secs": 86400,
"allowed_scopes": ["api"]
}
}
],
"revocation_endpoint": "https://example.com/.well-known/agent-identity-revocations.json",
"directory_listing": true
}
预先打包发现文档与吊销数据,适用于无互联网连接的环境:
from agentpin.bundle import TrustBundle
bundle = TrustBundle.from_json(bundle_json_str)
discovery = bundle.find_discovery("example.com")
revocation = bundle.find_revocation("example.com")
from agentpin.discovery import (
WellKnownResolver, # 基于 HTTP 的 .well-known 查找
DnsTxtResolver, # 基于 DNS TXT 记录的查找
ManualResolver, # 手动预配置的发现数据
)
域名可在发现文档中通过 "directory_listing": true 公告其全部代理。验证方可先枚举可用代理,再发起挑战。
# 构建全部 crate cargo build --workspace # 运行全部测试 cargo test --workspace # 代码检查(lint) cargo clippy --workspace # 格式检查 cargo fmt --check
cargo clippy --workspace 必须零警告通过cargo fmt --check 必须通过#[cfg(test)] mod tests)fetch 特性启用 reqwestfetch 特性;默认为离线就绪