@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-- -- 共用公用事业