# @cdklabs/cdk-verified-permissions 中文文档

规范地址：https://npmcn.com/package/%40cdklabs/cdk-verified-permissions/

版本：0\.3\.5
npm 元数据更新时间：2026-06-19T09:45:21.410Z
中文译文更新时间：2026-11-09T06:19:32.966Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：14.7 MB，45 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.12\.0
- 运行依赖：1 个
- peer 依赖：aws-cdk-lib ^2\.260\.0，constructs ^10\.5\.0
- 首次发布：2024-02-05T17:54:55.461Z
- 最新版本发布：2026-06-19T09:45:21.115Z
- 近 30 天下载量：50635（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 5 个）

## 中文简介

L2 亚马逊验证权限的 AWS CDK 构造

## 安装

```sh
npm install @cdklabs/cdk-verified-permissions
```

也可以使用：`pnpm add @cdklabs/cdk-verified-permissions`、`yarn add @cdklabs/cdk-verified-permissions`、`bun add @cdklabs/cdk-verified-permissions`

## README

# 亚马逊验证权限 L2 CDK 构造

此 repo 包含对 Amazon 验证权限的 L2 CDK 架构的执行

# 项目稳定性

这个构造仍然以α/v0主要版本进行版本,我们可以引入断开的更改,即使没有大版本的出错. 我们的目标是尽可能保持API的稳定性和后向兼容性,但我们目前无法保证这一点。 一旦我们发布v1.0.0,破解的更改会通过主要版本的凸起引入.

# 开始

## 政策存储

定义有默认的策略存储( 没有描述, 没有设置为关闭的设置 ) :

```ts
const test = new PolicyStore(scope, "PolicyStore");
```

定义一个没有 Schema 定义的政策存储器( 必须设置为 Validation 设置模式 ) :

```ts
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const test = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
});
```

定义带有描述和Schema定义的政策存储(强烈建议为带有计划的政策存储提供STRICT验证设置模式):

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = {
  PhotoApp: {
    entityTypes: {
      User: {},
      Photo: {},
    },
    actions: {
      viewPhoto: {
        appliesTo: {
          principalTypes: ["User"],
          resourceTypes: ["Photo"],
        },
      },
    },
  },
};
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
  description: "PolicyStore description"
});
```

定义带有校验设置的政策存储器以关闭并删除保护:

```ts
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const test = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
  deletionProtection: DeletionProtectionMode.ENABLED
});
```

定义带有 AWS 拥有密钥加密( 默认行为) 的政策存储 :

```ts
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: {
    mode: ValidationSettingsMode.OFF,
  },
  encryptionSettings: {
    awsOwnedKey: true,
  },
});
```

定义带有客户管理的 KMS 密钥用于加密的政策存储 :

```ts
const key = new kms.Key(scope, "PolicyStoreKey", {
  description: "Key for Verified Permissions Policy Store encryption",
});

const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: {
    mode: ValidationSettingsMode.OFF,
  },
  encryptionSettings: {
    customerManagedKey: {
      key,
    },
  },
});
```

定义有客户管理的 KMS 密钥和加密上下文的政策存储 :

```ts
const key = new kms.Key(scope, "PolicyStoreKey", {
  description: "Key for Verified Permissions Policy Store encryption",
});

const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: {
    mode: ValidationSettingsMode.OFF,
  },
  encryptionSettings: {
    customerManagedKey: {
      key,
      encryptionContext: {
        "department": "security",
        "project": "verified-permissions",
      },
    },
  },
});
```

## 示马斯

如果您在定义一个方案时想要类型安全, 您可以完成此任务 **仅限** 在打字符中输入。 简单使用 `Schema` 导出类型 `@cedar-policy/cedar-wasm`。 。 。 .

您也可以使用静态函数生成简单的计划 `schemaFromOpenApiSpec` 或者说 `schemaFromRestApi` 在 PolicyStore 构造中。 此功能复制您在 AWS 验证权限控制台中可以找到的东西 .

从 OpenAPI 光谱生成一个计划 :

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = PolicyStore.schemaFromOpenApiSpec(
  'path/to/swaggerfile.json',
  'UserGroup',
);
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
  description: "Policy store with schema generated from API Gateway",
});
```

从 RestApi 构造生成一个方案:

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = PolicyStore.schemaFromRestApi(
  new RestApi(scope, "RestApi"),
  "UserGroup",
);
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
  description: "Policy store with schema generated from RestApi construct",
});
```

## 身份来源

定义身份源 :

```ts
const userPool = new UserPool(scope, "UserPool"); // Creating a new Cognito UserPool
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = {
  PhotoApp: {
    entityTypes: {
      User: {},
      Photo: {},
    },
    actions: {
      viewPhoto: {
        appliesTo: {
          principalTypes: ["User"],
          resourceTypes: ["Photo"],
        },
      },
    },
  },
};
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
});
new IdentitySource(scope, "IdentitySource", {
  configuration: {
    cognitoUserPoolConfiguration: {
      userPool: userPool,
    },
  },
  policyStore: policyStore
});
```

用 Cognito 配置和所有属性定义身份源 :

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = {
  PhotoApp: {
    entityTypes: {
      User: {},
      Photo: {},
    },
    actions: {
      viewPhoto: {
        appliesTo: {
          principalTypes: ["User"],
          resourceTypes: ["Photo"],
        },
      },
    },
  },
};
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
});
const cognitoGroupEntityType = 'test';
const userPool = new UserPool(scope, "UserPool"); // Creating a new Cognito UserPool
new IdentitySource(scope, "IdentitySource", {
  configuration: {
    cognitoUserPoolConfiguration: {
      clientIds: ["&ExampleCogClientId;"],
      userPool: userPool,
      groupConfiguration: {
        groupEntityType: cognitoGroupEntityType,
      },
    },
  },
  policyStore: policyStore,
  principalEntityType: "PETEXAMPLEabcdefg111111",
});
```

用 OIDC 配置定义身份源, 并使用 Token 选择配置 :

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = {
  PhotoApp: {
    entityTypes: {
      User: {},
      Photo: {},
    },
    actions: {
      viewPhoto: {
        appliesTo: {
          principalTypes: ["User"],
          resourceTypes: ["Photo"],
        },
      },
    },
  },
};
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
});
const issuer = 'https://iamanidp.com';
const principalIdClaim = 'sub';
const entityIdPrefix = 'prefix';
const groupClaim = 'group';
const groupEntityType = 'GroupType';
new IdentitySource(scope, 'IdentitySource', {
  configuration: {
    openIdConnectConfiguration: {
      issuer: issuer,
      entityIdPrefix: entityIdPrefix,
      groupConfiguration: {
        groupClaim: groupClaim,
        groupEntityType: groupEntityType,
      },
      accessTokenOnly: {
        audiences: ['testAudience'],
        principalIdClaim: principalIdClaim,
      },
    },
  },
  policyStore: policyStore,
  principalEntityType: 'TestType',
});
```

使用 OIDC 配置和身份调值选择配置定义身份源 :

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const cedarJsonSchema = {
  PhotoApp: {
    entityTypes: {
      User: {},
      Photo: {},
    },
    actions: {
      viewPhoto: {
        appliesTo: {
          principalTypes: ["User"],
          resourceTypes: ["Photo"],
        },
      },
    },
  },
};
const cedarSchema = {
  cedarJson: JSON.stringify(cedarJsonSchema),
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  schema: cedarSchema,
  validationSettings: validationSettingsStrict,
});
const issuer = 'https://iamanidp.com';
const entityIdPrefix = 'prefix';
const groupClaim = 'group';
const groupEntityType = 'UserGroup';
const principalIdClaim = 'sub';
new IdentitySource(scope, 'IdentitySource', {
  configuration: {
    openIdConnectConfiguration: {
      issuer: issuer,
      entityIdPrefix: entityIdPrefix,
      groupConfiguration: {
        groupClaim: groupClaim,
        groupEntityType: groupEntityType,
      },
      identityTokenOnly: {
        clientIds: [],
        principalIdClaim: principalIdClaim,
      },
    },
  },
  policyStore: policyStore,
});
```

## 政策

装入全部 `.cedar` 在给定的文件夹中保存文件,并为每个文件定义政策对象。 所有政策都将与同一政策库挂钩. **请注意:** 此方法在内部使用 `Policy.fromFile` 所以同样的规则适用.

```ts
const validationSettingsStrict = {
  mode: ValidationSettingsMode.STRICT,
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsStrict,
});
policyStore.addPoliciesFromPath('/path/to/my-policies');
```

定义一个政策并添加到一个特定的政策库中:

```ts
const statement = `permit(
    principal,
    action in [MyFirstApp::Action::"Read"],
    resource
) when {
    true
};`;

const description = "Test policy assigned to the test store";
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
});

// Create a policy and add it to the policy store
const policy = new Policy(scope, "MyTestPolicy", {
  definition: {
    static: {
      statement,
      description,
    },
  },
  policyStore: policyStore,
});
```

定义带有模板链接定义的政策 :

```ts
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
});
const policyTemplateStatement = `
permit (
  principal == ?principal,
  action in [TinyTodo::Action::"ReadList", TinyTodo::Action::"ListTasks"],
  resource == ?resource
);`;
const template = new PolicyTemplate(scope, "PolicyTemplate", {
  statement: policyTemplateStatement,
  policyStore: policyStore,
});

const policy = new Policy(scope, "MyTestPolicy", {
  definition: {
    templateLinked: {
      policyTemplate: template,
      principal: {
        entityId: "exampleId",
        entityType: "exampleType",
      },
      resource: {
        entityId: "exampleId",
        entityType: "exampleType",
      },
    },
  },
  policyStore: policyStore,
});
```

使用文档中的语句定义策略 : **请注意:**

-   这个 `Policy.fromFile` 静态方法支持每个文件的多种Cedar政策. 每一个政策都必须遵循标准锡达规则. 这意味着每项政策都必须以 `;` 烧焦了.
-   您可以通过 Cedar 说明在 Policy 文件内直接指定 Policy 的 ID, 使用注释 `@cdkId`。注解中定义的ID相对于在注释中通过的ID具有优先权 `Policy.fromFile` 方法。 如果未定义注释,则在 `Policy.fromFile` 将使用方法。 自从 `Policy.fromFile` 方法支持每个文件的多 Cedar 策略,强烈建议通过注释来定义政策 ids,以避免许多具有相同 id 的 Policy Constructions (这会导致 CDK 运行时出错).
-   您可以直接在 Policy 文件内使用注释来指定策略的描述 `@cdkDescription`。注解中定义的描述将优先于在属性对象中传递的描述 `Policy.fromFile` 方法.

```ts
const description = "Test policy assigned to the test store";
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
});

// Create a policy and add it to the policy store
const policyFromFileProps = {
  policyStore,
  path: '/path/to/policy-statement.cedar',
  description: 'the policy description',
};
const policy = Policy.fromFile(scope, "MyTestPolicy", policyFromFileProps);
```

## 政策存储别名

在 API 操作中,一个 Policy Store Alias 提供了可供您引用的备选标识符 。 这一行动具有同理性——如果提出多项请求,则使用同一程序 `aliasName` 财务报告和审定财务报表 `policyStoreId`,之后的请求将被忽略.

为现有的政策商店定义政策存储地址:

```ts
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: {
    mode: ValidationSettingsMode.OFF,
  },
});

new PolicyStoreAlias(scope, "PolicyStoreAlias", {
  aliasName: "my-app-production",
  policyStore: policyStore,
});
```

参考现有政策存储地址:

```ts
const alias = PolicyStoreAlias.fromAliasName(
  scope,
  "ImportedAlias",
  "my-app-production",
);
```

## 政策模板

定义本地文件中提及 Cedar 语句的政策模板 :

```ts
const validationSettingsOff = {
  mode: ValidationSettingsMode.OFF,
};
const policyStore = new PolicyStore(scope, "PolicyStore", {
  validationSettings: validationSettingsOff,
});
const templateFromFileProps = {
  policyStore,
  path: '/path/to/template-statement.cedar',
  description: "Allows sharing photos in full access mode",
};
const template = PolicyTemplate.fromFile(scope, "PolicyTemplate", templateFromFileProps);
```

# 页:1

-   该项目遵循了AWS CDK 官方设计指南(参见: [https://github.com/aws/aws-cdk/blob/main/docs/DESIGN GUIDELINES.md. 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md))和 AWS CDK 新建构造创建指南(参见此处) [https://github.com/aws/aws-cdk/blob/main/docs/NEW CONSTRCUCTS GUIDE.md](https://github.com/aws/aws-cdk/blob/main/docs/NEW_CONSTRUCTS_GUIDE.md)) (中文(简体) ).
    
-   反馈是一种天赋:如果你发现有问题或有改进的想法,请打开一个问题或拉出请求

## 常见问题

### @cdklabs/cdk-verified-permissions 是什么？

L2 亚马逊验证权限的 AWS CDK 构造

### 如何安装 @cdklabs/cdk-verified-permissions？

在项目目录运行 npm install @cdklabs/cdk-verified-permissions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：aws-cdk-lib（^2\.260\.0）、constructs（^10\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdklabs/cdk-verified-permissions 支持 TypeScript 吗？

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

### @cdklabs/cdk-verified-permissions 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cdklabs/cdk-verified-permissions 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 18\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cdklabs/cdk-verified-permissions 可以商用吗？

@cdklabs/cdk-verified-permissions 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cdklabs/cdk-verified-permissions 的下载量有多少？

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

### @cdklabs/cdk-verified-permissions 还在维护吗？

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