@happyvertical/smrt-secrets

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.3万

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

中文使用文档
文档目录16 节
  1. 安装
  2. 使用量
  3. 加密链
  4. 从提供者获取主密钥
  5. 按键旋转
  6. 流动诊断和维修
  7. 审计记录
  8. 安保模式
  9. API 密码
  10. 模型
  11. 收款
  12. 服务
  13. 职能
  14. 出错类( 从 @happyvertical/secrets (中文(简体) )
  15. 密钥类型
  16. 依赖关系

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

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

安装

pnpm add @happyvertical/smrt-secrets

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

使用量

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); 运行时间创建 并保存密钥,使用户永远看不到它.

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 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-secrets 的常见问题

@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 和提交记录判断。