# @cloud-copilot/iam-policy 中文文档

规范地址：https://npmcn.com/package/%40cloud-copilot/iam-policy/

版本：0\.1\.109
npm 元数据更新时间：2026-08-29T12:21:07.480Z
中文译文更新时间：2026-11-10T02:19:13.153Z
软件包许可：AGPL-3\.0-or-later

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

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

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

- 包体积（解压后）：334 kB，125 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-09-28T21:37:33.523Z
- 最新版本发布：2026-08-29T12:21:07.131Z
- 近 30 天下载量：35554（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：121（近 12 个月 52 个）

## 中文简介

AWS IAM 策略的 ORM

## 安装

```sh
npm install @cloud-copilot/iam-policy
```

也可以使用：`pnpm add @cloud-copilot/iam-policy`、`yarn add @cloud-copilot/iam-policy`、`bun add @cloud-copilot/iam-policy`

## README

# IAM 策略语法校验和解析器

[![NPM Version](https://img.shields.io/npm/v/@cloud-copilot/iam-policy.svg?logo=nodedotjs)](https://www.npmjs.com/package/@cloud-copilot/iam-policy) [![License: AGPL v3](https://img.shields.io/github/license/cloud-copilot/iam-policy)](https://npmcn.com/package/%40cloud-copilot/iam-policy/LICENSE.txt) [![GuardDog](https://github.com/cloud-copilot/iam-policy/actions/workflows/guarddog.yml/badge.svg)](https://github.com/cloud-copilot/iam-policy/actions/workflows/guarddog.yml) [![Known Vulnerabilities](https://snyk.io/test/github/cloud-copilot/iam-policy/badge.svg?targetFile=package.json&style=flat-square)](https://snyk.io/test/github/cloud-copilot/iam-policy?targetFile=package.json)

这是一个简单的IAM政策库,可以让您安全地解析并导航IAM政策,而不用担心解析政策或验证语法的更困难的细节.

这个将来可能会更新,允许修改政策,现在只读.

## 验证策略语法 `validatePolicySyntax`

`validatePolicySyntax` 是一个语法 linter, 并且不会验证该策略是逻辑的, 安全的, 或者正确的 .

这将带走任何对象并返回一系列发现。 如果数组为空,则策略有效.

```typescript
import { validatePolicySyntax } from '@cloud-copilot/iam-policy'

validatePolicySyntax({
  Version: '2012-10-17',
  Statement: [
    {
      Sid: 'VisualEditor0',
      Effect: 'Allow',
      Action: 's3:GetObject',
      Resource: 'arn:aws:s3:::mybucket/*'
    }
  ]
}) // []

validatePolicySyntax({
  Version: '2012-10-17',
  Statement: [
    {
      Sid: 7,
      Effect: 'Allow',
      Action: 's3:GetObject',
      Resource: 'arn:aws:s3:::mybucket/*'
    }
  ]
}) // [{ message: 'Found data type number allowed type(s) are string', path: 'Statement[0].Sid'}]

/* It will attempt to find as many issues as possible in one pass */
validatePolicySyntax({
  Version: '2012-10-17',
  Comment: 'Jacob is kewl',
  Statement: [
    {
      Sid: 'SomeStatement',
      Effect: 7,
      Action: 's3:GetObject',
      Resource: 'arn:aws:s3:::mybucket/*'
    },
    {
      Sid: 'SomeStatement',
      Effect: ['Allow'],
      Action: 's3:GetObject',
      Resource: 'arn:aws:s3:::mybucket/*',
      Condition: {
        NumericLessThan: {
          's3:max-keys': 7
        },
        StringLike: {
          's3:authType': new RegExp(/REST.*/),
          'aws:TagKeys/Foo': ['Bar*', 'Baz*']
        }
      }
    }
  ]
}) /*
[
  { message: 'Invalid key Comment', path: 'Comment' },
  { message: 'Effect must be present and exactly "Allow" or "Deny"', path: 'Statement[0].Effect' },
  { message: 'Effect must be present and exactly "Allow" or "Deny"', path: 'Statement[1].Effect' },
  { message: 'Found data type object allowed type(s) are string, boolean, number', path: 'Statement[1].Condition.StringLike.s3:authType' }
]
*/
```

### 验证特定政策类型

有一些功能可以验证具体的政策类型,这些功能可以进行所有的一般政策验证,并对具体的政策类型进行额外检查. 例如,服务控制政策只允许在效果被拒绝时使用条件要素.

-   `validateIdentityPolicy(policy: any): ValidationError[]`
-   `validateServiceControlPolicy(policy: any): ValidationError[]`
-   `validateResourcePolicy(policy: any): ValidationError[]`
-   `validateTrustPolicy(policy: any): ValidationError[]`
-   `validateResourceControlPolicy(policy: any): ValidationError[]`
-   `validateEndpointPolicy(policy: any): ValidationError[]`
-   `validateSessionPolicy(policy: any): ValidationError[]`

## IAM 政策分析和处理 `loadPolicy`

`loadPolicy` _**不验证政策**_,如果需要先于时间使用验证 `validatePolicySyntax`。 。 。 .

### 将政策元素规范化,这些元素是对象/对象的阵列或弦/弦的阵列

```typescript
import { loadPolicy } from '@cloud-copilot/iam-policy'

//Statement can be an array of objects
const policyOne = {
  Version: '2012-10-17',
  Statement: [
    {
      Sid: 'ArrayStatement',
      Effect: 'Allow',
      Action: ['s3:GetObject'],
      Resource: 'arn:aws:s3:::government-secrets/*'
    }
  ]
}

//Statement can also be a single object
const policyTwo = {
  Version: '2012-10-17',
  Statement: {
    Sid: 'ObjectStatement',
    Effect: 'Allow',
    Action: ['s3:GetObject'],
    Resource: 'arn:aws:s3:::government-secrets/*'
  }
}

//In both cases you can use the `statements` function to get an array of statements
const p1 = loadPolicy(policyOne)
const p2 = loadPolicy(policyTwo)
console.log(p1.statements()[0].sid()) //ArrayStatement
console.log(p2.statements()[0].sid()) //ObjectStatement
```

对条件价值、主要价值和资源也有类似的支持.

### 相互排斥或任择政策要素

在机构间咨询小组的政策中,有一些相互排斥的要素。 比如,你不能有一个 `Principal` (单位:千美元) `NotPrincipal` 在同一声明中。 有些要素是完全可选的。 我们利用Typescript类型系统来确保您只访问经确认存在于策略中的数据.

```typescript
import{ loadPolicy } from '@cloud-copilot/iam-policy'

const actionPolicy = {
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
    ],
    "Resource": "arn:aws:s3:::government-secrets/*"
  }
};

const p = loadPolicy(actionPolicy);
const statement = p.statements()[0]; // Get the first statement out

statement.actions() // Compile time error because Statement does not the `actions` function

if(statement.isActionStatement()) {
  // Type is narrowed to ActionStatement so `actions` is now available
  statement.actions() /
}

if(statement.isNotActionStatement()) {
  // Will not exectue because the statement does not have a NotAction element
}
```

`isNotActionStatement` 检查“不行动”元素的存在,而不是反向 `isActionStatement`. 声明有可能对双方都是虚假的 `isActionStatement` 财务报告和审定财务报表 `isNotActionStatement` 如果报表中缺少两个要素.

也有类似的支持 `Action`, (中文(简体) ), `NotAction`, (中文(简体) ), `Principal`, (中文(简体) ), `NotPrincipal`, (中文(简体) ), `Resource`,以及 `NotResource` 要素.

### 平整复合结构

将复杂元素平整为一团同质物体来简化. 例如:主值可以是字符串或对象;对象值可以是字符串或数组的字符串. 我们把这些物体平整成一系列物体, 类似于您在地球政策中定义的物体.

```typescript
import { loadPolicy } from '@cloud-copilot/iam-policy'

const principalPolicy = {
  Version: '2012-10-17',
  Statement: {
    Effect: 'Allow',
    Principal: {
      AWS: ['arn:aws:iam::123456789012:root', 'arn:aws:iam::123456789013:user/FoxMulder'],
      CanonicalUser: '79a59df900b949e55d96a1e698fbacedfd6e09d98eacf8f8d5218e7cd47ef2be',
      Federated: 'cognito-identity.amazonaws.com'
    },
    Action: ['s3:GetObject'],
    Resource: 'arn:aws:s3:::government-secrets/*'
  }
}

const p = loadPolicy(principalPolicy)

const statement = p.statements()[0] // Get the first statement out
if (statement.isPrincipalStatement()) {
  //Get an array of 4 Principal objects with a type and value
  const principals = statement.principals()
  principals[0].type() //AWS
  principals[0].value() //arn:aws:iam::123456789012:root
  //and so on
  principals[3].type() //Federated
  principals[3].value() //cognito-identity.amazonaws.com
}
```

还有类似的平面 `Condition` 键.

```typescript
import { loadPolicy } from '@cloud-copilot/iam-policy'

const principalPolicy = {
  Version: '2012-10-17',
  Statement: {
    Effect: 'Allow',
    Principal: {
      AWS: 'arn:aws:iam::123456789012:root'
    },
    Action: ['s3:GetObject'],
    Resource: 'arn:aws:s3:::government-secrets/*',
    Condition: {
      StringEquals: {
        's3:prefix': 'home/${aws:username}',
        'aws:PrincipalOrgID': 'o-1234567890'
      },
      StringLike: {
        's3:authType': 'REST*',
        'aws:TagKeys/Foo': ['Bar*', 'Baz*']
      }
    }
  }
}

const p = loadPolicy(principalPolicy)

const statement = p.statements()[0] // Get the first statement out

const conditions = statement.conditions()
conditions[0].operation().value() //StringEquals
conditions[0].conditionKey() //s3:prefix
conditions[0].conditionValues() //[ home/${aws:username} ]
//and so on
conditions[3].operation().value() //StringLike
conditions[3].conditionKey() //aws:TagKeys/Foo
conditions[3].conditionValues() // [Bar*, Baz*]
```

## 常见问题

### @cloud-copilot/iam-policy 是什么？

AWS IAM 策略的 ORM

### 如何安装 @cloud-copilot/iam-policy？

在项目目录运行 npm install @cloud-copilot/iam-policy，或使用 pnpm add / yarn add / bun add。

### @cloud-copilot/iam-policy 支持 TypeScript 吗？

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

### @cloud-copilot/iam-policy 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloud-copilot/iam-policy 可以商用吗？

@cloud-copilot/iam-policy 使用 AGPL-3\.0-or-later 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cloud-copilot/iam-policy 的下载量有多少？

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

### @cloud-copilot/iam-policy 还在维护吗？

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