# @btravstack/keys 中文文档

规范地址：https://npmcn.com/package/%40btravstack/keys/

版本：0\.58\.0
npm 元数据更新时间：2026-11-07T21:12:14.252Z
中文译文更新时间：2026-11-08T18:41:22.278Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40btravstack/keys
原文对照：https://npmcn.com/package/%40btravstack/keys/?lang=original
项目主页：https://github.com/btravstack/btravstack#readme
源码仓库：https://github.com/btravstack/btravstack

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

- 包体积（解压后）：48 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：unthrown ^5\.0\.0，@btravstack/di ^0\.58\.0，@btravstack/core ^0\.58\.0，@btravstack/config ^0\.58\.0，@aws-sdk/client-kms ^3\.1000\.0
- 首次发布：2026-10-21T07:13:19.666Z
- 最新版本发布：2026-11-07T21:12:13.914Z
- 近 30 天下载量：4308（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

@btravstack/ core 的 EnvelopeKeys 端口: 由主人的 AWS KMS 密钥包裹的每个所有者的根密钥, 解开内存并缓存为 TTL, 并删除一个密钥, 以及 HKDF 助手给出每个目的的密钥

## 安装

```sh
npm install @btravstack/keys
```

也可以使用：`pnpm add @btravstack/keys`、`yarn add @btravstack/keys`、`bun add @btravstack/keys`

## README

# @btravstack/ 键

> 一个 `EnvelopeKeys` 用于 [`@btravstack/core`](https://npmcn.com/package/%40btravstack/core): 每根密钥 拥有者,世代相传,由该拥有者的 AWS KMS 密钥包裹——未被包入 内存和缓存为 TTL, 用一个密钥删除被删除—— 和一个 HKDF 助手给每个目的 自己的钥匙.

📖 **[文档](https://btravstack.github.io/btravstack/reference/keys)** • 妇女 [API 参考](https://btravstack.github.io/btravstack/api/keys/)

```sh
pnpm add @btravstack/keys @btravstack/core @btravstack/config @btravstack/di unthrown
pnpm add @aws-sdk/client-kms # for @btravstack/keys/kms
```

任何依赖都是同龄人 `@aws-sdk/client-kms` 可选的: `@btravstack/keys/kms` 进口.

## 实例

将租户的有效载荷密封在租户自己的钥匙下的一个港口,以及 提供密钥的构成:

```ts
import type { webcrypto } from "node:crypto";

import {
  EnvelopeKeys,
  deriveKey,
  type InvalidKeyPurpose,
  type KeyErased,
  type KeyGeneration,
  type KeysUnavailable,
} from "@btravstack/keys";
import { kmsKeys } from "@btravstack/keys/kms";

class PayloadKeys extends Port("ReadmePayloadKeys")<{
  readonly key: (
    generation: KeyGeneration,
  ) => AsyncResult<webcrypto.CryptoKey, KeyErased | KeysUnavailable | InvalidKeyPurpose>;
}> {}

export const payloadKeys = Provider(PayloadKeys)({
  inject: { keys: EnvelopeKeys },
  sync: ({ keys }) => ({
    key: (generation) =>
      keys.rootKey(generation).flatMap((root) =>
        deriveKey(root, { namespace: "payloads", purpose: "seal", version: 1 }, {
          algorithm: { name: "AES-GCM", length: 256 },
          usages: ["encrypt", "decrypt"],
        }),
      ),
  }),
});

export const Sealing = Module("ReadmeSealing")({
  imports: [kmsKeys()],
  provides: [payloadKeys],
  exports: [PayloadKeys],
});
```

提供一代人,轮流, 消除租户在一个电话和规模化 缓存是 [每个拥有者保留信封密钥](https://btravstack.github.io/btravstack/how-to/keep-envelope-keys-per-owner)。 。 。 .

## 选项

| 选项 | 何处 | 这是什么 |
| --- | --- | --- |
| `KEYS_KMS_REGION` | 环境 | 拥有者的 KMS 密钥区域—— 需要 |
| `KEYS_KMS_ALIAS_PREFIX` | 环境 | 车主的 KMS 密钥是 `<prefix><owner>` 所需数额 |
| `KEYS_KMS_ENDPOINT` | 环境 `endpoint` | 模拟器或 VPC 端点( 默认: AWS 本身) |
| `KEYS_CACHE_TTL_MS` | 环境 `cacheTtlMs` | 未包装根保存时间( 默认为 5 分钟) |
| `KEYS_KMS_PENDING_WINDOW_DAYS` | 环境 `pendingWindowDays` | 取消的天数(默认) `30`(中文(简体) ) |
| `clock` | `kmsKeys({ … })` | 缓存的 TTL 是用什么来衡量的 |

完整表——默认,语义和推理——活在 [参考页](https://btravstack.github.io/btravstack/reference/keys), (中文(简体) ), 这张名单是详细的.

## 它决定什么,它没有

**决定** 一代是一个 KMS 数据密钥, 受加密的约束 上下文 `{ owner, keyId }`因此,为另一个所有者或密钥 id 呈现的blob 是 拒绝而不是被解开; 禁用、删除、丢失或拒绝 键为已键 `KeyErased` 和任何其他 KMS 说一个打字 `KeysUnavailable`;删除所有者是预定删除的密钥 向每个 KMS 请求报告 `Observers`; 并且一个衍生的密钥是 HKDF-SHA-256号机车 `info = <namespace>/<purpose>/v<version>`。 。 。 .

**它没有决定** 在那座乐园里,有俘虏的世代 下一个加密, 或如何创建所有者的 KMS 密钥: 这些是 应用程序和平台。 理由是 [`AGENTS.md`](https://npmcn.com/package/%40btravstack/keys/AGENTS.md)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @btravstack/keys 是什么？

@btravstack/ core 的 EnvelopeKeys 端口: 由主人的 AWS KMS 密钥包裹的每个所有者的根密钥, 解开内存并缓存为 TTL, 并删除一个密钥, 以及 HKDF 助手给出每个目的的密钥

### 如何安装 @btravstack/keys？

在项目目录运行 npm install @btravstack/keys，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unthrown（^5\.0\.0）、@btravstack/di（^0\.58\.0）、@btravstack/core（^0\.58\.0）、@btravstack/config（^0\.58\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @btravstack/keys 支持 TypeScript 吗？

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

### @btravstack/keys 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @btravstack/keys 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @btravstack/keys 可以商用吗？

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

### @btravstack/keys 的下载量有多少？

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

### @btravstack/keys 还在维护吗？

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