为AI代理提供基于域锚的加密身份验证,采用ES256 JWT、TOFU密钥固定、撤销和委托链检查。
AgentPin Development Switch Fuility Guide.Purpose : 本指南帮助AI助手与AgentPin合作,进行域-安控加
功能概述
AgentPin Development Switch Fuility Guide.Purpose : 本指南帮助AI助手与AgentPin合作,进行域-安控加是一项面向实际任务的技能,主要用于Full Documents : 见RE.。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
核心要点
- 使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。
- 该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。
- 从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
使用与执行
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
结果检查与注意事项
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。
AgentPin 开发技能指南
目的:本指南帮助 AI 助手使用 AgentPin 实现面向领域的加密代理身份验证。
完整文档请参阅:README 文件与技术规范文档。
AgentPin 的功能
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 端点
按语言快速上手
Rust(CLI)
# 生成密钥
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
Rust(库)
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)?;
JavaScript
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);
Python
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)
提供 .well-known 端点服务
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
核心库 API
关键模块
| 模块 | 用途 |
|---|---|
crypto |
ECDSA P-256 签名/验证(不依赖外部 JWT crate) |
types |
核心数据结构(代理、凭据、能力) |
credential |
JWT 签发与解析 |
discovery |
代理身份文档的发布与解析 |
verification |
12 步凭据验证流程 |
revocation |
检查已被吊销的凭据/代理/密钥 |
pinning |
基于 JWK 指纹的 TOFU 密钥绑定 |
delegation |
委托链验证 |
mutual |
挑战-响应式双向身份认证(128 位随机数) |
jwk |
JWK 处理与指纹计算 |
resolver |
可插拔的身份发现解析器 |
各语言 API 参考
| 操作 | 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() |
特性标志(Feature Flags)
| 特性 | 用途 |
|---|---|
fetch |
启用 reqwest 实现在线发现(HTTP) |
| (默认) | 核心库,无任何 HTTP 依赖 |
关键概念
仅支持 ES256
AgentPin 仅使用 ES256(ECDSA P-256),拒绝所有其他签名算法。该限制在代码中内联实现,不依赖外部 JWT crate。
12 步验证流程
凭据验证流程包括以下步骤:
- JWT 结构解析
- 头部算法校验(仅允许 ES256)
- 签名验证
- 颁发者域名提取
- 身份发现文档解析
- 域绑定验证
- 密钥匹配(颁发者密钥 vs 发现文档中声明的密钥)
- TOFU 密钥绑定检查
- 过期时间验证
- 吊销状态检查
- 能力范围验证
- 委托链验证(如存在)
TOFU 密钥绑定
首次为某域名验证凭据时,将代理的公钥(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
}
v0.2.0 新特性
信任包(离线 / 气隙环境)
预先打包发现文档与吊销数据,适用于无互联网连接的环境:
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
开发约定
- Rust Edition 2021,最低支持 Rust 版本(MSRV)为 1.70
cargo clippy --workspace必须零警告通过cargo fmt --check必须通过- 单元测试内联于源文件中(
#[cfg(test)] mod tests) - 仅支持 ES256 —— 拒绝所有其他签名算法
- HTTP 功能按特性标志控制:
fetch特性启用 reqwest
AI 助手实用建议
- 仅使用 ES256 —— 切勿接受 RS256、HS256 或任何其他签名算法
- 短期凭据 —— 推荐 TTL 设置为小时级,而非天级
- 始终检查吊销状态 —— 在信任凭据前必须完成吊销检查
- TOFU 密钥绑定 —— 首次见到的密钥即被信任;密钥变更时应发出警告
- 委托链应收缩能力范围 —— 不得扩大原始能力集
- 不依赖外部 JWT crate —— 算法校验逻辑内联实现,防止算法混淆攻击
- HTTP 功能需按特性启用 —— 仅当需要在线发现时启用
fetch特性;默认为离线就绪 - 与 SchemaPin 兼容 —— 二者均采用 ECDSA P-256,共享相同密码学原语
- 信任包适用于 CI/CD 与气隙部署 —— 可预先打包发现与吊销数据
- JavaScript 与 Python SDK 提供与 Rust crate 完全一致的验证保障
热门AI工具
相关专题
本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。
0
2026.11.17
本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.17
本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。
0
2026.11.17
SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。
0
2026.11.17
SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。
0
2026.11.17
SQLAlchemy ORM 模型怎么写?本专题整理模型类定义、Mapped 字段映射、主键与约束、表结构创建和常见报错的相关文章,帮助你从基础配置到实际建模逐步掌握 SQLAlchemy。
0
2026.11.17
本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。
0
2026.11.12
本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.12
本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。
0
2026.11.12
热门下载
相关下载
精品课程
最新文章