@bessolve/iam-policy-ts (英语)

有自动生成的AWS动作目录的可树可摇动,类型安全的IAM政策助手.

每个~450 AWS服务都生活在自己的模块中. 仅导入您使用的东西 —— 您的捆绑者放下其余的 。 在 TypeScript 中写入内置策略时, 全部自动完成 AWS IAM 动作 .

安装

npm install @beesolve/iam-policy-ts

使用量

IAM 行动助手

每个 AWS 服务作为独立函数导出,具有全类型安全并自动完成:

import { s3, ec2, organizations } from "@beesolve/iam-policy-ts";

s3("GetObject");              // "s3:GetObject"
ec2("RunInstances");          // "ec2:RunInstances"
organizations("ListAccounts"); // "organizations:ListAccounts"
s3("*");                      // "s3:*"

连字符服务前缀使用骆驼Case函数名 :

import { accessAnalyzer, ssoDirectory } from "@beesolve/iam-policy-ts";

accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"
ssoDirectory("SearchUsers");      // "sso-directory:SearchUsers"

命名空间导入

如果您喜欢单一的命名空间( 类似于旧的) iam 对象,您可以使用命名空间导入 :

import * as iam from "@beesolve/iam-policy-ts";

iam.s3("GetObject");              // "s3:GetObject"
iam.accessAnalyzer("ListAnalyzers"); // "access-analyzer:ListAnalyzers"

在现代捆绑机(建造、滚出、Vite、Webpack5)中,树摇可以输入命名空间。 他们静态地分析你访问命名空间的属性,然后放下其余的属性. 此模式与 维利博特 (单位:千美元)import * as v from 'valibot') (中文(简体) ).

子路径导入( Tree- Shaking)

对于最佳捆绑大小,仅通过子路径导出导入所需的服务 :

// Import only what you need — optimal for tree-shaking
import { s3 } from "@beesolve/iam-policy-ts/s3";
import { accessAnalyzer } from "@beesolve/iam-policy-ts/access-analyzer";

s3("GetObject");                  // "s3:GetObject"
accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"

每个服务都有自己的子路径,匹配AWS服务前缀(保留了连字符).

政策验证

有两个验证模式:

允许( 默认) ——仅验证结构形状(字段类型,允许键). 匹配 AWS 在 JSON 级别上接受的,而不执行诸如 Action/ Not Action 专属等语法规则 .

import {
  isIamPolicyDocument,
  assertIamPolicyDocument,
  iamPolicyDocumentSchema,
} from "@beesolve/iam-policy-ts";

// Type guard
if (isIamPolicyDocument(unknownValue)) {
  // unknownValue is typed as IamPolicyDocument
}

// Assertion (throws on invalid input)
const policy = assertIamPolicyDocument(jsonInput);

严格 此外,还执行IAM语法规则:

• 一定有一个 Action 或者说 NotAction
• 无法同时拥有 Resource 财务报告和审定财务报表 NotResource

import {
  isIamPolicyDocumentStrict,
  assertIamPolicyDocumentStrict,
  iamPolicyDocumentStrictSchema,
} from "@beesolve/iam-policy-ts";

// Rejects policies with both Action and NotAction, etc.
if (isIamPolicyDocumentStrict(unknownValue)) {
  // Passes strict grammar checks
}

作为类型脚本的渲染策略

import { policyToTypescript } from "@beesolve/iam-policy-ts";

const ts = policyToTypescript({
  Version: "2012-10-17",
  Statement: [{
    Effect: "Allow",
    Action: ["s3:GetObject", "s3:ListBucket"],
    Resource: "*",
  }],
});

// Output uses per-service functions for known actions:
// {
//   Version: "2012-10-17",
//   Statement: [
//     {
//       Effect: "Allow",
//       Action: [
//         s3("GetObject"),
//         s3("ListBucket")
//       ],
//       Resource: "*"
//     }
//   ]
// }

访问原始目录

完整的动作目录可以从主条目或通过专用的子路径获取:

// From main entry
import {
  iamActionCatalog,
  iamActionCatalogSourceSha256,
  iamActionCatalogActionCount,
} from "@beesolve/iam-policy-ts";

// Or via dedicated subpath (avoids pulling in all service functions)
import {
  iamActionCatalog,
  iamActionCatalogSourceSha256,
  iamActionCatalogActionCount,
} from "@beesolve/iam-policy-ts/_meta";

// iamActionCatalog is a typed const object:
// { s3: ["AbortMultipartUpload", ...], kms: ["CancelKeyDeletion", ...], ... }

console.log(`${iamActionCatalogActionCount} actions across ${Object.keys(iamActionCatalog).length} services`);

迁移指南(出自v25/v26)

此版本引入了突破性更改: 单体 iam 帮助对象和 iamAction() 函数已被删除,从而有利于允许树摇动的每个服务函数导入.

删除了导出

移徙实例

在此之前:

import { iam, iamAction } from "@beesolve/iam-policy-ts";

iam.s3("GetObject");                        // "s3:GetObject"
iam["access-analyzer"]("ListAnalyzers");    // "access-analyzer:ListAnalyzers"
iamAction("s3", "GetObject");               // "s3:GetObject"

之后:

import { s3, accessAnalyzer } from "@beesolve/iam-policy-ts";

s3("GetObject");                  // "s3:GetObject"
accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"

快速引用

渲染输出更改

这个 policyToTypescript 函数现在发出每个服务功能的调用,而不是 iam.* 属性访问 :

更新目录

该目录由每日2:00 UTC运行的GitHub Action工作流程自动更新. 它从 AWS 获取最新的 IAM 动作数据,如果检测到变化,则承诺更新并发布新版本到 npm.

您也可以运行 npm run generate 本地生成目录 src/catalog/。 。 。 .

资料来源: https://awspolicygen.s3.amazonaws.com/js/politics.js 页面存档备份,存于互联网档案馆

版本

此软件包使用基于日期的版本 YY.M.D 格式(例如, 25.7.14) (中文(简体) ). 只有在上游AWS IAM动作目录发生变化时,才自动发布新版本. 该版本反映了协调世界时该目录被捕获的日期.

类型

所有IAM政策类型都导出:

• IamPolicyDocument 编号 : IamPolicyDocumentStrict
• IamPolicyStatement 编号 : IamPolicyStatementStrict
• IamPolicyPrincipal
• IamPolicyPrincipalMap
• IamPolicyConditionBlock
• IamPolicyStringList
• IamPolicyScalar
• IamPolicyScalarList
• IamPolicyVersion

也提供每类服务:

• S3Action, (中文(简体) ), Ec2Action, (中文(简体) ), AccessAnalyzerAction——每个服务机构有效行动的工会类型
• s3Actions, (中文(简体) ), ec2Actions, (中文(简体) ), accessAnalyzerActions等——一连串动作名

财务问题

这是否证实在AWS中确实存在IAM动作?

没有。 计划验证( A)isIamPolicyDocument, (中文(简体) ), assertIamPolicyDocument等)只检查结构形状——正确字段类型,允许键,非空字符串. 它无法证实动作字符串像 "s3:GetObject" 对应于真实的 AWS 动作。 每个服务功能从目录中提供编译时间自动完成,但计划层被有意与它脱钩.

宽容与严格验证有何区别??

允许(默认)验证JSON结构:正确类型,无未知密钥,非空值. 它反映了AWS在API级别上接受的内容.

严格额外执行IAM语法规则:一个语句必须完全具有其中之一 Action 或者说 NotAction,而且不能两者兼有 Resource 财务报告和审定财务报表 NotResource。在部署前要抓住逻辑错误时,请使用严格模式.

我能用通配符动作吗 s3:*? 吗?

对 每项服务职能接受 "*" 作为有效动作名称 :

s3("*")  // "s3:*"

方案层还接受任何非空字符串 Action编号 :NotAction,所以通配符喜欢 "s3:Get*" 通过验证.

动作目录多久更新一次??

每日GitHub Action工作流程于协调世界时02:00运行. 它从中获取最新数据 AWS 政策生成器,如果目录已更改,则将更新并发布新版本为npm。 无所变化时不创建放行.

动作目录的来源是什么??

该目录来源于 https://awspolicygen.s3.amazonaws.com/js/policies.js 与AWS政策生成器控制台相同的源头. 源文件的SHA-256散列记录在 iamActionCatalogSourceSha256 为可复制.

此软件包是否在运行时进行网络调用 ?

没有。 该目录在构建时生成并被作为静态TypeScript const对象发运. 有零运行时间网络呼叫.

这是否与 CDK / Pulumi / SST / Terraform CDK 有关?

对 帮助者产生平庸的字符串( E)"s3:GetObject")和计数函数接受/返回平原对象。 它们在您构建的 IAM 策略 JSON 在 TypeScript — CDK 内置策略, Pulumi 政策文件, SST 权限, 或 Terraform CDK 构造中整合 .

支持什么节点.js和TypeScript版本?

节点.js 24+和 TypeScript 6+. 一揽子措施仅限无害环境管理("type": "module") (中文(简体) ).

树能摇动吗?

对 每个AWS服务都在自己的模块(~450文件)中. 软件包声明 "sideEffects": false 并提供每条服务的子路径出口.

职业:

• 导入 2 - 3 服务, 您的捆绑只包含这些 —— 而不是完整的 ~ 18K 动作目录
• Subpath的进口给捆绑者提供了尽可能最强的信号(不需要进行管子分析)
• 与Esbuild、Rollup、Webpack、Vite以及任何支持的捆绑商合作 package.json "exports"
• 零运行时间高程 — 每个服务功能是返回模板文字的一行

条件/限制:

• 包中的~450个源文件(在磁盘上安装更大的尺寸,尽管npm压缩效果良好)
• TypeScript 语言服务器可能因文件计数而较慢于第一个打开的索引
• 枪管导入( E)import { s3 } from "@beesolve/iam-policy-ts")再出口所有服务——刷树取决于您捆绑者是否有能力再出口未使用的产品

当摇倒树木时:

• esbuild, Rollup, Vite——这些手提筒再出口和命名空间的进口情况良好;它们甚至会减少未使用的服务 import * as iam
• import * as iam from "@beesolve/iam-policy-ts" 现代捆绑商静态地分析财产进入(iam.s3, (中文(简体) ), iam.ec2)并仅包括
• 亚次路径进口( 4)@beesolve/iam-policy-ts/s3——保证与任何捆绑机合作,因为只有一个模块被装入
• 任何环境 "sideEffects": false 受到尊重

当摇树可能不起作用时:

• 没有捆绑器的节点(Node.js)——所有模块都可以使用,但运行时没有去除死码(因为这是一个 dev-time/building-time的担心)
• 更古老的网络包装版本( < 5),加上桶口进口——可能拉入整个桶口. 使用子路径导入来做工作 .
• 如果您导入 iamActionCatalog 从主条目中——包含完整的目录对象(~18K动作). 使用 @beesolve/iam-policy-ts/_meta 来隔离它.
• 动态访问模式 const fn = services[prefix] 失败静态分析——坚持命名的进口或静态 iam.s3(...) 财产访问
• 将命名空间物体绕行(doSomething(iam))——捆绑者无法追踪被调用者内部访问哪些属性

对于最大树摇动,使用子路径导入:

import { s3 } from "@beesolve/iam-policy-ts/s3";

如何重新生成本地目录?

npm run generate

这个运行 scripts/generate-catalog.ts,获取最新的 AWS 源,并生成每个服务文件 src/catalog/。 。 。 .

我应该使用主入口还是子通道进口?

这取决于你的设置:

如果怀疑,次路径进口总是最安全的选择。 他们完全绕过枪管分析.

许可证

麻省理工学院