# @happyvertical/smrt-secrets 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-secrets/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:55:23.322Z
中文译文更新时间：2026-11-17T09:36:21.265Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：394 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-06-23T01:18:44.746Z
- 最新版本发布：2026-11-17T07:55:23.145Z
- 近 30 天下载量：22964（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

为 SMRT 加密信封的租户保密管理

## 安装

```sh
npm install @happyvertical/smrt-secrets
```

也可以使用：`pnpm add @happyvertical/smrt-secrets`、`yarn add @happyvertical/smrt-secrets`、`bun add @happyvertical/smrt-secrets`

## README

# @happyvertical/smrt-secrets (欢快的垂直/秘密)

S-m-r-t框架带有信封加密的租户保密管理. 使用一个三层加密链:应用程序主密钥(AMK)包入每个租户的数据加密密钥(TDEK),该密钥加密单个秘密值.

## 安装

```bash
pnpm add @happyvertical/smrt-secrets
```

要求 `SMRT_SECRET_MASTER_KEY` 环境变量( 64 十六进制字符) 作为 AMK, 或 a `masterKeyProvider` (下) 过程没有环境读取.

## 使用量

```typescript
import { SecretService } from '@happyvertical/smrt-secrets';
import { withTenant } from '@happyvertical/smrt-tenancy';

// Create the service (reads AMK from env by default)
const service = await SecretService.create({ db });

await withTenant({ tenantId: 'tenant-123' }, async () => {
  // Store a secret (upserts if name already exists)
  await service.store('stripe-api-key', 'sk_live_xxx', {
    category: 'api-keys',
    description: 'Stripe production key',
    expiresAt: new Date('2027-01-01'),
  });

  // Retrieve and decrypt
  const { value, accessCount } = await service.retrieve('stripe-api-key');

  // List secret names (values never included)
  const secrets = await service.list({ category: 'api-keys' });

  // Disable/enable without deleting
  await service.disable('stripe-api-key');
  await service.enable('stripe-api-key');

  // Rotate the tenant's encryption key
  await service.rotateKey();
  // Re-encrypt all secrets with the new key (separate step)
  await service.reencryptAll();

  // Query audit logs
  const logs = await service.getAuditLogs({ secretName: 'stripe-api-key' });

  // Diagnose tenant secret/key drift without exposing values
  const drift = await service.diagnoseTenantSecretKeyDrift('tenant-123');

  // Preview and then explicitly repair unrecoverable drifted rows
  await service.repairTenantSecretKeyDrift('tenant-123', { dryRun: true });
  await service.repairTenantSecretKeyDrift('tenant-123', {
    confirmDeleteUnrecoverableData: true,
  });

  // Hard delete
  await service.delete('stripe-api-key');
});
```

### 加密链

```
AMK (env var, 256-bit)
  └─ wraps TDEK (per-tenant, auto-generated)
       └─ encrypts secret value (stored as JSON envelope)
```

AMK 是从 `SMRT_SECRET_MASTER_KEY` (可以通过 `amkEnvVar` 选项)。 环境变量总是获胜。 每个租户都有自己的TDEK 第一次秘密存储. TDEK以包裹的形式被存储——它们只能使用AMK来解接. 秘密值被未被封装的 TDEK 加密,并作为 `EncryptedEnvelope` 贾森.

### 从提供者获取主密钥

本地或桌面应用程序没有环境可以携带AMK. 过 `masterKeyProvider` (aync函数返回64个十六进制字符或32个字符) 原始字节),服务只有在环境变量是时才会问它 未设. 没有默认密钥 : 没有源代码, 创建失败 常规 `Application Master Key not found` 错误, 以及返回的提供者 `null` 做同样的。 提供的密钥从未被登录, 也从未出现在 错误。 在应用程序上 `@happyvertical/smrt-app-runtime`本地简介, pass `runtime.secretMasterKey()` (参见该软件包的 README); 运行时间创建 并保存密钥,使用户永远看不到它.

```ts
const secrets = await SecretService.create({
  db,
  masterKeyProvider: () => runtime.secretMasterKey(),
});
```

### 按键旋转

`rotateKey()` 创建了新的TDEK版本并退役了旧版本. 现有的秘密仍然可以读取,因为已退休的密钥被保存用于解密. 打电话 `reencryptAll()` 在旋转后用新密钥重新加密所有机密。 方法返回 `{ success, failed }` 计数.

租户身份: `active` (当前加密密钥), `rotating` (过渡), `retired` (用于解密), `compromised` (不应使用).

### 流动诊断和维修

`diagnoseTenantSecretKeyDrift(tenantId)` 租户的秘密/钥匙漂移情况 返回秘密值。 它检查活动 `secrets` 下层行 `tenant_encryption_keys` 使用的行数 `@happyvertical/secrets`还有s -m -r -t `tenant_keys` 使操作员能够区分缺失的秘密和 stale 或 无法使用的关键材料.

`repairTenantSecretKeyDrift(tenantId, { dryRun: true })` 预览行将 删除。 破坏性修复需要 `confirmDeleteUnrecoverableData: true`; 它只删除加密密钥行 以当前配置的 AMK 识别为无法恢复 。 修复后, 存储新密钥值 `storeForTenant()` 或者说 `store()`。 。 。 .

### 审计记录

每个秘密操作(创建、读取、更新、删除、旋转 密钥、禁用、启用)都被登录到 `SecretAuditLog` 带有用户ID,动作,结果(成功/失败/否认),以及可选IP/用户代理. 默认启用了审计记录;失败被记录为控制器而不是抛出,所以不会阻断秘密操作.

### 安保模式

这个 `Secret` 财务报告和审定财务报表 `TenantKey` 模型没有防止意外泄漏的API或MCP暴露. CLI访问仅限于列出名字. 这个 `TenantKey` 模式刻意不以租户为范围 -- -- 它跟踪租户的钥匙,而不是他们所拥有的钥匙.

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Secret` | 加密有状态、过期和访问跟踪的秘密记录 |
| `SecretAuditLog` | 所有秘密行动的不可更改的审计线索 |
| `TenantKey` | 包式的租户数据加密密钥 |

### 收款

| 导出 | 说明 |
| --- | --- |
| `SecretCollection` | 涉及租户过滤和类别支助的秘密查询 |
| `SecretAuditLogCollection` | 审计日志查询,包括过滤和标注 |
| `TenantKeyCollection` | 关键管理,包括已退休的关键清理 |

### 服务

| 导出 | 说明 |
| --- | --- |
| `SecretService` | 高级API:存储、检索、旋转、删除、审计、诊断和修复密钥漂移 |

### 职能

| 导出 | 说明 |
| --- | --- |
| `createAuditEntry` | 为秘密行动建立审计日志条目 |

### 出错类( 从 `@happyvertical/secrets`(中文(简体) )

`SecretError`, (中文(简体) ), `AMKUnavailableError`, (中文(简体) ), `DecryptionError`, (中文(简体) ), `EncryptionError`, (中文(简体) ), `InvalidKeyFormatError`, (中文(简体) ), `KeyNotFoundError`, (中文(简体) ), `KeyRotationError`, (中文(简体) ), `StoreNotInitializedError`, (中文(简体) ), `TenantKeyMissingError`

### 密钥类型

`SecretServiceOptions`, (中文(简体) ), `SecretMasterKeyProvider`, (中文(简体) ), `StoreSecretOptions`, (中文(简体) ), `RetrievedSecret`, (中文(简体) ), `DiagnoseTenantSecretKeyDriftOptions`, (中文(简体) ), `SecretKeyDriftReport`, (中文(简体) ), `SecretKeyDriftIssue`, (中文(简体) ), `RepairTenantSecretKeyDriftOptions`, (中文(简体) ), `SecretKeyDriftRepairResult`, (中文(简体) ), `ListSecretsOptions`, (中文(简体) ), `ListAuditLogsOptions`, (中文(简体) ), `SecretStatus`, (中文(简体) ), `SecretAuditAction`, (中文(简体) ), `SecretAuditResult`, (中文(简体) ), `TenantKeyStatus`, (中文(简体) ), `ApplicationMasterKey`, (中文(简体) ), `EncryptedEnvelope`, (中文(简体) ), `TenantDataEncryptionKey`, (中文(简体) ), `SecretStore`

## 依赖关系

-   `@happyvertical/smrt-core` -- ORM 和代码生成
-   `@happyvertical/smrt-tenancy` -- 范围业务的租户背景
-   `@happyvertical/secrets` -- 信封加密原始数据
-   `@happyvertical/sql` -- 数据库接口
-   `@happyvertical/utils` -- -- 共用公用事业

## 常见问题

### @happyvertical/smrt-secrets 是什么？

为 SMRT 加密信封的租户保密管理

### 如何安装 @happyvertical/smrt-secrets？

在项目目录运行 npm install @happyvertical/smrt-secrets，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-secrets 支持 TypeScript 吗？

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

### @happyvertical/smrt-secrets 支持 ESM 还是 CommonJS？

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

### @happyvertical/smrt-secrets 可以商用吗？

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

### @happyvertical/smrt-secrets 的下载量有多少？

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

### @happyvertical/smrt-secrets 还在维护吗？

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

