fix(dynamodb): resolve circular dependency with AccountRootPrincipal grants

[pahud]

Issue # (if applicable)

Closes #35967.

Reason for this change

In CDK 2.222.0, PR #35554 fixed addToResourcePolicy() to actually work (it was previously a no-op). This exposed a circular dependency issue when using grantReadData() or other grant methods with AccountRootPrincipal.

When AccountRootPrincipal is used with grant methods, the IAM Grant system adds the policy to the table's resource policy (since it's in the same account). The resource policy statement included the table's ARN (!GetAtt Table.Arn), creating a circular dependency: Table → ResourcePolicy → Table.Arn → Table.

This is a regression that breaks existing user code that worked in 2.221.1.

Description of changes

Applied the established KMS grant pattern to DynamoDB by adding resourceSelfArns: ['*'] parameter to Grant.addToPrincipalOrResource() calls in the combinedGrant method.

How it works:

• resourceArns contains actual table ARNs → used for principal policies (IAM user/role policies)
• resourceSelfArns: ['*'] → used for resource policies (table's resource policy)
• IAM Grant system automatically chooses which to use based on context
• No circular dependency because resource policy uses wildcard instead of !GetAtt Table.Arn

Why wildcard is safe:

• Wildcard is scoped to the table's resource policy (not global)
• Resource policy is attached to specific table resource
• Principal and Action fields still enforce access control
• Same pattern used by KMS for years in production

Files modified:

• packages/aws-cdk-lib/aws-dynamodb/lib/table.ts - Added resourceSelfArns: ['*'] to combinedGrant method
• packages/aws-cdk-lib/aws-dynamodb/lib/table-v2-base.ts - Applied identical change for Table V2
• packages/aws-cdk-lib/aws-dynamodb/README.md - Added documentation about grant methods and resource policy interaction

Before (causes circular dependency):

const table = new dynamodb.Table(this, 'Table', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
});

// This caused circular dependency error in 2.222.0
table.grantReadData(new iam.AccountRootPrincipal());
// Error: Circular dependency between resources: [Table]

After (no circular dependency):

const table = new dynamodb.Table(this, 'Table', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
});

// This now works correctly
table.grantReadData(new iam.AccountRootPrincipal());
// ✓ Resource policy uses wildcard, no circular dependency

CloudFormation template change:

{
  "Resources": {
    "Table": {
      "Type": "AWS::DynamoDB::Table",
      "Properties": {
        "ResourcePolicy": {
          "PolicyDocument": {
            "Statement": [{
              "Action": ["dynamodb:BatchGetItem", "dynamodb:GetItem", "dynamodb:Query", "dynamodb:Scan"],
              "Effect": "Allow",
              "Principal": { "AWS": "arn:aws:iam::ACCOUNT:root" },
              "Resource": "*"
            }]
          }
        }
      }
    }
  }
}

Describe any new or updated permissions being added

N/A - This fix does not add new permissions. It resolves how existing grant methods generate resource policies to avoid circular dependencies.

Description of how you validated changes

• Unit tests: Added 2 new tests validating AccountRootPrincipal with grant methods

  • packages/aws-cdk-lib/aws-dynamodb/test/dynamodb.test.ts: Test for Table V1
  • packages/aws-cdk-lib/aws-dynamodb/test/table-v2.test.ts: Test for Table V2
  • Both tests verify resource policy uses wildcard (*) to avoid circular dependency
  • All 348 unit tests pass (346 existing + 2 new)

• Integration tests: Enhanced existing integration test with grant scenario

  • packages/@aws-cdk-testing/framework-integ/test/aws-dynamodb/test/integ.dynamodb.add-to-resource-policy.ts
  • Added TEST 3: Validates grantWriteData(new AccountRootPrincipal()) works without circular dependency
  • Successfully deployed to AWS (us-east-1)
  • CloudFormation synthesis succeeds, no circular dependency errors
  • Snapshots updated with GrantTable resource

• Regression testing: All 346 existing tests pass

  • Grant methods with IAM Users still work
  • Grant methods with IAM Roles still work
  • Grant methods with Service Principals still work
  • Tables with indexes work correctly
  • Global tables (Table V2) work correctly
  • Encrypted tables work correctly

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[Abogical]

Thanks! I've asked for another reviewer to this.

[mergify]

Thank you for contributing! Your pull request will be automatically updated and merged (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

This pull request has been removed from the queue for the following reason: pull request branch update failed.

The pull request can't be updated

For security reasons, Mergify can't update this pull request. Try updating locally.
GitHub response: refusing to allow a GitHub App to create or update workflow .github/workflows/integration-test-deployment.yml without workflows permission.

You should update or rebase your pull request manually. If you do, this pull request will automatically be requeued once the queue conditions match again.
If you think this was a flaky issue, you can requeue the pull request, without updating it, by posting a @mergifyio requeue comment.

[mergify]

Thank you for contributing! Your pull request will be automatically updated and merged (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be automatically updated and merged (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.