Azure 密钥断层

按项目、环境和组处理 Azure 密钥默认密钥的节点库( 当金库是时) 和JSON一样 每一次失败都被分类和记录在它的级别, 图书馆说谁 它签了名 所以一个失踪的金库 无法进入的身份和失踪的秘密 一样.

无害环境管理,节点22.12或以后.

如何使用 QQ

import { AzureKeyVault } from '@achs/azure-key-vault';

// DefaultAzureCredential: environment variables, workload or
// managed identity, Azure CLI ("az login")...
const keyVault = new AzureKeyVault({
    vaultUrl: 'https://my-key-vault.vault.azure.net',
    project: 'my-project',
    group: 'web',
    env: 'dev',
});

await keyVault.setAll({
    SECRET1: 'my secret 1',
    otherConfig: { SECRET2: 'my secret 2' },
});

const secrets = await keyVault.getFor({
    SECRET1: null,
    otherConfig: { SECRET2: null },
    SECRET3: 'default for secret 3',
});
// { SECRET1: 'my secret 1', otherConfig: { SECRET2: 'my secret 2' }, SECRET3: 'default for secret 3' }
// typed with the shape of the input: secrets.otherConfig.SECRET2

选项

仅具有某些值的服务本位值将丢入 TypeError,命名缺失的,和 无效 concurrency, (中文(简体) ), timeoutMs 或者说 expiryWarningDays 数值。 图书馆从来不写 process.env。 。 。 .

秘密名称

密钥地图 project-group-env-key小写 _ 空间变为 - (单位:千美元)toSecretName(scope, key) 给它.

• : (或 --筑起一个键: car:props:name 实值 { car: { props: { name } } }。 。 。 .
• 最后一段从 $ 由项目的每个组(app)共用,相同 环境: parent:$global_var 地图到 project-env-parent--global-var不与 其他项目。 没有团体, KEY 财务报告和审定财务报表 $KEY 映射到同一个秘密.
• 不映射到有效秘密名称的密钥( 字母、 数字和破折号, 最多为 127) 失败 在任何请求之前; 以组表示范围包名称( x)@scope/name也一样,所以设置 AZURE_GROUP。 。 。 .
• 范围(项目、组、环境)与名称相似,无论情况或空间如何 与(normalizeScope: My App 财务报告和审定财务报表 my-app 是一个组,标记是写入的 已经正常了.

标记

每个秘密都带有重建其关键和范围的标记(project, (中文(简体) ), group, (中文(简体) ), env, (中文(简体) ), name, (中文(简体) ), path, (中文(简体) ), 加:

JSON 值( 除字符串外的任何东西) 也有 contentType: application/json,并在 要么这么说. updated-by 来源于该图书馆所签名的身份( 它需要一个符号) ); 使用注入的客户端时,它被忽略.

伐木和可追踪性

每一次失败都被分类(AzureKeyVaultErrorKind并登录在它的级别,命名金库和 它影响的秘密。 价值从来没有记录,只有秘密的名字.

每个关卡都显示:

• 错误/ 警告:每个原因各一行,每个秘密都会影响. A 类 forbidden 线条名称 保险库里的人appid编号 :oid),操作需要的许可和作用 (单位:千美元)Key Vault Secrets User 读取和列表, Key Vault Secrets Officer 和谁的图书馆 签入.
• 警告( e) 又: 读取已过期、 尚未生效的密件( 关键 Vault 无论如何都给它们) 或 关于 将到期的expiryWarningDays) (中文(简体) ).
• 资讯: 谁是图书馆注册的(authenticated as user [email protected] (tenant ...)从 第一令牌:用户、服务主或管理下的身份,对多个操作的汇总 保密(read 3 of 5 secrets, 1 not found or disabled, 1 failed)和结果 check()。 。 。 .
• 调试:每个秘密读取,写出,删除,被清洗或恢复.
• 追踪:每个原因的原Azure SDK错误.

keyVault.identity 提供已知的身份(仅当库建客户端时).

木头去的地方

• 注入的 logger 接收每个关卡并过滤自己,所以主机应用程序保存 所有东西都有一个日志级. @achs/env 通过自己的 tslog 记录器这种方式。 设定 logLevel 改为 在这里过滤它.
• 没有 logger图书馆用一个 [akv] 前缀,从 logLevel, (中文(简体) ), 还有 AKV_LOG_LEVEL 环境变量,其他 warn。 。 。 .

const keyVault = new AzureKeyVault({
    vaultUrl,
    project: 'my-project',
    env: 'dev',
    logger: parentLogger.getSubLogger({ name: 'akv' }),
});

失败和 strict

• 阅读和维修 (单位:千美元)get, (中文(简体) ), getFor, (中文(简体) ), getAll, (中文(简体) ), keys, (中文(简体) ), versions, (中文(简体) ), delete, (中文(简体) ), purge, (中文(简体) ), restore 编辑 *All 函数)记录其失败并继续:无法被读取的值 默认(或 null) (中文(简体) ). 与 strict: true时,错误级别失败会丢出一个 AzureKeyVaultError 一旦一切被记录下来,一个丢失或残废的秘密只会发出警告.
• 写作 (单位:千美元)set, (中文(简体) ), setAll, (中文(简体) ), rollback和 getInfo 总是扔一个 AzureKeyVaultError。 。 。 .

import { AzureKeyVaultError } from '@achs/azure-key-vault';

try {
    await keyVault.getFor(schema);
} catch (error) {
    if (error instanceof AzureKeyVaultError)
        console.error(error.kind, error.vaultUrl, error.secretNames);
}

classifyError(error) azure SDK 所抛出的任何错误.

check()

诊断一个金库 只有一个请求 一个不应该存在的秘密: 当金库通过它 主机解析和答案, 身份认证并可能读取机密, 上面写着是谁签名的 . 从来投出.

const { ok, kind, message, identity } = await keyVault.check();
// { ok: false, kind: 'forbidden', identity: { type: 'service-principal', appId: '...' }, message: 'https://...: the identity appid=... lacks the "get" secret permission (...), signed in as service principal appid=...' }

网络:DNS检查、VPN和代理

在首次请求之前,图书馆会解决一次库房主机 系统 DNS一个 每个请求的用途( VPN 包含的 DNS ) : 不同时解析失败的主机 vault-not-found,而不是在对每项请求进行重审之后。 它从来不违背要求, 与针对公共DNS服务器的检查不同,VPN可能会屏蔽. 当代理解决时它被跳过 改为主机(clientOptions.proxyOptions,或 HTTPS_PROXY编号 :HTTP_PROXY编号 :ALL_PROXY),带有 已注射 client,并与 dnsCheck: false。 。 。 .

concurrency 一次性封顶请求(一个共用的库门节流阀,它的所有呼叫者), timeoutMs 限制每个操作,和 clientOptions 到达 Azure 客户端(retries,代理). 用户代理 携带 @achs/azure-key-vault/<version>保险库的诊断记录显示是谁打来的.

职能

getFor 只读默认为空的密钥( e)null, (中文(简体) ), '', (中文(简体) ), 0, (中文(简体) ), false),或每把键带有 override; 存储为 JSON (一个数组, 一个对象, 一个数字) 的秘密返回解析 .

const secrets = await keyVault.getFor({
    '$global-var': null,
    'my-secret': null,
    'my-secret-2': 'default value',
    'my-secret-group1': { 'my-secret-3': null },
    'my-array-secret': null,
});

审计

audit() 为项目或 与 allProjects 整个金库,一个摘要(机密,由图书馆管理,贴上标签,不挂上标签, (b) 将项目、小组(按环境分列)和这些结果记录在自己的层次:

auditSecrets(properties, options) 对别处列出的秘密财产进行同样的检查.

用模型测试

createAzureKeyVaultMock(options, { faults }) 给一个管理者一个由每个人共享的内存金库 嘲讽,这失败 就像阿苏尔做的(一个缺失的秘密是一个 secret-not-found) (中文(简体) ). faults 注入失败 键,或每个请求 '*'· ; resetAzureKeyVaultMock() 空出金库.

const vault = createAzureKeyVaultMock(
    { project: 'app', env: 'dev' },
    { faults: { DB_PASS: 'forbidden', '*': 'timeout' } },
);

命令 {}

这个 akv 命令运行相同的操作。 日志转到 stderr (at info 除非 --log 说 否则),输出为 stdout.

退出代码 : 0 成功吗, 2 未找到金库,无法到达或超时, 3 无可用身份, 4 拒绝许可, 1 其他的任何东西。 仅读出命令失败 --strict (或何时) get, (中文(简体) ), list 或者说 versions 读作"无".

akv check --uri=https://my-key-vault.vault.azure.net --project=my-project --env=dev --json
printf '%s' "$DB_PASS" | akv set --uri=... --project=my-project --env=dev --key=DB_PASS
akv getfor --uri=... --project=my-project --env=dev --file=structure.json --output=secrets.json --log=debug

runCli(argv) 从代码运行相同的命令,以及 exitCode(kind) 绘制其代码的失败类型.

联合国

pnpm test:cov   # Vitest with coverage (100% thresholds)
pnpm lint       # ESLint
pnpm typecheck  # TypeScript
pnpm format     # Prettier
pnpm build      # Vite library build into dist/

变换日志 QQ

上一次更改见 变动情况。 。 。 .

由 QQ 建造

• @azure/身份 - Azure身份提供商.
• @azure/ keyvault- 机密 - Azure 键断层 秘密客户.