@ agenticprimitives/ 钥匙保管
部分 代理先导 ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. 开发者工具包 • 妇女 所有软件包
监护权不是权威.
在这个堆栈中,密钥符号——它们不会决定. 当局以代表团和保管政策为单位;这个软件包是其下面的密码层:可插入信封加密、KMS支持的签名器和HMAC供应商背后的 A2AKeyProvider 接口。 本地-AES和本地的secp256k1标志用于开发,AWS KMS和GCP KMS用于实际部署. 因为这里的签人只是一个签人,一个失密的会话密钥是撤销事件,而不是身份丢失——"智能特工"地址及其保管政策坐落在密钥上,而不是其中.
比你想象的要小 故意: 会话生命周期为 @agenticprimitives/delegation。这个软件包提供原始密码 SessionManager 电线ADR-0002 (韩语)) (中文(简体) ). 有效载荷是带有调用器提供AAD的不透明字节——同样绑入了AES-GCM AAD和KMS加密康特特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克.
部分 代理原始产品 ——代理经济的信托基底:一个有监护,授权,命名,证书,审计证据的犬类智能代理身份,设计成一个系统.
见 spec.md → specs/203-key-custody.md。 。 。 .
快开始
import { buildKeyProvider, buildSignerBackend, createKmsAccount, canonicalContextBytes } from '@agenticprimitives/key-custody';
const provider = buildKeyProvider({ backend: process.env.A2A_KMS_BACKEND });
// Generate a wrapped data key for envelope encryption
const { plaintextDataKey, encryptedDataKey, keyId, keyVersion } =
await provider.generateSessionDataKey({ aadContext: { /* caller-supplied */ } });
// Sign as a viem-compatible signer
const signer = buildSignerBackend({ backend: 'aws-kms' });
const kmsAccount = await createKmsAccount(signer);
基本内容之外:通过HKDF生成的每个OIDC主题符号(deriveSubjectSigner, (中文(简体) ), 第235区),是任何签名呼号上投出的唯一中继主签名符 (getRelayOnlySigner,以及HMAC 的供应商 /mac 子路径。 每次解密和签名操作都会发出审计行 keyVersion 和一个散列会话ID——原始会话ID从未被登录.
agentic-kms ——代理密钥保管服务后端
backend: 'agentic-kms' 路由信封数据密钥、MAC、生成的密钥签名和每个主体
aKCS部署的衍生签名人(基于HSM的保密-VM保管;repo) faithkms) (中文(简体) ).
适配器是 fetch + Web Crypto 只——无云 SDK——并保留每个软件包规则:秘密是
Uint8Array,私密密钥在此过程中从未存在,并且有 无后退 改为 local-aes
或者说 gcp-kms 在远程错误中.
import { buildKeyProvider, deriveSubjectSigner, staticTokenProvider, loadSecret } from '@agenticprimitives/key-custody';
const agenticKms = {
baseUrl: 'https://akcs.example.internal',
tenantId: 'my-tenant',
tokenProvider: () => getWorkloadToken(), // short-lived JWT for the AKCS audience
// dev only: staticTokenProvider(loadSecret(env.AKCS_TOKEN))
acceptedProtectionLevels: ['CVM_DERIVED', 'CVM_WRAPPED'], // add 'DEV_LOCAL' only in dev
};
const provider = buildKeyProvider({ backend: 'agentic-kms', agenticKms });
const signer = deriveSubjectSigner({ backend: 'agentic-kms', agenticKms, subject: { iss, sub } });
准确 ap-oidc-custodian-secp256k1-v1 aKCS内部的衍生; 遗产
A2A_MASTER_PRIVATE_KEY/ 保管根通过经过核实的操作员仪式从那里导入,所以
保留现有地址。 跨语言向量生活在 test/vectors/。 。 。 .
生产警卫
local-aes 拒绝启动时 NODE_ENV=productionAWS、GCP和 agentic-kms 后端有 没有本地倒计时 - 关机故障 这是有意的:无声地降级到更弱后端的密钥-保管层不是保管层.
怎么不一样
Twitchey和Fireblocks是强大的保管产品:用自己的政策引擎、控制台和信任模式管理的关键基础设施。 这些也是你的权威模式最终存在的地方——支配关键的政策是供应商的政策,用供应商的话说。 这个包采取相反的位置: KMS后端是可互换的管道(buildKeyProvider({ backend })此外,当局模式在链上保管政策和EIP-712代表团中上一层楼,其余部分执行和审计。 你保留云 -KMS级的密钥保护 不使一个卖家的政策引擎 你的真实来源 谁可以做什么.
校验
pnpm --filter @agenticprimitives/key-custody typecheck
pnpm --filter @agenticprimitives/key-custody test
状态
测试网/飞行员准备 生产启动在基础README的公开核对表上进行——包括第三方合同审计和治理关键轮换。 追踪所有安全发现 docs/audits/findings.yaml。 。 。 .
P-256 签名端口
JwsSignerPort 是第二个签名端口: ES256 超过 SHA-256 一个消息,原始 r || s低调 低调, kid = RFC 7638
拇指印——对于实地验证的密钥(一个JWS,一个OpenAC设备绑定,一个证书签发者). LocalEs256Signer 实值
双人测试 在生产过程中,钥匙生活在代理-kms钥匙服务和 createAkcsEs256Signer 绑定它:
- 设备密钥 (单位:千美元)
signingPurpose: 'ES256_SHA256',默认值)仅在下签名 约束性证据 a 包括: 编号摘要、地点和上游摘要,由@agenticprimitives/delegation演示文稿 审判后释放credential.present线. - 签发密钥 (单位:千美元)
signingPurpose: 'ES256_ISSUE_SHA256') 只在下面签名证书 出具证据 —— 说 表示摘要、发行人面和证书类型的符号.
设备密钥不能发行,而发行密钥不能出现:密钥服务拒绝其他目的. 每一个答案
以密钥的已公布点进行校验,然后返回. createAkcsP256Key 提供这种关键.
derivePairwiseSubject 每个公司或服务都给予个人一个稳定、无法联系的主题(usr_ + HKDF 超过 a
秘密在她的金库里, 被观众取盐),和 ExternalAccountLinkV1 记录她经纪人在一家公司持有的东西.
参考文献
出口. 接口 : A2AKeyProvider, (中文(简体) ), KmsAccountBackend, (中文(简体) ), KmsBackend, (中文(简体) ), BuildOpts。工厂: buildKeyProvider, (中文(简体) ),
buildSignerBackend, (中文(简体) ), buildMacProvider, (中文(简体) ), getRelayOnlySigner, (中文(简体) ), buildToolExecutorBackendNoIsolation (仅保留,拒绝使用)
生产; buildToolExecutorBackend 已贬值并投掷(它被忽略) toolId 并归还了主签.
每个主体( 第235段): deriveSubjectSigner, (中文(简体) ), subjectCanonicalMessage, (中文(简体) ), SubjectId, (中文(简体) ), DeriveSubjectOpts.viem适配器:
createKmsAccount。内设: LocalAesProvider, (中文(简体) ), LocalSecp256k1Signer, (中文(简体) ), GcpKmsProvider, (中文(简体) ), GcpKmsSigner, (中文(简体) ),
RemoteAgenticKmsProvider, (中文(简体) ), RemoteAgenticKmsSigner, (中文(简体) ), remoteSubjectSigner, (中文(简体) ), staticTokenProvider (固定装置),
AgenticKmsErrorES256号: JwsSignerPort, (中文(简体) ), LocalEs256Signer (dev/test;不生产即拒绝生产)
A2A_ALLOW_LOCAL_DEVICE_KEY=true, (中文(简体) ), p256JwkThumbprint, (中文(简体) ), verifyEs256, (中文(简体) ), AkcsEs256Signer, (中文(简体) ), createAkcsEs256Signer, (中文(简体) ),
createAkcsP256Key。光谱442: derivePairwiseSubject, (中文(简体) ), ExternalAccountLinkV1, (中文(简体) ), sessionStartDecision, (中文(简体) ),
revokeExternalAccountLink, (中文(简体) ), signInKindRefusal, (中文(简体) ), securityRowOf(原始内容存档于2018-10-21). AAD: canonicalContextBytes未导出 :
deriveSubjectPrivateKeyHex (模块-内部),以及AWS提供商和签名人(未执行的抛出根).
消费者安全KMS核心./kms-core, 第276页. src/kms/{secp256k1-core,gcp-transport,kms-core}.ts 这是
签署没有对等依赖的表面( 只有) @noble/*) (中文(简体) ). 外部应用程序导入 signDigestWithKms, (中文(简体) ), gcpSignDigest, (中文(简体) ),
createGcpKmsTransport 财务报告和审定财务报表 addressFromSpkiPem 从 @agenticprimitives/key-custody/kms-core 而不是内嵌一个 KMS
签名者. GcpKmsSigner 是一个薄的、经审计的包装; 密码留在核心中. test/unit/kms-core.test.ts
守护导入图.
这个 agentic-kms 适配器. RemoteAgenticKmsProvider (信封+MAC)和 RemoteAgenticKmsSigner (生成密钥和
每个主题的衍生符号) src/providers/agentic.ts 使用情况 fetch 和 Web 加密, 只需准时
TokenProvider永远不要回头 这个 ap-oidc-custodian-secp256k1-v1 衍生运行服务器侧; test/vectors/*.json
是和密钥服务共享的黄金向量。 外面的反应 acceptedProtectionLevels 被拒绝.
审计. key-custody.sign 当地和GCP签字人和ES256签字人; key-custody.envelope.{wrap,unwrap} 从
GcpKmsProvider,用 AAD 散列和会话 id 散列keccak256(sessionId)初出十八分 永远不要生.
共同任务. 一个新的 KMS 后端设备 A2AKeyProvider 内 src/providers/<backend>.ts,在
buildKeyProvider 并添加子路径导出 。 一个新的审计领域进入 src/audit.ts,并与 delegation。 。 。 .
密码更改需要安全审查, 纪录片: specs/203-key-custody.md。 。 。 .