# @agenticprimitives/key-custody 中文文档

规范地址：https://npmcn.com/package/%40agenticprimitives/key-custody/

版本：1\.0\.0-alpha\.46
npm 元数据更新时间：2026-10-26T11:49:29.543Z
中文译文更新时间：2026-11-06T01:49:22.470Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agenticprimitives/key-custody
原文对照：https://npmcn.com/package/%40agenticprimitives/key-custody/?lang=original
项目主页：https://agenticprimitives.dev/
源码仓库：https://github.com/agentictrustlabs/agenticprimitives

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：345 kB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：viem ^2\.52\.2，@agenticprimitives/audit ^1\.0\.0-alpha\.46，@agenticprimitives/types ^1\.0\.0-alpha\.46，@agenticprimitives/connect-auth ^1\.0\.0-alpha\.46
- 首次发布：2026-05-31T17:12:51.465Z
- 最新版本发布：2026-10-26T11:49:26.625Z
- 近 30 天下载量：7003（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

可插件信封加密+签名人+HMAC供应商(本地-AES / AWS KMS / GCP KMS / AKCS代理-kms). 纯密码原始人;没有会话生命周期(即代表团).

## 安装

```sh
npm install @agenticprimitives/key-custody
```

也可以使用：`pnpm add @agenticprimitives/key-custody`、`yarn add @agenticprimitives/key-custody`、`bun add @agenticprimitives/key-custody`

## README

# @ agenticprimitives/ 钥匙保管

> 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers)

**监护权不是权威.**

在这个堆栈中,密钥符号——它们不会决定. 当局以代表团和保管政策为单位;这个软件包是其下面的密码层:可插入信封加密、KMS支持的签名器和HMAC供应商背后的 `A2AKeyProvider` 接口。 本地-AES和本地的secp256k1标志用于开发,AWS KMS和GCP KMS用于实际部署. 因为这里的签人只是一个签人,一个失密的会话密钥是撤销事件,而不是身份丢失——"智能特工"地址及其保管政策坐落在密钥上,而不是其中.

**比你想象的要小 故意:** 会话生命周期为 `@agenticprimitives/delegation`。这个软件包提供原始密码 `SessionManager` 电线[ADR-0002 (韩语)](https://npmcn.com/package/docs/architecture/decisions/0002-session-lifecycle-in-delegation.md)) (中文(简体) ). 有效载荷是带有调用器提供AAD的不透明字节——同样绑入了AES-GCM AAD和KMS加密康特特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克特克.

> 部分 [代理原始产品](https://npmcn.com/package/README.md) ——代理经济的信托基底:一个有监护,授权,命名,证书,审计证据的犬类智能代理身份,设计成一个系统.

见 [`spec.md`](https://npmcn.com/package/%40agenticprimitives/key-custody/spec.md) → [`specs/203-key-custody.md`](https://npmcn.com/package/specs/203-key-custody.md)。 。 。 .

## 快开始

```ts
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区](https://npmcn.com/package/specs/235-google-kms-custody.md)),是任何签名呼号上投出的唯一中继主签名符 (`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` 在远程错误中.

```ts
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=production`AWS、GCP和 `agentic-kms` 后端有 **没有本地倒计时** - 关机故障 这是有意的:无声地降级到更弱后端的密钥-保管层不是保管层.

## 怎么不一样

Twitchey和Fireblocks是强大的保管产品:用自己的政策引擎、控制台和信任模式管理的关键基础设施。 这些也是你的权威模式最终存在的地方——支配关键的政策是供应商的政策,用供应商的话说。 这个包采取相反的位置: KMS后端是可互换的管道(`buildKeyProvider({ backend })`此外,当局模式在链上保管政策和EIP-712代表团中上一层楼,其余部分执行和审计。 你保留云 -KMS级的密钥保护 不使一个卖家的政策引擎 你的真实来源 谁可以做什么.

## 校验

```bash
pnpm --filter @agenticprimitives/key-custody typecheck
pnpm --filter @agenticprimitives/key-custody test
```

## 状态

测试网/飞行员准备 生产启动在基础README的公开核对表上进行——包括第三方合同审计和治理关键轮换。 追踪所有安全发现 [`docs/audits/findings.yaml`](https://npmcn.com/package/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` (固定装置), `AgenticKmsError`ES256号: `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`。 。 。 .

## 常见问题

### @agenticprimitives/key-custody 是什么？

可插件信封加密\+签名人\+HMAC供应商\(本地-AES / AWS KMS / GCP KMS / AKCS代理-kms\)\. 纯密码原始人;没有会话生命周期\(即代表团\)\.

### 如何安装 @agenticprimitives/key-custody？

在项目目录运行 npm install @agenticprimitives/key-custody，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agenticprimitives/types（^1\.0\.0-alpha\.46）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 ap-provision-gcp，可以用 npx ap-provision-gcp 直接运行。

### @agenticprimitives/key-custody 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agenticprimitives/key-custody 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agenticprimitives/key-custody 可以商用吗？

@agenticprimitives/key-custody 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agenticprimitives/key-custody 的下载量有多少？

根据 npm 官方下载统计，@agenticprimitives/key-custody 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,003 次，日均约 233 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agenticprimitives/key-custody 还在维护吗？

最新版本 1\.0\.0-alpha\.46 发布于 2026/10/26（10 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 45 个；首次发布于 2026/06/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。