feat: add rate limiting to prevent policy conflicts (#550)

feat(policy): Add throttling and resource conflict management

Implement intelligent dependency management for policy creation to
address CloudFormation limitations:

- Add getPolicyPropsFromFile helper to extract policy metadata including
principal, action, and resource from Cedar policies
- Refactor Policy.fromFile to use new helper function
- Enhance PolicyStore.addPoliciesFromPath with dependency management:
  * Group policies by resource with sequential dependencies
* Policies with same resource never created concurrently * Limit the
number of parallel resource creation streams to 5 by cfn dependency

This prevents CloudFormation throttling (10 TPS default limit) and
resource conflicts when creating multiple policies.

Co-authored-by: Victor Moreno <morevct@amazon.com>

Author: Swolebrain

API.md

@@ -1,5 +1,8 @@
 
+import * as fs from 'fs';
+import * as path from 'path';
 import * as cedar from '@cedar-policy/cedar-wasm/nodejs';
+import { PolicyProps } from './policy';
 export const POLICY_DESCRIPTION_ANNOTATION = '@cdkDescription';
 export const POLICY_ID_ANNOTATION = '@cdkId';
 
@@ -141,4 +144,74 @@ export function buildSchema(
       actions,
     },
   };
-}
+}
+
+export interface PolicyPropsFromFile {
+  principal: string;
+  action: string;
+  resource: string;
+  cdkId: string;
+  policyProps: PolicyProps;
+}
+
+/**
+ * Extracts policy properties from a Cedar policy file
+ * @param filePath Path to the Cedar policy file
+ * @param policyStore The policy store to associate policies with
+ * @param defaultPolicyId Default ID to use if not specified in annotations
+ * @param defaultDescription Optional default description
+ * @param enablePolicyValidation Whether to enable policy validation
+ * @returns Array of policy properties with parsed principal, action, resource
+ */
+export function getPolicyPropsFromFile(
+  filePath: string,
+  policyStore: any,
+  defaultPolicyId: string,
+  defaultDescription?: string,
+  enablePolicyValidation: boolean = true,
+): PolicyPropsFromFile[] {
+  const policyFileContents = fs.readFileSync(filePath).toString();
+  const relativePath = path.basename(filePath);
+  const policies = splitPolicies(policyFileContents);
+
+  return policies.map(policyContents => {
+    const parseResult = cedar.policyToJson(policyContents);
+    if (parseResult.type === 'failure') {
+      throw new Error(`Failed to parse policy: ${parseResult.errors.map((e: any) => e.message).join('; ')}`);
+    }
+
+    const policyJson = parseResult.json;
+    const annotations = policyJson.annotations || {};
+    const cdkId = annotations[POLICY_ID_ANNOTATION.substring(1)] || defaultPolicyId;
+    const description = annotations[POLICY_DESCRIPTION_ANNOTATION.substring(1)] || defaultDescription || `${relativePath} - Created by CDK`;
+
+    const stringifyEntity = (constraint: cedar.PrincipalConstraint | cedar.ActionConstraint | cedar.ResourceConstraint): string => {
+      if (constraint.op === 'All') {
+        return 'Unspecified';
+      }
+      if (!('entity' in constraint)) {
+        throw new Error(`Invalid constraint in policy ${policyContents} in file ${filePath}`);
+      }
+      const entityUid: cedar.EntityUidJson = constraint.entity;
+      const typeAndId = '__entity' in entityUid ? entityUid.__entity : entityUid;
+      return `${typeAndId.type}::"${typeAndId.id}"`;
+    };
+
+    return {
+      principal: stringifyEntity(policyJson.principal),
+      action: stringifyEntity(policyJson.action),
+      resource: stringifyEntity(policyJson.resource),
+      cdkId,
+      policyProps: {
+        definition: {
+          static: {
+            statement: policyContents,
+            description,
+            enablePolicyValidation,
+          },
+        },
+        policyStore,
+      },
+    };
+  });
+}

src/cedar-helpers.ts

@@ -5,7 +5,7 @@ import * as iam from 'aws-cdk-lib/aws-iam';
 import { CfnPolicyStore } from 'aws-cdk-lib/aws-verifiedpermissions';
 import { ArnFormat, IResource, Resource, Stack } from 'aws-cdk-lib/core';
 import { Construct } from 'constructs';
-import { buildSchema, checkParseSchema, cleanUpApiNameForNamespace, validateMultiplePolicies } from './cedar-helpers';
+import { buildSchema, checkParseSchema, cleanUpApiNameForNamespace, getPolicyPropsFromFile, validateMultiplePolicies } from './cedar-helpers';
 import { Policy, PolicyDefinitionProperty } from './policy';
 import {
   AUTH_ACTIONS,
@@ -14,6 +14,7 @@ import {
 } from './private/permissions';
 
 const RELEVANT_HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'];
+const SIMULTANEOUS_POLICY_CREATION_STREAMS = 5;
 
 export interface Tag {
   readonly key: string;
@@ -446,6 +447,7 @@ export class PolicyStore extends PolicyStoreBase {
    * .cedar file as policies to this policy store (searching recursively if needed).
    * Parses the policies with cedar-wasm and, if the policy store has a schema,
    * performs semantic validation of the policies as well.
+   * Organizes policies with dependencies to avoid CloudFormation throttling and resource conflicts.
    * @param absolutePath a string representing an absolute path to the directory containing your policies
    * @param recursive a boolean representing whether or not to search the directory recursively for .cedar files
    * @returns An array of created Policy constructs.
@@ -483,14 +485,46 @@ export class PolicyStore extends PolicyStoreBase {
       });
     }
 
-    const policies = policyFileNames.flatMap((cedarFile) =>
-      // Using base path of the file as default id for policy
-      Policy.fromFile(this, path.basename(cedarFile), {
-        path: cedarFile,
-        policyStore: this,
-      }),
+    const allPolicyProps = policyFileNames.flatMap(cedarFile =>
+      getPolicyPropsFromFile(cedarFile, this, path.basename(cedarFile), undefined, true),
     );
 
+    // Group policies by resource
+    const resourceGroups = new Map<string, typeof allPolicyProps>();
+    for (const props of allPolicyProps) {
+      const resourceKey = JSON.stringify(props.resource);
+      if (!resourceGroups.has(resourceKey)) {
+        resourceGroups.set(resourceKey, []);
+      }
+      resourceGroups.get(resourceKey)!.push(props);
+    }
+
+    // Create policies with dependencies
+    const policies: Policy[] = [];
+    const firstPolicyPerResourceGroup: Policy[] = [];
+
+    // First, handle policies within same resource groups (sequential dependencies)
+    for (const group of resourceGroups.values()) {
+      let previousPolicyInGroup: Policy | undefined;
+      for (const props of group) {
+        const policy = new Policy(this, props.cdkId, props.policyProps);
+        if (previousPolicyInGroup) {
+          policy.node.addDependency(previousPolicyInGroup);
+        } else {
+          firstPolicyPerResourceGroup.push(policy);
+        }
+        policies.push(policy);
+        previousPolicyInGroup = policy;
+      }
+    }
+
+    // Then, organize resource groups in batches to prevent throttling
+    // First SIMULTANEOUS_POLICY_CREATION_STREAMS resource groups can be created simultaneously
+    // Each subsequent resource group depends on the resource group SIMULTANEOUS_POLICY_CREATION_STREAMS positions earlier
+    for (let i = SIMULTANEOUS_POLICY_CREATION_STREAMS; i < firstPolicyPerResourceGroup.length; i++) {
+      firstPolicyPerResourceGroup[i].node.addDependency(firstPolicyPerResourceGroup[i - SIMULTANEOUS_POLICY_CREATION_STREAMS]);
+    }
+
     return policies;
   }
 }

src/policy-store.ts

@@ -1,9 +1,7 @@
-import * as fs from 'fs';
-import * as path from 'path';
 import { CfnPolicy } from 'aws-cdk-lib/aws-verifiedpermissions';
 import { IResource, Resource } from 'aws-cdk-lib/core';
 import { Construct } from 'constructs';
-import { checkParsePolicy, getPolicyDescription, getPolicyId, splitPolicies } from './cedar-helpers';
+import { checkParsePolicy, getPolicyDescription, getPolicyPropsFromFile } from './cedar-helpers';
 import { IPolicyStore } from './policy-store';
 import { IPolicyTemplate } from './policy-template';
 
@@ -204,36 +202,29 @@ export class Policy extends PolicyBase {
    * `PolicyStore.addPoliciesFromPath()`
    *
    * @param scope The parent creating construct (usually `this`).
-   * @param props A `StaticPolicyFromFileProps` object.
    * @param defaultPolicyId The Policy construct default id. This may be directly passed to the method or defined inside the file.
    *           When you have multiple policies per file it's strongly suggested to define the id directly
    *           inside the file in order to avoid multiple policy constructs with the same id. In case of id passed
    *           directly to the method and also defined in file, the latter will take priority.
+   * @param props A `StaticPolicyFromFileProps` object.
    */
   public static fromFile(
     scope: Construct,
     defaultPolicyId: string,
     props: StaticPolicyFromFileProps,
   ): Policy[] {
-    const policyFileContents = fs.readFileSync(props.path).toString();
-    let relativePath = path.basename(props.path);
-    let enablePolicyValidation = (props.enablePolicyValidation == undefined) ? true : props.enablePolicyValidation;
-    const policies = splitPolicies(policyFileContents);
-    const policyDefinitions = policies.map(policyContents => {
-      let policyId = getPolicyId(policyContents) || defaultPolicyId;
-      let policyDescription = getPolicyDescription(policyContents) || props.description || `${relativePath}${POLICY_DESC_SUFFIX_FROM_FILE}`;
-      return new Policy(scope, policyId, {
-        definition: {
-          static: {
-            statement: policyContents,
-            description: policyDescription,
-            enablePolicyValidation: enablePolicyValidation,
-          },
-        },
-        policyStore: props.policyStore,
-      });
-    });
-    return policyDefinitions;
+    const enablePolicyValidation = props.enablePolicyValidation ?? true;
+    const policyPropsArray = getPolicyPropsFromFile(
+      props.path,
+      props.policyStore,
+      defaultPolicyId,
+      props.description,
+      enablePolicyValidation,
+    );
+
+    return policyPropsArray.map(({ cdkId, policyProps }) =>
+      new Policy(scope, cdkId, policyProps),
+    );
   }
 
   readonly policyId: string;

src/policy.ts

@@ -0,0 +1,109 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Stack } from 'aws-cdk-lib';
+import { PolicyStore, ValidationSettingsMode } from '../src/policy-store';
+
+describe('Policy Dependencies', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync('/tmp/test-policies-');
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true });
+    }
+  });
+
+  test('policies with same resource have sequential dependencies', () => {
+    // Create policies with same resource
+    fs.writeFileSync(
+      path.join(testDir, 'policy1.cedar'),
+      'permit(principal, action, resource == Photo::"vacation.jpg");',
+    );
+    fs.writeFileSync(
+      path.join(testDir, 'policy2.cedar'),
+      'permit(principal, action, resource == Photo::"vacation.jpg");',
+    );
+
+    const stack = new Stack();
+    const policyStore = new PolicyStore(stack, 'PolicyStore', {
+      validationSettings: { mode: ValidationSettingsMode.OFF },
+    });
+
+    const policies = policyStore.addPoliciesFromPath(testDir);
+
+    expect(policies.length).toBe(2);
+    // Second policy should depend on first
+    expect(policies[1].node.dependencies.length).toBeGreaterThan(0);
+  });
+
+  test('policies are organized in resource group batches', () => {
+    // Create 12 policies with different resources (12 resource groups)
+    for (let i = 0; i < 12; i++) {
+      fs.writeFileSync(
+        path.join(testDir, `policy${i}.cedar`),
+        `permit(principal, action, resource == Photo::"photo${i}.jpg");`,
+      );
+    }
+
+    const stack = new Stack();
+    const policyStore = new PolicyStore(stack, 'PolicyStore', {
+      validationSettings: { mode: ValidationSettingsMode.OFF },
+    });
+
+    const policies = policyStore.addPoliciesFromPath(testDir);
+
+    expect(policies.length).toBe(12);
+
+    // First 5 resource groups should have no dependencies (can be created simultaneously)
+    for (let i = 0; i < 5; i++) {
+      const deps = policies[i].node.dependencies.filter(
+        d => d.node.id !== 'PolicyStore',
+      );
+      expect(deps.length).toBe(0);
+    }
+
+    // Each resource group after the first 5 depends on the resource group 5 positions earlier
+    // Resource group 5 depends on resource group 0
+    expect(policies[5].node.dependencies.some(d => d === policies[0])).toBe(true);
+
+    // Resource group 6 depends on resource group 1
+    expect(policies[6].node.dependencies.some(d => d === policies[1])).toBe(true);
+
+    // Resource group 10 depends on resource group 5
+    expect(policies[10].node.dependencies.some(d => d === policies[5])).toBe(true);
+
+    // Total number of dependencies should be numPolicies - SIMULTANEOUS_POLICY_CREATION_STREAMS
+    const SIMULTANEOUS_POLICY_CREATION_STREAMS = 5;
+    const totalDeps = policies.reduce((count, policy) => {
+      return count + policy.node.dependencies.filter(d => d.node.id !== 'PolicyStore').length;
+    }, 0);
+    expect(totalDeps).toBe(policies.length - SIMULTANEOUS_POLICY_CREATION_STREAMS);
+  });
+
+  test('policies with annotations use correct cdkId and description', () => {
+    fs.writeFileSync(
+      path.join(testDir, 'annotated1.cedar'),
+      '@cdkId("CustomId1")\n@cdkDescription("Custom description 1")\npermit(principal, action, resource);',
+    );
+    fs.writeFileSync(
+      path.join(testDir, 'annotated2.cedar'),
+      '@cdkId("CustomId2")\n@cdkDescription("Custom description 2")\npermit(principal, action, resource);',
+    );
+
+    const stack = new Stack();
+    const policyStore = new PolicyStore(stack, 'PolicyStore', {
+      validationSettings: { mode: ValidationSettingsMode.OFF },
+    });
+
+    const policies = policyStore.addPoliciesFromPath(testDir);
+
+    expect(policies.length).toBe(2);
+    expect(policies[0].node.id).toBe('CustomId1');
+    expect(policies[0].definition.static?.description).toBe('Custom description 1');
+    expect(policies[1].node.id).toBe('CustomId2');
+    expect(policies[1].definition.static?.description).toBe('Custom description 2');
+  });
+});